Migration to a New Server

When you replace server hardware or move OptimiDoc to a new virtual machine, you migrate the installation while preserving the database, configuration and device connections. There is one extra consideration that catches people out: OptimiDoc encrypts stored secrets with a machine-bound key, so a straight copy of the database and files is not enough on new hardware — you must also recover the encryption keys. This guide covers the whole move, with that step called out where it belongs.

Read First — The Encryption Key Caveat

OptimiDoc protects stored credential and destination secrets (connector passwords, mailbox credentials, connection strings) with a Master Encryption Key (MEK). The MEK is itself protected with Windows DPAPI bound to the local machine. That binding is the whole point of the caveat:

• On new hardware, the copied MEK cannot be unwrapped — DPAPI on the new machine cannot read a blob sealed by the old machine. Encryption fails to initialise and the log shows "Cannot decrypt MEK. If this is a new server, use disaster recovery or join an existing cluster node."

• When encryption cannot initialise, OptimiDoc cannot decrypt its stored secrets — and because the administrator credentials are among those secrets, you may not even be able to log in normally.

• This applies whether or not the database itself moves — it is about the server's machine identity, not the database location. Even if the new server points at the same remote SQL Server, it is still a new machine and still needs the keys recovered.

There are exactly two supported ways to bring the keys across:

1. Recovery key (.odrk) — download it from the old server before the move, then upload it on the new server. This is the standard path for replacing a standalone server. Covered in Step 4 below.

2. Cluster re-join — if a live cluster peer still exists, the new node bootstraps the MEK from that peer automatically when it joins the cluster; no recovery key is needed. See Failover Architecture.

Do this before you touch anything: on the old server, open the Encryption page (/encryption, administrators only) and click Download Recovery Key. This saves an .odrk file and writes a matching recovery record into the database (which then travels with your database backup). Store the .odrk file somewhere safe and separate — you will need it in Step 4. You can re-download it at any time while the old server is still running.

Migration Overview

1. Install the same OptimiDoc version on the new server.

2. Copy the configuration and licence from the old server.

3. Point the new server at the database (existing remote SQL Server, or move the database).

4. Recover the encryption keys on the new server.

5. Update DNS or IP so devices and clients reach the new server.

6. Verify, then decommission the old server.

Prerequisites

• The new server meets the OptimiDoc system requirements (Windows Server, IIS, .NET Framework).

• Network connectivity from the new server to the database (if SQL Server is remote) and to all multifunction devices.

• Administrator access to both the old and new servers.

• The encryption recovery key (.odrk) downloaded from the old server (see the callout above), unless you are re-joining a running cluster.

• You know the exact version running on the old server — check the System Info dashboard widget.

Step 1 — Install OptimiDoc on the New Server

1. Install the same version of OptimiDoc that runs on the old server. Matching versions is essential before restoring a database.

2. Do not start the application yet — stop the OptimiDoc site in IIS and the OptimiDoc Service after installation.

Step 2 — Copy Configuration and Licence

Copy the following from the old server to the new one, overwriting the fresh-install equivalents:

Step 3 — Configure the Database Connection

Using a remote SQL Server (recommended):

1. In web.config, confirm the OptimiDoc.Dao.OptimiDocDbContext connection string still points at the correct SQL Server. No change is needed if the database server has not moved.

2. Ensure the new server's service/application-pool account can reach and authenticate to the database.

3. If you use quotas, do the same for the OptimiDoc.Dao.QuotaDbContext connection string.

Moving a LocalDB database with the server:

1. Copy the optimidocX.mdf / .ldf files (and optimidocQ if you use quotas) from the old server's App_Data to the new server, and adjust the connection string paths if they differ.

Moving to a new SQL Server at the same time:

1. Follow LocalDB to SQL Server to restore the database and repoint the connection string.

Step 4 — Recover the Encryption Keys

With the database and configuration in place but the application still not logged in, restore the encryption keys on the new machine:

1. Browse to the Recover Encryption Keys page at /recover-encryption on the new server. This page is deliberately reachable without logging in, because encryption must be restored before a normal login can succeed.

2. Upload the .odrk recovery key file you downloaded from the old server.

3. OptimiDoc validates the file against the recovery record in the database, restores the MEK, and re-seals it under the new machine's DPAPI so future restarts work normally. It then reloads the data keys.

4. You can now log in as administrator; stored connector and mailbox secrets decrypt correctly.

If you are re-joining a cluster instead: skip the recovery-key upload. When the new node joins an existing cluster with a live peer, it obtains the MEK from that peer automatically during bootstrap. The recovery key is only required when no surviving cluster node is available.

Belt and braces: the Encryption page also offers Export Encryption Keys, which downloads all key records from the database as JSON. Keeping that export alongside the .odrk gives you a second copy of the key material for your records.

Step 5 — Update DNS or IP References

Devices and clients reach OptimiDoc by DNS name or IP address; point those at the new server.

• Update DNS (preferred). Repoint the OptimiDoc hostname to the new server's IP. Lower the DNS TTL ahead of the move to speed propagation. Devices then reconnect automatically.

• Reuse the old IP. Release the IP on the old server and assign it to the new one — no device reconfiguration needed.

• Update device URLs individually. If neither is possible, update each device's server URL (or reinstall its agent) from the Devices page on the new server.

Step 6 — Reinstall Device Agents (If Necessary)

Agents usually keep working after migration if the server URL (DNS name or IP) is unchanged. You may need to reinstall an agent if:

• the server URL changed and the device cannot reach the new server;

• the SSL certificate changed and the device rejects it; or

• the agent version is incompatible with the server version.

To reinstall: open Devices, select the affected device, and reinstall its agent; then confirm it shows online.

Step 7 — Start and Verify

1. Start the OptimiDoc Service, then the OptimiDoc site.

2. Log in as administrator (this proves the encryption recovery in Step 4 succeeded).

3. Run through the checks:

Step 8 — Decommission the Old Server

Once the new server is fully verified:

1. Stop the OptimiDoc site and OptimiDoc Service on the old server.

2. Keep the old server available for a rollback period (at least one week recommended).

3. After the rollback period, decommission or repurpose the old server. Retain your database backup, the .odrk recovery key and any key export securely.

In Summary

Migrating to a new server is: install the matching version, copy web.config, App_Data and the licence, point at the database — and then, because the encryption key is machine-bound, recover the encryption keys on the new machine by uploading the .odrk file at /recover-encryption (or by re-joining a live cluster). Download that recovery key from the old server's Encryption page before you start. Finish by repointing DNS/IP to the new server, verifying that stored secrets decrypt and devices reconnect, and keeping the old server on standby for a rollback window.

Related articles

• General Upgrade

• LocalDB to SQL Server

• Failover Architecture

• Cluster and Failover Issues

• Upgrade and Migration