Migration and Upgrades

Server Migration

Nucleus 2021.2.0 and newer

If a server migration is necessary, we recommend a blue-green approach where a new instance (green) is configured alongside the existing instance (blue) and validated prior to switching users to it.

Below is an example migration plan (overview) keeping as minimal of a maintenance window as possible: (Short hostnames are used here for simplicity.)

  • Nucleus is deployed on nucleus-host-1, and it’s desired to migrate to nucleus-host-2. The DNS name that users are utilizing when accessing this instance is mynucleus.example.com, which resolves to nucleus-host-1.

  • nucleus-host-2 is configured with the Nucleus DATA_ROOT directory rsync’d from nucleus-host-1. Please note that while hot copies are not supported, the majority of data will be copied prior to shutting down the nucleus-host-1. (It’s recommended to run this sync again prior to the maintenance window to ensure minimal downtime.)

  • Copy the /secrets directory from within the base_stack directory to nucleus-host-2 and ensure it’s in the same location.

  • Schedule the maintenance window for the server swap with your users.

During the downtime:

  • Nucleus on nucleus-host-1 is shut down. If Nucleus is also running on nucleus-host-2, shut it down as well.

  • rsync the data again. This sync should be very fast as it will only sync the most recent updates. This will also be the final sync before the cutover.

  • Nucleus on nucleus-host-2 is started and the data is validated.

  • The DNS entry for mynucleus.example.com is updated to resolve to nucleus-host-2 (the new server.)

  • When comfortable, the older nucleus-host-1 server can be deleted.

In-place Nucleus Upgrade

Nucleus 2023.1.0 and newer

To upgrade Nucleus to a newer version in-place, follow these steps: (These steps assume that Nucleus is installed in the /opt/ove directory and using the SSL-based configuration. If your configuration differs, modify the steps below as needed.)

Warning

Prior to upgrading Nucleus, please make sure that you have a tested and confirmed working backup!

  1. Stop all running Docker containers:

sudo docker compose --env-file /opt/ove/base_stack/nucleus-stack.env -f /opt/ove/base_stack/nucleus-stack-ssl.yml down

  1. Move /opt/ove to /opt/ove-old:

sudo mv /opt/ove /opt/ove-old

  1. Create a new /opt/ove directory, then unpack the new Nucleus Base Stack .tgz file into it:

sudo mkdir /opt/ove
sudo tar xvzf nucleus-stack-2023.1.0+tag-2023.1.0.gitlab.8633670.7f07353a.tar.gz -C /opt/ove --strip-components=1

  1. Copy the Nucleus secrets into the new Nucleus directory:

sudo cp -R /opt/ove-old/base_stack/secrets /opt/ove/base_stack/secrets

Warning

The secrets folder contains keys that are required to decrypt locally encrypted files and new/updated secrets can not decrypt older files and vice-versa. When upgrading/migrating, it’s important to ensure the secrets folder (and all files within) remains persistent.

  1. Manually port the custom configuration (IP Addresses, Hostnames, etc.) from /opt/ove-old/base_stack/nucleus-stack.env into /opt/ove/base_stack/nucleus-stack.env (Opening both configuration files side-by-side is recommended.) - Do not copy the configuration files as they will differ.

  2. Pull the latest updated containers, then start Nucleus:

sudo docker compose --env-file /opt/ove/base_stack/nucleus-stack.env -f /opt/ove/base_stack/nucleus-stack-ssl.yml pull
sudo docker compose --env-file /opt/ove/base_stack/nucleus-stack.env -f /opt/ove/base_stack/nucleus-stack-ssl.yml up -d

  1. Connect to your Enterprise Nucleus Server and confirm/verify it’s functionality. If any containers fail to start, start Nucleus without -d and review the on-screen messages for additional troubleshooting detail.