Planning and prerequisites

Use this page before you run atomos-cli on production hardware. It connects Hardware constraints to Architecture roles, C4 reachability, Electros registration, and storage design.

Illustrative diagrams

Topology drawings below are illustrative. They are not certified reference designs or availability guarantees. Adapt IP plans, port rules, and redundancy to your organization’s standards and validate with a PoC.

Choose a deployment pattern

Pattern	AtomOS roles	When it fits
Single-host full	full (+ optional atomosgui)	Lab, PoC, small office, edge with modest VM count
Separated compute and storage	compute on hypervisors, storage on vault nodes	Independent scaling, clearer fault domains, larger VM fleets
Hyperconverged (HCI)	full on multiple similar nodes	Uniform nodes that each run VMs and local/shared vaults
Multi-node cluster	Mix of compute, storage, full	Electros-managed fleet with C4 discovery among peers
Storage-only satellite	storage on Ubuntu/Debian	Central vault tier while compute stays on Alma/Rocky

Deep-dive scenarios: Deployment topologies and Availability & recovery.

Illustrative topology: single full host

flowchart TB
  subgraph site["Single site — illustrative"]
    subgraph mgmt_net["Management network"]
      ADM[Admins / Electros]
    end
    subgraph host["One server — full role"]
      BR[br0 guest bridge]
      VM[VMs]
    end
    ADM -->|SSH HTTPS| host
    BR --> VM
    VM --> LAN[User VLANs / upstream]
  end

Document: host IP, DNS, bridge NIC, vault disk layout, backup target, and Electros target name.

Illustrative topology: separated compute and storage

flowchart TB
  subgraph dc["Datacenter — illustrative"]
    EL[Electros]
    subgraph mgmt["Management network"]
      EL
      ADM[Administrators]
    end
    subgraph cluster_net["Cluster / API network"]
      C1[Compute 1]
      C2[Compute 2]
      S1[Storage 1]
      S2[Storage 2]
    end
    subgraph guest["Guest networks"]
      C1 --> VM1[VMs]
      C2 --> VM2[VMs]
    end
    EL --> C1
    EL --> C2
    EL --> S1
    EL --> S2
    C1 --- S1
    C2 --- S1
    C2 --- S2
    S1 --> DISK1[(Backends)]
    S2 --> DISK2[(Backends)]
  end

Ensure cluster and storage ports from the install reference are open between peers on the paths you use.

Illustrative topology: multi-node HCI cluster

flowchart LR
  subgraph hci["Three-node HCI — illustrative"]
    H1[Node 1 full]
    H2[Node 2 full]
    H3[Node 3 full]
    H1 <-->|C4 / cluster| H2
    H2 <-->|C4 / cluster| H3
    H1 <-->|C4 / cluster| H3
  end
  E[Electros] --> H1
  E --> H2
  E --> H3

HCI simplifies uniform hardware orders; still plan maintenance windows, backup, and whether vault backends replicate across nodes.

Management, storage, and BMC networks

Network	Typical traffic	Planning notes
Management	SSH, atomos-cli, Electros HTTPS, optional AtomOS GUI (7780/7781), optional Cockpit (9090)	Restrict sources; document fingerprint verification steps
Cluster / AtomOS APIs	C4 discovery, compute, storage, client ports	See install reference; avoid routing through asymmetric NAT without testing
Guest / bridge	VM production traffic via br0 (or additional bridges)	Dedicated NIC recommended; VLAN strategy in Networking
Storage	Vault replication, iSCSI/NFS, backend sync	Low latency and stable MTU; separate from guest overload when possible
BMC / IPMI	Out-of-band power and console	Not used by AtomOS directly; keep on isolated management

Run atomos-cli --bridge-setup during or after install to bind guest bridging to the intended NIC — Install.

Storage redundancy and capacity

AtomOS vaults abstract POSIX paths backed by local disks, mdadm, ZFS, GlusterFS, Quobyte, and other supported backends. Redundancy is a property of the backend you configure, not a single global AtomOS mode.

Goal	Planning action
Survive disk loss	Use RAID/ZFS/mirrored pools or distributed backends appropriate to RPO
Survive node loss	Replicate or place volumes where other compute nodes can reconnect; test pledge re-placement
Capacity growth	Track vault settings.json limits (--vault-creator, --vault-editor); expand backends before virtual capacity exhausts
Deletion safety	Volumes removed from Electros may land in elemento-bin — define retention — Storage

Coordinate with Backup & recovery for guest-consistent and vault-level procedures.

Electros and organizational prerequisites

Before fleet operations:

• Organization admins can add Connections → Targets and enable Active Connections.
• Operators know how to compare TLS fingerprints (atomos-cli --show-fingerprint).
• Scenarios, networks, and storage objects match the VLAN and vault layout you build on hosts.

Walkthrough: VMs & Electros.

Network reachability and endpoints

Hosts need outbound access during install and updates:

Destination	Purpose
Distro package mirrors	AlmaLinux, Rocky, Ubuntu, or Debian repositories
idp.elemento.cloud	Identity / Elemento services
repo.elemento.cloud	AtomOS packages and bootstrap
portal.elemento.cloud	Portal integration

Inbound rules must allow Electros and administrators to reach each registered target IP and every peer path required for C4 and storage APIs — Networking & certificates.

Cloud installs

On some CSP instances, verify IPv4/IPv6 routing with atomos-cli --verify-network before install — Install.

Document before install

Capture at least the following in your runbook or ticket template:

Identity and access

• [ ] Electros organization roles and who may register targets
• [ ] Local AtomOS GUI groups if using atomosgui (storage, compute, admin)
• [ ] Break-glass root/sudo holders and maintenance window

Network

• [ ] IP addressing and DNS for every target interface
• [ ] VLAN IDs and upstream gateways for br0 and management
• [ ] Firewall zones and allowed ports (install reference)
• [ ] Certificate SANs (all IPs and DNS names used to reach hosts)

Hardware and storage

• [ ] Server inventory and firmware levels — Hardware
• [ ] Disk map: OS vs vault backends (lsblk baseline)
• [ ] BMC addresses and access policy

Workloads

• [ ] Baseline specfiles or templates for standard VM sizes
• [ ] GPU/passthrough requirements and IOMMU validation plan
• [ ] Expected VM count and growth for CPU/RAM sizing

Resilience

• [ ] Backup scope (guests, vault metadata, Electros configuration export per your process)
• [ ] RTO/RPO targets without assuming C4 discovery equals HA — C4
• [ ] Recovery steps for single-host loss vs storage-node loss

Role selection worksheet

Question	If yes →	If no →
VMs and vaults on same box?	full	Split compute + storage
Ubuntu/Debian only for this machine?	storage (or atomosgui)	Use Alma/Rocky for compute / full
Local UI without Electros path?	Add atomosgui	Electros-only operations
Dedicated vault servers?	storage on storage nodes, compute elsewhere	full on HCI nodes

Install commands: Install with atomos-cli.

Pre-install checklist (condensed)

1. [ ] Distro version matches the hardware OS matrix
2. [ ] CPU virt flags and RAM meet recommended sizing (not only 2 core / 2 GB minimum)
3. [ ] Preflight commands recorded (lscpu, lsblk, ip, lspci)
4. [ ] Network design reviewed (management, cluster, guest, storage)
5. [ ] Storage backends chosen and redundancy documented
6. [ ] Electros target names and fingerprint procedure assigned
7. [ ] PoC success criteria defined (create VM, reboot host, restore from backup test)

Next step

Proceed to Install with atomos-cli when the checklists above are complete.

Related:

• CLI & ports reference
• Core concepts (C4)
• Glossary