Back Up And Move Optima
Optima keeps everything it knows on the Gateway machine, in one folder: users, conversations, Assistants, Knowledge Bases, Connectors and their credentials, settings and certificates. This guide covers what to back up, how to restore it, and how to move Optima to a new machine.
By the end of this guide you will have a backup you can restore from, and — if you are moving — Optima running on the new machine with everything people had before.
Note
Optima has no backup button. A backup is a copy of its data folders, taken while its services are stopped.
What To Back Up
Most of what matters is in the Gateway's data folder. Each Node has a few settings of its own that are also worth keeping.
The Gateway's Data Folder
| Platform | Folder |
|---|---|
| Windows | C:\ProgramData\Parker Software\OptimaGateway |
| Linux | /var/lib/ParkerSoftware/OptimaGateway |
| macOS | /Library/Application Support/Parker Software/OptimaGateway |
Back up the whole folder. The parts that matter most are:
| In the folder | What it holds |
|---|---|
config.json |
The Gateway's own settings, and the key every stored secret is encrypted with |
optima.db |
Users, conversations, Assistants, Connectors and their credentials, settings, and access lists |
Documents/knowledgebases/ |
Every Knowledge Base: its documents and their text |
Documents/attachments/ |
Images people attached to conversations, encrypted |
jwtsettings.json |
Sign-in sessions. Without it, everyone will have to sign in again |
certificate.json, *.pfx |
The Gateway's certificate settings, and its certificate files |
node-cert-pins.json |
The Node certificates this Gateway trusts |
Branding/, ConnectorIcons/ |
The chat app's logo, and Connectors' icons |
optima-analytics.db |
Analytics history. Optional — only the reports are lost without it |
license.json, machine.id |
This machine's licence. See Moving to a new machine before restoring these anywhere else |
Warning
config.json and optima.db belong together. The credentials in optima.db — Connector keys, sign-ins, the mail server's password — and the image attachments can only be read with the key in config.json. A backup of one without the other cannot be fully restored.
You can leave the following parts out to make the backup smaller. Optima will download or rebuild them by itself:
| In the folder | What it is |
|---|---|
ScriptRuntime/, ConnectorDeps/, PipCache/, ConnectorRuns/ |
The Python runtime and Connectors' packages |
Documents/knowledgebases/*/index/ |
Knowledge Base search indexes. Rebuilt from the documents, which takes a while for large ones and needs the embedding model running |
Mcp/ |
Cached icons from the MCP directory |
Logs/ |
Log files |
Each Node
A Node's models can always be downloaded again, so a Node backup is about its settings:
| What | Where |
|---|---|
| The Node's settings, including its access key | config.json in C:\ProgramData\Parker Software\OptimaNode, or /var/lib/ParkerSoftware/OptimaNode on Linux |
| Each model's settings — context window, instances, backend and the rest | optima.executors.db in the Node's installation folder: C:\Program Files\OptimaNode, or /opt/OptimaNode on Linux |
| Models | Executors/Models/ in the Node's data folder. Large; only worth backing up if downloading them again would be slow |
What Is Not On The Gateway
Conversations are kept on the Gateway, so they are in the backup. Each person's Optima Chat app keeps a few things on their own device — their Workspace folders, tool activity, and which tools they ticked — and these are not part of a server backup.
Taking A Backup
The databases must not be changing while they are copied. Stop the services first, and start them again afterwards. You can do this with Stop and Start in the installer's Manage page (see Managing Optima), or with the commands below, which suit a scheduled backup.
Windows — in PowerShell, as administrator:
Stop-Service OptimaGateway, OptimaNode
Compress-Archive -Path "C:\ProgramData\Parker Software\OptimaGateway" `
-DestinationPath "D:\Backups\optima-gateway-$(Get-Date -Format yyyy-MM-dd).zip"
Start-Service OptimaNode, OptimaGateway
Linux:
sudo systemctl stop OptimaGateway OptimaNode
sudo tar -czf /backups/optima-gateway-$(date +%F).tar.gz \
-C /var/lib/ParkerSoftware OptimaGateway
sudo systemctl start OptimaNode OptimaGateway
Leave out OptimaNode if the Gateway machine runs no Node. People cannot use Optima while the services are stopped, so schedule backups out of hours.
Warning
Protect the backup as you would a password store. It holds every credential Optima has, together with the key that decrypts them. Keep it somewhere only administrators can reach, and encrypt it if it leaves the building.
Restoring On The Same Machine
You can go back to a backup on the machine it came from — for example, after a failed disk, or a mistake you need to undo:
- Install Optima, if it is not installed, at the same version as the backup or newer.
- Stop the services.
- Replace the Gateway's data folder with the one from the backup — all of it,
license.jsonandmachine.idincluded. - Start the services.
Everything will come back as it was when the backup was taken. Anything created since — conversations, users, uploaded documents — will be lost.
Moving To A New Machine
A licence belongs to one machine, so a move releases it from the old one and activates it on the new one. Both machines need internet access for this. Without it, see Without internet access.
On The Old Machine
- Tell people Optima will be unavailable for the move.
- Open the Licence page and click Deactivate. This releases the serial number for the new machine. Optima will carry on running, with reduced limits.
- Stop the services, and take a backup as above.
- Note how the certificate was set up, in Settings → Security → Manage Certificates. If it came from the Windows certificate store, export it with its private key as a PFX file.
On The New Machine
- Install Optima, at the same version as the old machine or newer. See Installing Optima.
- Stop the services.
- Copy the backup into the Gateway's data folder, except
license.jsonandmachine.id. Leave those out: they belong to the old machine. - Start the services, and sign in with your usual account.
- Open the Licence page and activate with your serial number. See Activating a licence.
- Set up the certificate again: upload the PFX file, or choose it from the new machine's certificate store. A certificate's password cannot be carried between Windows machines, so this is needed even when the files were copied. See Certificates and Security.
- Point your DNS record at the new machine.
Nodes
How you move a Node depends on where it runs:
- A Node on the old Gateway machine moves with it: install the Node on the new machine too, and copy its
config.jsonandoptima.executors.dbacross before starting it. Its models can be copied or downloaded again. - A Node on another machine needs nothing, if the Gateway keeps the same address. If a Node itself moves, or is reinstalled, it has a new certificate, and the Gateway will refuse it until you click Trust new certificate on the Node. See Managing Nodes.
- A Node installed afresh — moved, or reinstalled without its
config.json— also has a new access key. Give it the Gateway's key on the installer's finish screen, or later from Manage. See Access Keys.
Check Everything Came Across
Once the new machine is running, check the following:
| Check | How |
|---|---|
| People can sign in | Sign in to Optima Chat with an ordinary account |
| Conversations are there | Open an old conversation, including one with an attached image |
| Connectors still work | Ask an Assistant something that uses a Connector. If one reports a credential problem, the backup's config.json and optima.db did not come from the same copy |
| Knowledge Bases answer | Search one on the Knowledge page. If its index was left out of the backup, rebuild it first |
| Nodes are connected | The Nodes page shows each Node connected, with its models running |
| Email works | Settings → Email → Send a test email |
If the new machine has the same address and a certificate from your own certificate authority, people will notice nothing. If it uses the Gateway's self-signed certificate, the Optima Chat apps will show Certificate has changed the first time they connect, and each person will have to trust the new one. Tell people to expect it.