Migrate to a new server#

Applies from the release after 6.0.2.40. The automatic re-activation and the deployment name described here arrive in the first Reportworq release after version 6.0.2.40. On 6.0.2.40 and earlier, the license is tied to the server's machine name, so a move to a server with a different name may need you to enter your key again on the new server.

Migration moves an existing Reportworq instance to different hardware while keeping its full state: jobs, schedules, contacts, datasources, settings, and stored credentials. All of that lives in the Repository folder, so a migration is fundamentally: install the same product on the new server, point it at a copy of the old Repository, then retire the old server once the new one is confirmed working. Your license comes along too, with one step on first start: the new server re-activates it (see Moving to a new server re-activates the license).

The procedure below is for a server-to-server move on Windows or Linux. It is the same shape on both: stop the old server, copy the Repository, install, bring the Repository across, 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 copy. Set a deployment name on it first, because a container's host name changes every time it is recreated. See Deployment topology.

Before you begin#

• A new server that meets the system requirements, on either Windows or Linux.
• Administrator rights on both servers.
• The same Reportworq version on both servers. Bring the new server up to the old one, never the old one down: if you want a newer version, update the old server first with Update Reportworq, and then install that same version on the new server.
• A maintenance window.

Have your license key ready. The new server re-activates automatically using the key carried in the Repository, and needs internet access to the licensing service to do it, but if that fails you enter the key again (see Moving to a new server re-activates the license). An offline server needs Manual activation.

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.

What travels with the Repository#

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 the tarball installer seeds it at /var/lib/reportworq/repository. If it was relocated (Settings ▸ Configuration ▸ Web Server, Repository Path), copy it from wherever it actually lives, not the default.

Some things do not travel and are covered under Things that do not travel: the service logon account, report templates stored outside the Repository, and your Microsoft Entra app registration.

Migration procedure#

Follow these steps in order.

1. Stop the old service and keep it stopped. On Windows, stop the Reportworq 6 Bootstrap Service in services.msc and set its Startup type to Disabled, so that a restart of the machine does not bring it back. On Linux, run sudo systemctl stop reportworq and then sudo systemctl disable reportworq. From here on, only one server may run against this Repository: two running copies would both run the same schedules and send every scheduled distribution twice.
2. Copy the Repository folder from the old server to safe storage. The old service is stopped, so the copy is consistent. This carries all instance state.
3. 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.
4. Install Reportworq on the new server, the same version, using the same installer, see Install Reportworq. This creates a fresh, empty Repository. Do not activate a license on it: the new server re-activates automatically, using the key carried in your copied Repository, when it first starts against that Repository.
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. On Windows, if you use Route B, point the new install at the copy now, while its service is running, see Route B. The product restarts the service against the copy for you. Then go to step 9.
7. Otherwise, stop Reportworq on the new server. On Windows that is the Reportworq 6 Bootstrap Service (services.msc); on Linux, run sudo systemctl stop reportworq.
8. Bring the Repository in and start the service. Use Route A on Windows or Linux, or Route B on Linux, then start the service. The first start re-activates the license (see below).
9. Update the Web App Host, then validate: check jobs, schedules, datasource connections, and run a test job.
10. Retire the old server once you are satisfied. See Retire the old server.

Warning: never replace, move, or edit the files of a Repository while a Reportworq service is running against it. The running instance holds locks and may write over your change or corrupt the store. That is why Route A, and Route B on Linux, stop the service first. Changing the Repository Path setting in the product (Route B on Windows) is different: the new path takes effect only when the service restarts, so it is safe to change it while the service runs.

Route A: replace the new Repository folder#

This is the simplest route and keeps the default path. It works on Windows and Linux, with the new server's service stopped (step 7).

1. Delete the freshly generated Repository folder on the new server (C:\Program Files\Reportworq 6\Repository on Windows, /var/lib/reportworq/repository on Linux, by default).
2. Put the copied Repository folder in its place, at the same location.
3. Make sure the service identity can read and write it. On Linux, the service runs as the reportworq user, so give the copy to that user: sudo chown -R reportworq: /var/lib/reportworq/repository. On Windows, grant the service account from step 6 read and write access if it is not Local System.

Route B: leave the copy where it is and change the Repository Path#

Use this when the copy lives somewhere else, for example a data disk or a share.

• Windows, with the service running (step 6).
  • A fresh install that has not finished setup opens the first-run wizard when you browse to it. On its Repository step choose Connect to an existing repository and give the full path of the copied folder. The wizard applies it and restarts the service, with no license step, see First-run setup. Do not choose Create a new repository, which goes on to activate a license on an empty store.
  • An install that has already finished setup: open Settings ▸ Configuration ▸ Web Server. Either select Reconfigure on that card, which reopens the same repository choices, or set Repository Path to the full path of the copied folder, save, and select Restart. A caption under the field, Currently using followed by a path, shows the folder the running process is really bound to. It does not change until the restart, so check it after the service comes back.
• Linux, with the service stopped (step 7). The tarball installer keeps the repository location as RepositoryPath in /opt/reportworq/settings.json (seeded to /var/lib/reportworq/repository). Change it there to the full path of the copy. If RW_REPOSITORY_PATH is set (uncommented) in /etc/reportworq/reportworq.env, that override wins at every start, so change or comment it out instead. The service runs as the reportworq user, so give the copy to that user: sudo chown -R reportworq: <path-to-copy>.
• Give the service account access. Whatever path you choose, the service identity from step 5 needs read and write access to it.

In a load-balanced deployment the Repository must be a network share reachable by every node. Point every node at the same share, see If you run more than one node.

Moving to a new server re-activates the license#

The license identity belongs to the deployment: one web app, its Repository, and any load-balanced nodes. The identity is the deployment name, which is the server's machine name unless you set one (see Deployment name).

A Repository copied to a server with a different name is a new deployment. On its first start, Reportworq:

1. Carries your license key and contact details forward from the copied Repository.
2. Re-activates once with the licensing service. This needs internet access from the new server, and it may use an installation seat. If no seat is free, contact support.

If the automatic attempt fails permanently, you see the normal activate prompt at Settings ▸ Configuration ▸ License: enter your key and activate. A server with no internet access uses Manual activation. Re-activation is routine, and the licensing service also re-validates a stored license about every 12 months.

The same name means no re-activation. If you rebuild under the same machine name, or give the new server the same deployment name, the activation carries over untouched.

A copy that keeps running needs its own name. If you clone production to make a development or test server and leave both running, give the copy a different deployment name. Two copies of one Repository running under the same name share one activation.

You can confirm the state at Settings ▸ Configuration ▸ License, which shows the license status and details. Keep the old service stopped after cutover (step 1) so that it does not run the same schedules and send the same distributions.

Deployment name#

The deployment name is what identifies your license. By default it is the machine name of the server that runs the web app. To set it yourself, use either of these:

• The RW_DEPLOYMENT_NAME environment variable.
• The DeploymentName setting in settings.json.

If both are set, the environment variable wins. Leave it blank to use the machine name. Set one in these cases:

• Containers (Docker or Azure App Service). The host name changes whenever the container is recreated, so set RW_DEPLOYMENT_NAME to keep the license steady. The shipped Docker Compose and Azure templates already set it. Without it, a container keeps the first identity it was given and never changes it, so it does not notice a copied Repository until you set a name. Setting a name on an existing container deployment is itself a deployment change, and re-activates once.
• A clone of production. Give the copy a different name from the original.

A server with a stable machine name, such as a Windows server or a Linux virtual machine from the tarball, does not need one. Renaming that server is a new deployment, so expect one automatic re-activation.

Update the Web App Host#

Reportworq keeps its own address in the settings that travel with the Repository, so after a move the Web App Host still names the old server.

1. Sign in to the new server and open Settings ▸ Configuration ▸ Web Server.
2. Set Web App Host to the machine name, IP address, or DNS name that other machines use to reach the new server.
3. If the address that recipients use in links differs from that (a reverse proxy or a friendly DNS name), also set External URL. See Server configuration.
4. Select Save Changes.

If the new server keeps the old server's DNS name, the value may already be right. Set it explicitly anyway, so it no longer depends on a machine name.

If you run more than one node#

A load-balanced deployment has several nodes reading one shared Repository, so they are one deployment and share one license identity. That is the expected design, not a sign that the license has been duplicated. You do not activate each node separately. Only the main web server activates; the other nodes read the result.

To migrate a cluster:

1. Stop every node, old and new, and move the shared Repository once.
2. Start only the main web server against the share, and set its Web App Host (see Update the Web App Host).
3. Only then point the other nodes at the share and start them. The other nodes reach the main web server through the Web App Host address, so starting them before it is updated sends them to the old server.
4. Restart every node after any deployment change (a new server name, or a new deployment name). A node that was already running keeps the old identity until it restarts, so it reports the license as missing.

Things that do not travel#

• 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.

• The Azure (Entra ID) app registration's redirect URIs. If the instance uses Microsoft Entra sign-in or any Microsoft 365 feature, its Azure app registration lives in your tenant, not in the Repository, and its redirect URIs are tied to the old server's advertised address. When the new server has a different address, add the new server's :8600 URLs to the registration under Authentication ▸ Web, alongside the existing ones, or Entra sign-in and every Microsoft 365 feature (email, SharePoint, and Teams distribution, and email data collection) will fail after the move:

  • https://<new-host>:8600/signin-oidc
  • https://<new-host>:8600/server/v0/get-office365-smtp-token
  • https://<new-host>:8600/server/v0/get-office365-sharepoint-token

  Replace <new-host> with the new server's advertised host, and adjust the port if you changed it from the 8600 default. If the new server keeps the old address, the existing URIs still match and no change is needed. See Microsoft 365 OAuth setup.

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 bringing a Repository across:

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.

Roll back#

Until you retire the old server, going back is quick, because the old Repository was copied, not moved:

1. Stop the service on the new server and keep it stopped (on Windows set its Startup type to Disabled; on Linux run sudo systemctl disable reportworq).
2. Re-enable and start the service on the old server (on Windows set its Startup type back to Automatic and start it; on Linux run sudo systemctl enable --now reportworq). Its Repository is exactly as you left it. Re-activation is routine, so if the old server asks to activate, enter your key. If no seat is free, contact support.
3. Re-point anything you changed to the new address (DNS, firewall rules, Entra redirect addresses) back to the old one.

Anything that happened on the new server after cutover (job runs, edits, new schedules) exists only in the new Repository. If you need it, copy the new server's Repository back over the old one, with both services stopped, before you start the old server.

Retire the old server#

Once the new server is validated, retire the old instance so that only one server runs against the Repository:

1. Keep the service on the old server stopped and disabled (step 1), and do not start it again.
2. Keep the old Repository copy for as long as you want a rollback path.
3. When you are ready to remove the software, uninstall Reportworq, see Install Reportworq. A move needs no Release on the old server, so the uninstall page's Release step does not apply here: Release needs the old service running, which would duplicate your schedules and distributions. To return an installation seat, contact support. Leave the residual files in place until you are sure you will not need them.

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.
• Do not run the old and the new server against production at the same time. If you keep both running as separate environments, give the copy its own deployment name.

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