GCP

Make sure your Google Cloud Platform account has the necessary permissions to create a VM instance.

Create a VM instance#

Create a VM instance with the appropriate resources. For this guide, we will use the recommended e2-standard-4 instance.

Read our Resourcing guide for more details.

• Give your instance a descriptive name like onyx-prod

• Select the Debian GNU/Linux 12 boot disk

• Select the e2-standard-4 machine type

• Select Allow HTTPS traffic in the Firewall section

• Configure storage following the Resourcing Guide

Create the instance#

Click Create and then view your instance details.

Save the External IP of the instance!

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 Nexus 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 Nexus requirements#

Nexus requires git, docker, and docker compose.

To install these on Debian GNU/Linux 12, run the following:

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

  sudo install -m 0755 -d /etc/apt/keyrings
  curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
  sudo chmod a+r /etc/apt/keyrings/docker.gpg
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

  sudo apt update
  sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

If using CentOS, Red Hat Linux, or similar, 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

Install and Configure Nexus#

To install Nexus, 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.

  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 school from creating an account
  VALID_EMAIL_DOMAINS=<YOUR_COMPANIES_EMAIL_DOMAIN>

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.

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

Launch Nexus#

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

  docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate

Give Nexus a few minutes to start up.

You can monitor the progress with `docker logs onyx-stack-api_server-1 -f`.

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

Next Steps#

Configure Authentication#

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

More Nexus Configuration Options#

Learn about all available configuration options for your Nexus deployment.