Skip to main content
This guide walks you through deploying Omni on a Linux host with internet access. By the end, you will have a fully functional Omni instance running with TLS, an OIDC identity provider, and either embedded or external etcd.
Omni is licensed under the Business Source License and requires a support contract for production use. Contact Sidero sales for a production license.

Prerequisites

You will need:
  • A Linux host with at least 2 vCPUs and 4 GB RAM
  • A domain name or IP address for your Omni instance
  • Docker installed on the host
  • The following ports open and accessible:

Step 1: Install Docker

Omni and its supporting services run as Docker containers. Follow the official Docker installation guide for your Linux distribution. After installing, add your user to the docker group so you can run Docker without sudo:

Step 2: Install cfssl

cfssl generates and signs the TLS certificates used by Omni and Dex.

Step 3: Set environment variables

Set variables that define your host’s network addresses and the internal hostnames for Omni and Dex. They are referenced throughout the guide, so set them before proceeding.
If your host does not have a public IP (e.g. a local VM), set HOST_PUBLIC_IP to the IP your local machine uses to reach the host.

3.1: Add internal hostnames to /etc/hosts

Omni and Dex use .internal hostnames that are not registered in public DNS. This maps them to localhost so the host can resolve them.

Step 4: Generate TLS certificates

Omni and Dex communicate over TLS. In this step, you create a root CA and use it to sign a certificate covering both service endpoints. The CA certificate is also distributed to client machines in Step 9 so their browsers trust the Omni UI.
If you already have a trusted internal CA, use it to sign the certificate in Step 4.3 and skip Steps 4.1 and 4.2.

4.1: Create the root CA

Run this command to generate a self-signed root CA, the trust anchor for all certificates in this setup. It produces ca-key.pem (private key), ca.pem (public cert), and ca.csr (signing request).
Add the CA to the host’s system trust store so services running on this machine trust certificates signed by it:

4.2: Create the signing configuration

Create a signing configuration that tells cfssl how to sign certificates. The web-server profile is used for Omni and Dex. The client profile is used for external etcd authentication.

4.3: Generate the server certificate

Generate a single wildcard certificate covering both the Omni and Dex endpoints. Both IPs are included so TLS connections work regardless of whether clients connect by hostname or IP.
If you plan to use workload proxy, add a wildcard SAN for your proxy domain to the hosts array now to avoid regenerating the certificate later. The exact value depends on your domain layout. See Choose your domain layout.
Sign the certificate using the CA and configuration from the previous steps:
Bundle the server certificate with the CA so clients can verify the full chain:
This produces server-key.pem (private key), server.pem (public cert), and server-chain.pem (cert bundled with CA). Make them readable by all service users by running:

Step 5: Generate the etcd encryption key

Omni encrypts all data written to etcd at rest using a GPG key. This generates the key and exports it to omni.asc, which Omni reads on startup.
Do not set a passphrase on this key. Omni reads the key file on startup and cannot prompt for a passphrase interactively.

Step 6: Set up an identity provider

Omni requires an OIDC or SAML identity provider for user authentication. This guide uses Dex, configured with a static user. Dex can also act as a proxy to upstream providers such as LDAP, SAML, GitHub, and Okta, see the Dex connector documentation for details. If you already have an existing SAML or OIDC provider and want to connect it directly to Omni, skip this step and see Authentication and Authorization.

6.1: Create a password hash for the admin user

You will be prompted to enter a password. This becomes your Omni login password. The hash is stored in the Dex configuration and never transmitted in plain text.

6.2: Write the Dex configuration

Create a dex.yaml configuration file, which configures Dex to serve OIDC over TLS on port 5556, registers Omni as an OAuth2 client, and creates a single static login user.

6.3: Run Dex

Start Dex as a container, mounting the configuration file and TLS certificates. The :Z flag on volume mounts ensures compatibility with SELinux if it is enabled on your host.

Step 7: Run Omni

In this step you will start the Omni container and connect it to the services you set up in the previous steps: the TLS certificates from Step 4, the encryption key from Step 5, and the identity provider from Step 6.

7.1: Get the latest Omni version

Fetch the latest Omni release tag from GitHub and store it in OMNI_VERSION:

7.2: Merge the CA trust bundle

Step 7.5 mounts a certificate at /etc/ssl/certs/ca-certificates.crt so the container trusts the certificate generated in Step 4. This path is also the container’s system trust store, used to verify TLS connections to external hosts such as the Image Factory. Merge your CA into the image’s existing trust bundle so both the internal certificate and the standard public certificate authorities remain trusted:

7.3: Create the SQLite storage directory

Omni uses SQLite alongside etcd for certain internal state. This command creates the directory on the host that will be mounted into the container:

7.4: Accept the EULA

Omni requires acceptance of the End User License Agreement (EULA) to start. Acceptance is recorded the first time Omni starts with a name and email address, and starting Omni with a different name or email updates the record.
If your organization has a separate agreement with Sidero Labs, that agreement takes precedence and the EULA does not apply. Omni still requires the acceptance values below to start.
The commands in Step 7.5 set the --eula-accept-name and --eula-accept-email flags from the EULA_NAME and EULA_EMAIL environment variables. Set them to your own values:
To accept the EULA in an Omni configuration file instead, see eulaAccept in the Omni configuration reference.

7.5: Start Omni

Choose the etcd mode that matches your setup. Embedded etcd is suitable for a single Omni instance. External etcd is required for high availability or if you need to manage the datastore independently. The commands below use CLI flags to start Omni. If you prefer to use a configuration file instead, see Omni configuration Examples. The OIDC client secret from Step 6.2 is set with the OMNI_AUTH_OIDC_CLIENT_SECRET environment variable.
Omni uses embedded etcd for cluster state. This command creates the directory on the host that will be mounted into the container:
With the etcd directory in place, start the Omni container:

Step 8: Verify services are running

Check that both Omni and Dex containers started successfully:
Expected output:
Confirm Omni is serving on port 443:
This should return the Omni HTML page.

Step 9: Access the Omni UI

Omni is running on your host, but your local machine does not yet trust the CA certificate or know how to resolve the internal hostnames. The steps below set that up.

9.1: Copy the CA certificate to your local machine

Copy ca.pem from the host to your local machine. You will install it as a trusted root in the next step.
Replace <HOST_PUBLIC_IP> with your instance’s public IP and ~/path/to/your-key.pem with your SSH key path.

9.2: Trust the CA certificate

Add the CA to your local machine’s system trust store. This tells your browser and OS to trust TLS certificates signed by this CA, including the Omni and Dex endpoints.
On Red Hat and Fedora based distros you can copy the ca.pem file into the /etc/pki/ca-trust/source/anchors/ folder and then run the following command to generate the trusted root store:

9.3: Add internal hostnames to your local hosts file

Map the Omni and Dex hostnames to your host’s public IP so your local machine can resolve them. Replace <HOST_PUBLIC_IP> with your host’s public IP.

9.4: Log into Omni

Open https://omni.internal in your browser and sign in with the email from Step 3 and the password from Step 6.1.

Step 10: Connect machines

Machines connect to Omni through the SideroLink API at https://omni.internal:8090. Because omni.internal is not a public DNS name and its certificate is signed by the CA from Step 4, machines need to resolve the hostname and trust the CA. Each requirement is met by the following:
  • Name resolution: A DNS record for omni.internal on the machines’ network, or a StaticHostConfig document. StaticHostConfig requires Talos Linux 1.12 or later.
  • CA trust: A TrustedRootsConfig document with the CA certificate.
To connect a machine, add these documents to the Omni join configuration and provide the result to the machine at first boot:
  1. On your local machine, open the Omni Home page and click Download Machine Join Config. The browser saves the join configuration to your downloads folder as machine-config.yaml, or with a number added to the name if a file with that name already exists.
  2. On your local machine, set the public IP of the Omni host. Replace <HOST_PUBLIC_IP> with the public IP:
  3. In the same terminal, append the StaticHostConfig and TrustedRootsConfig documents to machine-config.yaml, with the ca.pem file you copied in Step 9.1. Run the command from the folder that contains both files, and replace machine-config.yaml with the name of the downloaded file if it differs:
  4. Provide the combined file to each machine at first boot. The method depends on the platform:
    • Cloud platforms, such as AWS, GCP, Azure, and DigitalOcean: Paste the file into the user data of the instance.
    • Proxmox: Provide the file through the NoCloud datasource.
    • Bare metal: Serve the file over HTTP and add the talos.config kernel argument with its URL to the default kernel arguments, for example through a PXE boot or an Image Factory schematic.
    Acquiring Machine Configuration lists every method. The combined file only connects the machine to Omni. Omni generates the full Talos Linux machine configuration when the machine joins a cluster.