Using AWS EC2 is the recommended way of deploying Onyx. It is simple to set up and should meet the performance needs of 90% of organizations looking to use Onyx!

​
Guide

1

Create an EC2 instance

Create an EC2 instance with the appropriate resources. For this guide, we will use the recommended m7g.xlarge instance.
Read our Resourcing guide for more details.
  • Give your instance a descriptive name like onyx-prod
  • Select the Amazon Linux 2023 AMI
  • Select the 64-bit (Arm) architecture
  • Select the m7g.xlarge instance type
  • Select Allow HTTPS traffic from the internet in the Network settings section
  • Configure storage following the Resourcing Guide
EC2 Instance CreationEC2 Security Group Configuration
2

Create the instance

Click Launch instance and then view your instance details.
Save the Public IPv4 address of the instance!
EC2 Public IPv4 Address
3

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

Install Onyx requirements

Onyx requires git, docker, and docker compose.To install these on Amazon Linux 2023, run the following:
sudo yum update -y

sudo yum install docker -y
sudo service docker start

sudo curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

sudo yum install git
5

Install and Configure Onyx

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

# See our auth guides for options here
AUTH_TYPE=
.env.nginx
DOMAIN=<YOUR_DOMAIN>  # Something like "onyx.app"
6

Launch Onyx

Running the init-letsencrypt.sh script will get us a SSL certificate from letsencrypt and launch the Onyx stack.
./init-letsencrypt.sh
If you are skipping the HTTPS setup, start Onyx manually:
docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
Give Onyx a few minutes to start up.You can monitor the progress with docker logs onyx-stack-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.