You can use a DigitalOcean Droplet to deploy Onyx. This is a simple and cost effective way to deploy Onyx and should meet the performance needs of smaller organizations looking to use Onyx. Feel free to reach out to us via the links on our Contact Us page for more individual help.

​
Getting an Instance

Create a new Droplet in the Digital Ocean console.
  1. Open the Digital Ocean Console and select Create Droplet.
  2. Select a region close to your users and a datacenter.
  3. Select a Docker image from the Marketplace tab.
  4. Choose the size of the Droplet. We recommend at least 16GB of RAM, 4-8vCPU cores, and 500GB of disk for a small-mid sized organization (< 5000 users).
  5. Select additional options as needed and assign your Droplet to a Project.
  6. Select Create Droplet.

​
Create a Domain record

Use @ to create the record at the root of the domain or enter a hostname to create it elsewhere. A records are for IPv4 addresses only and tell a request where your domain should direct to.
  1. Go to the Networking section of the Digital Ocean console.
  2. Click Add Domain.
  3. Enter your domain name and click Add Domain.
  4. Click Add Record and select A.
  5. Enter the hostname (usually @) and the IP address of your Droplet.
  6. Click Create Record.

​
Pointing your Domain to the Instance

Next, point your domain to the Droplet. To do this, you’ll need to add two records to your DNS and set your Nameservers to Digital Ocean’s. Nameservers control how your website is located based on your domain name.
If you don’t have a domain to use yet, then you can either buy one from a DNS provider like GoDaddy or just skip HTTPS for now.
Adding DNS Records First, we need to grab the public IP address of the instance. You can do that in the page for your instance in the Digital Ocean Droplet Console. Instance Finally, we need to head to the DNS provider and add two entries into the DNS: Instance Instance The first record directs traffic to that domain to your Droplet. The second record will handle www.<YOUR_DOMAIN> and ensure that this also takes the user to your container running on your Droplet. Setting Nameservers Next, we need to set the nameservers to Digital Ocean’s. Digital Ocean’s nameservers are:
  • ns1.digitalocean.com
  • ns2.digitalocean.com
  • ns3.digitalocean.com
These need to be set in the DNS provider’s console.

​
Starting up Onyx

Because your Droplet is running Docker, we can use Docker Compose to start up Onyx. Once the Droplet agent is installed (and configured if necessary), you can access the Droplet Console from the DigitalOcean Control Panel. First, click the name of the Droplet you want to access to expand its detail window, then click the name again to go to its detail page. From the detail page, click the Access tab in the left menu. In the Droplet Console section, enter the user you want to log in as in the Log in as… field. By default, this is set to root. Once you choose a user, click Launch Droplet Console to open the Droplet console. When the console loads, you can use the command line to run commands on your Droplet. Clone the repo: 
git clone https://github.com/onyx-dot-app/onyx.git
Next, let’s set the necessary env variables: 
cd onyx/deployment/docker_compose
touch .env
touch .env.nginx
In the .env file, you can copy past the following (filling in the missing fields as needed): 
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>

AUTH_TYPE=basic
# if you want to enable email verification, uncomment the following
# REQUIRE_EMAIL_VERIFICATION=true
# SMTP_USER=<GMAIL_ACCOUNT_EMAIL_YOU_WANT_TO_SEND_VERIFICATION_EMAILS_WITH>
# SMTP_PASS=<GMAIL_ACCOUNT_PW_YOU_WANT_TO_SEND_VERIFICATION_EMAILS_WITH>

# if you've gone through the Google OAuth setup guide, then comment out
# the above and uncomment the following
# AUTH_TYPE=google_oauth
# GOOGLE_OAUTH_CLIENT_ID=
# GOOGLE_OAUTH_CLIENT_SECRET=
# SECRET=<RANDOMLY_GENERATED_UUID>

GEN_AI_MODEL_PROVIDER=openai
GEN_AI_MODEL_VERSION=gpt-4  # if it's an option, we recommend using gpt-4

# Default values here are what Postgres uses by default, feel free to change.
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
In the .env.nginx file, put the following: 
DOMAIN=<YOUR_DOMAIN>  # something like "onyx.app"
Next, let’s get our SSL certificate from letsencrypt. To do this, we can simply run: 
./init-letsencrypt.sh
If are skipping the HTTPS setup, you should start things up with: docker-compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate instead of the above. You can then access Onyx from the IP address from earlier or from the instance Public IPv4 DNS provided on the instance’s page in the DigitalOcean console.
Voila, you’re all done! 🎉 After waiting a few minutes (you can monitor the progress with docker logs onyx-stack-api_server-1 -f; once you see a log for INFO: Application startup complete. then everything should be good to go).