Skip to main content
A single Droplet is the simplest way to self-host Onyx on DigitalOcean.

​
Guide

1

Create a Droplet

Create a Droplet with the appropriate resources. This guide uses the Marketplace image with Docker pre-installed.
  • Give your Droplet a descriptive name like onyx-prod
  • Select a region close to your users
  • Select the Docker image from the Marketplace tab
  • Choose a Droplet size with at least 4 vCPUs and 16GB RAM
  • Configure storage following the Resourcing guide
  • Add your SSH key for secure access
2

Create the Droplet

Click Create Droplet and then view your Droplet details.
Save the Public IP address of the Droplet.
Digital Ocean Public IP Address
3

Open HTTPS

The Docker image ships with the ufw firewall enabled. Allow web traffic:
4

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.DNS A Record ConfigurationDNS CNAME Record Configuration
5

Install Onyx requirements

The Docker Marketplace image includes Docker and the docker compose plugin.Install git:
Prefer a guided install? The Onyx CLI writes the configuration and manages upgrades for you. Skip the remaining steps if you use it.
6

Install and Configure Onyx

To install Onyx, we’ll need to clone the repo and set the necessary environment variables.
Fill out the .env and .env.nginx files.
.env
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
7

Launch Onyx

Running the init-letsencrypt.sh script will get us a SSL certificate from letsencrypt and launch the Onyx stack.
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:
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!

​
Next Steps

Configure Authentication

Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.

More Onyx Configuration Options

Learn about all available configuration options for your Onyx deployment.