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 tonucleus-host-2
. The DNS name that users are utilizing when accessing this instance ismynucleus.example.com
, which resolves tonucleus-host-1
.nucleus-host-2
is configured with the Nucleus DATA_ROOT directoryrsync
’d fromnucleus-host-1
. Please note that while hot copies are not supported, the majority of data will be copied prior to shutting down thenucleus-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 thebase_stack
directory tonucleus-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 onnucleus-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 tonucleus-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!
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
Move /opt/ove to /opt/ove-old:
sudo mv /opt/ove /opt/ove-old
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
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.
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.
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
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.