.. _install-upgrade:

==================================
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:

   .. code-block:: console

      # 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:

   .. code-block:: console

      # 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:

   .. code-block:: console

      # systemctl stop toa-server.service

#. **Re-point the symlinks** to the new version:

   .. code-block:: console

      # 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
   :ref:`install-server`), no unit edit is required.

#. **Start** the service and verify it comes up cleanly with the
   same checks as for a fresh install:

   .. code-block:: console

      # systemctl start toa-server.service
      # journalctl -u toa-server.service --since "-2 min" --no-pager

   Run the ``GET /domains`` smoke test from :ref:`install-verify` 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:

   .. code-block:: console

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

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.