Azure

A single Azure virtual machine is the simplest way to self-host Onyx on Azure.

To deploy Onyx on AKS with Azure Database for PostgreSQL, Azure Managed Redis, and Blob Storage, use the Terraform modules for Azure.

Guide

Create a VM instance

Create a VM with the appropriate resources. This guide uses the recommended Standard_D4s_v3 size.

Give your VM a descriptive name like onyx-prod
Select the Ubuntu Server 24.04 LTS image
Select the Standard_D4s_v3 size
Select Allow selected ports and check HTTPS (443) in the Inbound port rules section
Configure storage following the Resourcing guide

Create the instance

Click Create and then view your VM details.

Save the Public IP address of the VM.

Point domain to the instance

If you don’t have a domain, buy one from a DNS provider like GoDaddy or just skip HTTPS for now.

To point our domain to the new instance, we need to add an A and CNAME record to our DNS provider.The A record should be the subdomain that you would like to use for the Onyx instance like prod.The CNAME record should be the same name with the www. in front resulting in www.prod pointing to the full domain like prod.onyx.app.

Install Onyx requirements

Onyx requires git, docker, and the docker compose plugin.To install these on Ubuntu Server, run the following:

sudo apt-get update
sudo apt-get install -y ca-certificates curl

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin git
sudo usermod -aG docker $USER

Log out and back in so your user can run docker without sudo.

Prefer a guided install? The Onyx CLI installs Docker Compose, writes the configuration, and manages upgrades for you. Skip the remaining steps if you use it.

Install and Configure Onyx

To install Onyx, we’ll need to clone the repo and set the necessary environment variables.

git clone --depth 1 https://github.com/onyx-dot-app/onyx.git

cd onyx/deployment/docker_compose
cp env.prod.template .env
cp env.nginx.template .env.nginx

Fill out the .env and .env.nginx files.

.env

WEB_DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"

# If your email is something like "chris@onyx.app", then this should be "onyx.app"
# This prevents people outside your company from creating an account
VALID_EMAIL_DOMAINS=<YOUR_COMPANIES_EMAIL_DOMAIN>

# Admin keys for the bundled object store. Use long random values.
S3_AWS_ACCESS_KEY_ID=<RANDOM_VALUE>
S3_AWS_SECRET_ACCESS_KEY=<RANDOM_VALUE>

Email/password login works out of the box, and SSO (Google / OIDC / SAML) is configured later from the admin panel. See our auth guides for details.

.env.nginx

DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"

Launch Onyx

Running the init-letsencrypt.sh script will get us a SSL certificate from letsencrypt and launch the Onyx stack.

./init-letsencrypt.sh

You will hit an error if you fail the letsencrypt workflow more than 5 times. You will need to wait 72 hours or request a new domain.

If you are skipping the HTTPS setup, start Onyx manually:

docker compose -f docker-compose.prod-no-letsencrypt.yml up -d

Give Onyx a few minutes to start up.You can monitor the progress with docker logs onyx-api_server-1 -f.

You can access Onyx from the instance Public IPv4 or from the domain you set up earlier!

Getting Started

Deploy Locally

Production

Craft

Onyx Anywhere

Deploy on Cloud

Authentication

Miscellaneous

Guide

Next Steps

Configure Authentication

More Onyx Configuration Options

​Guide

​Next Steps

Configure Authentication

More Onyx Configuration Options

Guide

Next Steps