Skip to main content
This guide shows you how to deploy Omni on-prem. This guide assumes that Omni will be deployed on an Ubuntu machine. Small differences should be expected when using a different OS. For SAML integration sections, this guide assumes Azure AD will be the provider for SAML. Omni is available via a Business Source License which allows free installations in non-production environments. If you would like to deploy Omni for production use please contact Sidero sales. If you would like to subscribe to the hosted version of Omni please see the SaaS pricing;

​
Prerequisites

There are several prerequisites for deploying Omni on-prem. We will assume you have an Ubuntu machine available. Any distribution with Docker should work.

​
Install Docker

Install Docker according to the Ubuntu installation guide here. You will also need the docker compose plugin package if you want to use the example docker compose template. 
curl -L https://get.docker.io | sh

​
Generate Certs

On-prem Omni will require valid SSL certificates. This means that self-signed certs will not work. Generating certificates is left as an exercise to the user, but here is a rough example that was tested using DigitalOcean’s DNS integration with certbot to generate certificates. The process should be very similar for other providers like Route53. 
# Install certbot
$ sudo snap install --classic certbot

# Allow for root access
$ sudo snap set certbot trust-plugin-with-root=ok

# Install DNS provider
$ snap install certbot-dns-<provider>

# Create creds file with API tokens
$ echo '<creds example' > creds.ini

# Create certs for desired domain
$ certbot certonly --dns-<provider> -d <domain name for onprem omni>

​
Configure Authentication

​
Auth0

Create an Auth0 account. On the account level, configure “Authentication - Social” to allow GitHub and Google login. Create an Auth0 application of the type “single page web application”. Configure the Auth0 application with the following:
  • Allowed callback URLs: https://<domain name for onprem omni>
  • Allowed web origins: https://<domain name for onprem omni>
  • Allowed logout URLs: https://<domain name for onprem omni>
Disable username/password auth on “Authentication - Database - Applications” tab. Enable GitHub and Google login on the “Authentication - Social” tab. Enable email access in the GitHub settings. Take note of the following information from the Auth0 application:
  • Domain
  • Client ID

​
SAML Identity Providers

Other identity providers also work with Omni. Configuring these should be similar to Auth0.

​
Create Etcd Encryption Key

Generate a GPG key: 
gpg --quick-generate-key "Omni (Used for etcd data encryption) how-to-guide@siderolabs.com" rsa4096 cert never
Find the fingerprint of the generated key: 
gpg --list-secret-keys
Using the fingerprint, add an encryption subkey and export: 
gpg --quick-add-key <fingerprint> rsa4096 encr never
gpg --export-secret-key --armor how-to-guide@siderolabs.com > omni.asc
Note: Do not add passphrases to keys during creation.

​
Deploy Omni

There are two easy ways to run Omni: docker-compose and a simple docker run. We recommend using docker-compose, but both are detailed in separate tabs below.
  • Docker Compose
  • Docker Run

​
Export variables

You will need to specify some customizations for your installation. Export these variables with your information to use in the provided templates
export OMNI_VERSION=0.41.0
OMNI_ACCOUNT_UUID=$(uuidgen)
OMNI_DOMAIN_NAME=omni.siderolabs.com
OMNI_WG_IP=10.10.1.100
OMNI_ADMIN_EMAIL=omni@siderolabs.com
AUTH0_CLIENT_ID=xxxyyyzzz
AUTH0_DOMAIN=dev-aaabbbccc.us.auth0.com

​
Download Assets

To pull down the Omni deployment assets for Docker Compose, simply grab them with curl as follows.
curl https://raw.githubusercontent.com/siderolabs/omni/v${OMNI_VERSION}/deploy/env.template \
  | envsubst > omni.env

curl https://raw.githubusercontent.com/siderolabs/omni/v${OMNI_VERSION}/deploy/compose.yaml -o compose.yaml

​
Verify settings

Open the omni.env file to check that all of your variables have been set to your environment requirements.

​
Run It!

With your environment file in hand, it’s now time to run Omni. This can be done with a simple docker compose command:
docker compose --env-file omni.env up -d
⌘I