2.4. Upgrading an existing installation

A TOA server upgrade is a swap of the installation directory. The configuration file and the data root are left untouched, so the procedure is short:

Download the new toa-server-<new-version>-dist.zip from Artifactory (same coordinates as for the initial install, just a different version). Verify you received the intended build before touching the running server.
Unpack next to the current install so both versions live side-by-side:
```
# unzip /tmp/toa-server-1.1.0-dist.zip -d /opt/
```
You now have /opt/toa-server-1.0.0/ (running) and /opt/toa-server-1.1.0/ (staged).
Copy the customer configuration from the old installation into the new one:
```
# cp /opt/toa-server-1.0.0/config/toa-server.yml \
     /opt/toa-server-1.1.0/config/toa-server.yml
```
Always compare the old file against the new sample (/opt/toa-server-1.1.0/config/toa-server.yml as shipped) and merge any new keys that the release notes mention. The data root and domain codes must stay the same - they refer to existing on-disk imports.
Stop the running service:
```
# systemctl stop toa-server.service
```
Re-point the symlinks to the new version:
```
# ln -sfn /opt/toa-server-1.1.0 /opt/toa-server
# ln -sfn /opt/toa-server/toa-server-1.1.0.jar \
          /opt/toa-server/toa-server.jar
```
Because the systemd unit references the stable /opt/toa-server and /opt/toa-server/toa-server.jar paths (see Installing TOA server), no unit edit is required.
Start the service and verify it comes up cleanly with the same checks as for a fresh install:
```
# systemctl start toa-server.service
# journalctl -u toa-server.service --since "-2 min" --no-pager
```
Run the GET /domains smoke test from Verifying the install to confirm the new version serves requests.
Keep the previous installation for rollback until the new version has proven stable in production. If rollback is needed, stop the service, point the symlinks back at the old directory, and start again - no data conversion is involved because the data root is managed by the service, not by the installation.
Remove old versions once the new one is confirmed stable:
```
# rm -rf /opt/toa-server-1.0.0
```
The data root and configuration are not under the versioned directory and are unaffected.

Downtime during the swap is limited to the few seconds between systemctl stop and systemctl start. Imports that are in flight at the moment of the restart will fail on the client and need to be retried - schedule the upgrade for a quiet window if that matters.

2.4.1. Release notes

Before upgrading, read the release notes for every version between the currently installed one and the target version. Any configuration keys that were added, removed or renamed are called out there; the upgrade procedure above assumes a drop-in config. When the release notes mandate a configuration change (for example a new mandatory field), edit the copied toa-server.yml before starting the service.