> For the complete documentation index, see [llms.txt](https://docs.uxwizz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uxwizz.com/guides/migrating-to-a-new-server.md).

# Migrating to a new server

Move the database, application files, and private runtime configuration together. Keep the same UXWizz version during the move; update separately after the migration is verified.

You need administration access to both servers and your DNS. Check the destination against the [requirements](/installation/requirements.md). For Agency multi-database installations, include **every analytics database and the main database**.

### 1. Migrate the MySQL database

#### 1.1 Backup the current database

1. Record the installed version, application path, database names, PHP service user, and task-runner setup.
2. Take a complete backup before deleting or changing any data. Store it outside the web root with restricted access.
3. Prepare a maintenance window for the final copy. Pause writes and old-server task runners during that copy so the two servers do not diverge.
4. Export a consistent database backup with your hosting tool or the database's own dump utility.

For an InnoDB database named `uxwizz`, this MySQL example prompts for the password. Run it from a private backup directory and replace the database username and name as needed:

```bash
umask 077
mysqldump --single-transaction --quick --hex-blob --no-tablespaces --user=uxwizz --password uxwizz > uxwizz.sql
```

Check the command's exit status and output before continuing. On MariaDB, use `mariadb-dump`. Your database administrator must account for any non-InnoDB tables, ongoing schema changes, or extra databases. Test the restore; a nonempty file alone is not proof of a usable backup.

#### 1.2 Copy the .sql.gz file to the new server

You can compress the checked SQL file while keeping the original:

```bash
gzip -c uxwizz.sql > uxwizz.sql.gz
```

Transfer it with SFTP or SCP to a private directory on the destination. Do not upload a database backup to a public web folder.

#### 1.2.1 Generate new SSH key

Use your existing authorized SSH access when possible. If a new key is required, create a dedicated key without overwriting an existing one. Add only its public key to the destination account and verify the server's host-key fingerprint before accepting the connection.

Use an account with the permissions needed for the transfer. Password authentication can also work if your server permits it.

For a dedicated migration key, run this on the original server. Choose a different filename if it already exists:

```bash
ssh-keygen -t rsa -b 4096 -f ~/.ssh/uxwizz_migration
ssh-copy-id -i ~/.ssh/uxwizz_migration.pub your-user@new-server
```

Set a passphrase when prompted. `ssh-copy-id` adds the public key to the destination account's `~/.ssh/authorized_keys`; it needs existing login access. If it is unavailable, add the contents of `uxwizz_migration.pub` as a new line through your hosting console, keeping the existing lines. Never transfer the private key.

With this key, add `-i ~/.ssh/uxwizz_migration` to the SCP commands below. After verification, remove only this temporary public-key entry from the destination if it is no longer needed.

#### 1.2.2 Copy the backup file

Create a private `uxwizz-migration` directory in the destination account's home folder first. Replace the account and hostname:

```bash
scp uxwizz.sql.gz your-user@new-server:~/uxwizz-migration/
```

Compare file checksums on both servers before restoring.

#### 1.3 Import the new database

Create an **empty** destination database and a dedicated application user with privileges on that database. Do not import a full backup over a database that already contains new tracking data; see [Import SQL data on an existing server](/import-sql-data-on-an-existing-server.md).

For an intended new database named `uxwizz`, an administrator can run:

```sql
CREATE DATABASE uxwizz CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```

If that name already exists, inspect it; do not drop it to make the command succeed. To inspect the original application's account privileges, connect as that account on the old server and run:

```sql
SELECT CURRENT_USER();
SHOW GRANTS;
```

Create the corresponding dedicated account through the destination host's database tools and grant it access to the new database. Match the connecting host and database names. Server-wide account exports can include unrelated users and password hashes; they are not needed for a single-application move.

From the private destination directory:

```bash
gzip -dk uxwizz.sql.gz
mysql --user=uxwizz --password uxwizz < uxwizz.sql
```

Use `mariadb` for a MariaDB client. Check for import errors and verify the restored tables. Create the required database account on the destination; do not blindly copy all server users or global grants from the old server.

### 2. Copy the UXWizz folder

Copy the complete application to a dedicated destination directory, including hidden files and `server/storage`. Do not run a fresh installer over the restored application and database.

For example, with the source application in `/var/www/html` and an empty private staging directory on the destination:

```bash
scp -r /var/www/html your-user@new-server:~/uxwizz-migration/
```

Copying the directory itself includes its hidden files. Check `html/.htaccess` and `html/server/storage` on the destination. Have its administrator move the staged application to the intended server path and set ownership; do not copy it over an unrelated website.

Also transfer the private configuration that lives outside the application:

* The environment file, such as `/etc/uxwizz/uxwizz.env`, or your hosting platform's equivalent.
* The existing `UXWIZZ_APP_KEY` and any file-based application key. Changing the key can make encrypted settings unreadable.
* Database connection settings, including Agency domain databases.
* The virtual host or reverse-proxy configuration and HTTPS setup.
* The scheduled-task setup: systemd units/timers, cron entries, Docker Compose files, or WordPress cron configuration.

Keep secrets private. Set ownership for the destination PHP service user, and check the [environment overrides](/guides/environment-settings.md) if database connection values change. Do not reuse another server's user IDs or blanket permission commands.

### 3. Point your domain name to new server

1. Test the destination with the real hostname using a controlled DNS/hosts override. Check HTTPS, sign-in, historical reports, a recording, and access to each domain.
2. Complete the final consistent data copy during the maintenance window.
3. Change DNS to the destination IP. Keep the previous DNS values and old server available for rollback.
4. Open the normal dashboard URL, make a test visit on a tracked site, and confirm new data arrives.
5. Enable task runners only on the active server and check **Settings → Scheduled Tasks**.
6. Keep the old backup and server until the new installation and backups are verified. Plan how to preserve any new data before rolling back.

Keeping the same public dashboard URL normally avoids a tracking-code change. If the public URL must change, plan redirects and update tracking snippets and integrations before retiring the old endpoint.