⬇️ AtomOS & atomos-cli Installation Guide

This guide explains how to install the atomos-cli and use it to deploy AtomOS and its components on supported Linux distributions.

Prerequisites

Run all commands as root (use sudo).
Supported distributions: AlmaLinux (RHEL), Ubuntu, Debian (x86_64 only).
Minimum: 2 CPU cores, 2GB RAM.
Internet access is required.

1. Install `atomos-cli`

The recommended way to install atomos-cli is via the official installer script:

curl -fsSL https://repo.elemento.cloud/get-atomos.sh | sudo bash

This will:

Download the latest atomos-cli CLI to /usr/bin/atomos-cli
Make it executable and add it to your PATH (if needed)
Set up a cron job to check for updates monthly

You can now use the atomos-cli command from anywhere.

2. Install AtomOS

The installation of AtomOS is automatic, at the end of the package installation, the CLI will ask a series of additional config in order to have a fully functional installation

Here you can see a test installation of the latest version:

For RHEL/AlmaLinux

Compute Node:

sudo atomos-cli --install compute <on-prem | cloud>

Storage Node:

sudo atomos-cli --install storage <on-prem | cloud>

AtomOS-Gui Node:

sudo atomos-cli --install atomosgui <on-prem | cloud>

Full Node (Compute + Storage):

sudo atomos-cli --install full <on-prem | cloud>

For Ubuntu/Debian

Storage Node only:

sudo atomos-cli --install storage <on-prem | cloud>

AtomOS-Gui Node:

sudo atomos-cli --install atomosgui <on-prem | cloud>

Compute/Full packages are not available for Ubuntu/Debian.

Note: Choose on-prem or cloud installation based on where the host machine reside

after running the command, follow the instruction that atomos-cli will prompt

3. Network Bridge Setup

During installation, atomos-cli will prompt you to select a network interface and will create a bridge (default: br0) using nmcli. Follow the prompts to select the correct interface for your environment.

To set up a bridge manually at any time:

sudo atomos-cli --bridge-setup

WARNING
Some CSPs add a custom IPv6 default route to their intances, make sure to verify that through that interface you have internet connection, otherwise the installation could throw some error (eg. pip defaults to IPv6 if a route is present and setted to default
To find out use sudo atomos-cli --verify-network to see the actual configuration

4. Module Installation

After AtomOS installation, atomos-cli will offer to fetch and install additional modules from the Elemento repository. You can:

List available modules
Select modules to install interactively

sudo atomos-cli --modules

Full removal of the module can be done with:

sudo atomos-cli --remove-module

5. Vault Setup

If you install Storage or Full, atomos-cli will set up the default Elemento vault and offer to create custom vaults with your chosen settings. Call the cli to create new custom vaults:

sudo atomos-cli --vault-creator

After the installation, editing vaults settings is possibile via:

sudo atomos-cli --vault-editor

after every change, the storageserver must be restarted to update it's behavior

6. HTTPS Certificate Setup

From version 0.9.0 AtomOS requires https certificates to secure communications. In order to create the needed certificates, you can use the cli command:

sudo atomos-cli -crt

This will create self-signed certificates for your AtomOS instance.

7. Local user management

From version 0.9.0 AtomOS can serve it's own Electros-on-AtomOS instance, thus enabling users and sysadmin to have a simple and local way to manage and provision resources. In order to create the needed local users, you can use the cli command:

sudo atomos-cli -mu

This will create the needed user groups and ask for each user which group to assign them to, thus giving them the right permissions to manage the AtomOS instance and its resources.

The possible groups are:

storage --> full permision to manage storage resources
compute --> full permision to manage compute resources
admin --> full permision to manage both compute, storage and network resources

8. Post-Install

Check installation:
```
sudo atomos-cli --verify-install
```
Show system info:
```
sudo atomos-cli --info
```
Restart your system to apply all changes.

9. Troubleshooting

Ensure you have root privileges.
If you encounter errors, check logs with:
```
sudo atomos-cli --logs
```
For help:
```
sudo atomos-cli --help
```

For more information, visit https://elemento.cloud