Migrate to a new server#

Migration moves an existing Reportworq instance to different hardware while keeping its full state: jobs, schedules, contacts, datasources, settings, and stored credentials. Because that state lives in the Repository folder, a migration is fundamentally: install the same product on the new server, then replace its fresh Repository with the old one, done in the right order, with the service stopped at the swap.

The procedure below is written for a server-to-server move on Windows or Linux, which is the same shape on both: install, stop the service, swap the Repository, start. Only the paths and the service manager differ, and both are called out where they matter.

Container deployments do not migrate this way at all. A Docker or Azure App Service deployment keeps its state on a mounted repository, so you move it by pointing a new deployment at that same repository. There is no folder to swap. See Deployment topology.

Before you begin#

• A new server that meets the system requirements, on either Windows or Linux.
• Administrator rights on both servers.
• Your license key, and connectivity to the licensing service (or the manual activation path). Optionally, a non-production license key if you want to test the move before cutting over, see Move the license.
• A maintenance window.

Tip: before you migrate, run the repository metadata report on the old instance. It exports the whole distribution configuration to a spreadsheet, giving you an inventory to check the migrated instance against.

Where the Repository lives#

The Repository is the single folder that holds the instance's state. On Windows it sits under the install folder at C:\Program Files\Reportworq 6\Repository by default; on Linux it sits under the install root alongside settings.json. If it was relocated (Settings > Configuration > Web Server, Repository path), copy it from wherever it actually lives, not the default. Everything except the license and locally-stored report templates travels inside this folder.

Migration procedure#

Follow these steps in order. The order matters, swapping the Repository while the service is running risks corrupting it.

1. Copy the Repository folder from the old server (default C:\Program Files\Reportworq 6\Repository) to safe storage. This carries all instance state.
2. Document the service identity on the old server: the Bootstrap Service logon account on Windows (Local System or a specific domain account), or the user the systemd unit runs as on Linux. You must reproduce it on the new server or network access will break.
3. Install Reportworq on the new server using the same installer, see Install Reportworq. This creates a fresh, empty Repository.
4. Stop Reportworq on the new server. On Windows that is the Reportworq 6 Bootstrap Service (services.msc); on Linux, stop the systemd unit.
5. Reproduce the service identity on the new server and its file permissions, see Install Reportworq. On Windows, match the Bootstrap Service logon account if it was a domain account rather than Local System; on Linux, match the user the systemd unit runs as.
6. Replace the Repository. Delete the freshly generated Repository folder on the new server and put the copied old Repository folder in its place.
7. Start the service.
8. Sign in and validate. Check jobs, schedules, datasource connections, and run a test job.

Warning: always stop the service, then swap, then start. Replacing the Repository folder while the Bootstrap Service is running risks file conflicts and store corruption, because the running instance holds locks and may write over the swap.

Move the license#

The license is not part of the Repository swap.

Standard move#

1. On the old server, open Settings > Configuration > License and select Release to return the seat.
2. On the new server, Activate with the same key (or use Manual activation if the server is air-gapped).

Warning: migrating without releasing first can strand the seat. See Licensing and entitlements.

Test with a non-production license key first#

If you want to validate the new server while the old one keeps running, request a non-production license key from Reportworq support and activate the new server with it. This lets you prove the migrated instance, its jobs, schedules, and connections, without taking the production instance offline. When you are ready to sunset the old server:

1. Release the non-production key on the new server.
2. Release the production license on the old server.
3. Activate the new server with the production key.

Things that do not travel in the Repository#

• Locally-stored report templates. Reports served from a local file path on the old server (a source report provider pointing at a local folder) are not inside the Repository. Copy them to the new server separately, or re-point the provider, or those reports are lost. This is the same rule that governs installation: sources must be reachable by the service account.
• The service logon account. If the old instance ran jobs under a domain account with rights to network shares, the new instance must use the same identity (or an equivalent), otherwise jobs that read or write network paths fail after the move even though the Repository is intact.

What is portable#

Encrypted credentials travel with the Repository. Passwords and connection strings are encrypted with a portable static key (not tied to the Windows machine), so the ciphertext in the migrated Repository decrypts on the new server with no re-entry.

Move a subset of content instead#

To move individual jobs or folders between instances rather than the whole instance, use content-level Export/Import ("Send to") instead of a Repository swap:

1. In the source instance, open the workspace and select the job or folder to move.
2. Use Send to (or Export) to package the content, or send it directly to the destination workspace or installation.
3. In the target instance, import the content into the destination workspace.
4. Reconnect any data sources or providers the imported content depends on, then run a test job to confirm it works on the new instance.

Use this for a partial move; use the full procedure above to move the whole instance. For the detailed content-move steps, see Workspaces.

Decommission the old server#

Once the new server is validated and the license has moved, retire the old instance:

1. Release the old server's license if you have not already (Settings > Configuration > License, Release).
2. Uninstall Reportworq from Windows Add/Remove Programs > Uninstall, see Install Reportworq.

Warning: some files remain after uninstall. Do not delete the residual files if there is any chance you will need to migrate again, they hold Repository and configuration state.

Notes and limits#

• Migration as described here is a server-to-server move, on Windows or Linux. Container deployments are relocated instead by re-pointing a new deployment at the mounted repository, see Deployment topology.

Going deeper. The backup-and-restore-into-Repository path is the recovery-style variant of this move, see Update Reportworq and Server configuration.