AtomOS Docs

Appearance

Upgrades ​

Plan AtomOS updates around running VMs, licenses, TLS certificates (from the 0.9 HTTPS milestone), and optional AtomOS GUI packages. This page separates routine updates, minor/major in-place upgrades, legacy pre-0.6 migration, certificate rotation, and conceptual rollback.

Confirm capabilities after any change: Feature availability, Diagnostic commands.

Preflight (all upgrade paths) ​

  1. Record current state: sudo atomos-cli --version, --info, --status.
  2. Confirm outbound access to distro mirrors and Elemento endpoints (Install reference).
  3. Verify disk space on /, /var, and vault mounts under /mnt.
  4. Ensure console/BMC access if the host uses br0 on a sensitive NIC (Networking).
  5. Notify stakeholders; drain or migrate VMs if your change window requires it (Migration).
  6. Verify backups of /etc/elemento (licenses) and critical vault data (Backup).

Routine updates (same major packaging era) ​

Use this path for typical in-place maintenance on current atomos-cli installs (including hosts originally on 0.7 / 0.8 lines moving forward).

1. Refresh atomos-cli ​

Prefer download, review, then execute:

bash
curl -fsSL https://repo.elemento.cloud/get-atomos.sh -o /tmp/get-atomos.sh
# Review /tmp/get-atomos.sh, then:
sudo bash /tmp/get-atomos.sh

Avoid blind pipe-to-shell

Piping curl directly to bash skips review. Production hosts should use the saved script pattern above (Install reference).

From the 0.9 milestone, the tool is atomos-cli (formerly nucleus).

2. Update AtomOS packages ​

bash
sudo atomos-cli --update

Mind licenses and running VMs — service restarts during update can interrupt workloads.

3. Post-update items the updater may not complete ​

HTTPS certificates (0.9+ milestone) ​

New installs prompt for certificates. After upgrading into the HTTPS era, generate or renew if SANs are incomplete:

bash
sudo atomos-cli --generate-cert
sudo atomos-cli -ra

Re-trust fingerprints in Electros and on peer hosts (--show-fingerprint, --get-certificate) — Networking.

AtomOS GUI (atomosgui) ​

--update updates packages already installed; it does not add roles that were never deployed. To add the on-host GUI after upgrade:

bash
sudo atomos-cli --install atomosgui on-prem

Alternatively, on RHEL-family hosts where your matrix includes the package:

bash
sudo dnf install atomos-atomosgui

Reboot when prompted or per site standard. Fresh full installs that include GUI from the start avoid this gap.

Post-validation ​

bash
sudo atomos-cli --verify-install
sudo atomos-cli --status
sudo atomos-cli --healthcheck

Exercise one Electros target operation and one storage check (--volume-info). Runbooks: Troubleshooting.

Minor vs major upgrades (in-place) ​

TypeTypical scopeOperator focus
Minor / patchPackage refreshes within your current architectureRoutine path above; watch TLS and GUI gaps
MajorMilestone changes (e.g. introduction of HTTPS defaults, role packaging changes)Certificates, Electros trust, peer pins, legacy migration if applicable

Elemento does not document a single universal “major version number” for every fleet in this guide — use atomos-cli --version, release notes from support/portal, and Feature availability before declaring production readiness.

For multi-host fleets: upgrade staging first; align ELEMENTO_CLUSTER_SECRET and peer certificates; avoid mixed secret or trust states during rolling work (Security).

Legacy migration: pre-0.6 monolithic atomos → current packaging ​

Apply only if the host still runs the old monolithic atomos package (pre-0.6 era). This is a destructive reinstall path, not a routine --update.

Data first

Back up /etc/elemento (licenses) and every vault under /mnt/*/vid.* before uninstalling. Skipping backup causes data loss. Shut down and delete VMs per your runbook before uninstall when required.

Outline:

  1. Copy licenses aside; rsync vault vid.* trees aside; strip export lock files (iqn*) from copies if present in your environment.
  2. dnf remove atomos (and Docker packages if they were part of the old stack).
  3. Remove /var/elemento, /etc/elemento, /opt/elemento, and old vault mounts after backup verification.
  4. Remove legacy Elemento repo files under /etc/yum.repos.d/.
  5. Follow Install AtomOS for a clean current install (download-then-execute bootstrap).
  6. Restore licenses to /etc/elemento; recreate vaults with --vault-creator; rsync volumes back; sudo atomos-cli --restart-all.

Expect multiple reboots. Contact support@elemento.cloud before attempting on production.

Certificate changes during upgrades ​

SituationAction
New IP or DNS for targetRegenerate with --generate-cert, restart all, re-trust Electros
Peer storage/compute added--get-certificate on both sides for each IP/role
Verification disabled for debugRe-enable with --set-cert-verify before closing the window

Rollback (conceptual) ​

AtomOS --update does not provide a single documented “undo” button. Rollback strategy is operational:

  • VM-level: restore from backup; revert snapshots only if your backend provides verified snapshot semantics — not assumed for all vault backends (Storage).
  • Host-level: restore OS from image/backup taken at preflight; reinstall AtomOS from Install and restore /etc/elemento and vault data.
  • Package-level: distro tools (dnf history) may help on RHEL-family hosts for recent transactions — test in lab; dependencies on Elemento repos may still require support guidance.

Plan rollback before change windows; automatic failover rollback is not verified as a product feature (HA).

Upgrade troubleshooting ​

SymptomSee
Electros SSL errors after updateTroubleshooting — TLS
GUI missingInstall atomosgui role or package — above
Services fail start--logs, --journal SERVICE, disk space
Partial cluster after rolling updatesSecret alignment, peer certificates, --status