Migration and Upgrades
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-2is configured with the Nucleus DATA_ROOT directory
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.)
/secretsdirectory from within the
nucleus-host-2and ensure it’s in the same location.
Schedule the maintenance window for the server swap with your users.
During the downtime:
nucleus-host-1is shut down. If Nucleus is also running on
nucleus-host-2, shut it down as well.
rsyncthe 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-host-2is started and the data is validated.
The DNS entry for
mynucleus.example.comis updated to resolve to
nucleus-host-2(the new server.)
When comfortable, the older
nucleus-host-1server 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.)
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
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
-dand review the on-screen messages for additional troubleshooting detail.