Quickstart

Resourcing Overview

To host Onyx, we recommend:

Resource	Minimum	Preferred
CPU	4 vCPU	8+ vCPU
RAM	10 GB	16+ GB
Disk	50 GB + ~2.5x indexed data	500 GB for organizations <5000 users

Vespa does not allow writes once disk usage hits 75%. Make sure to always have some storage headroom.

For more details, our Resourcing guide covers selecting Cloud instances, resourcing by container, and how to scale your Onyx deployment.

Onyx CLI

Onyx CLI is coming soon! Preview the CLI below.

Onyx CLI preview

The Onyx CLI is a lightweight tool that checks your system for requirements and then deploys Onyx. By default, the tool uses images from our Docker Hub, but it can be configured to build from source.This tool should not be used for production deployments at this time.

Install Requirements

Install Onyx CLI and Check System Requirements

The Onyx CLI is installed via pip and is automatically kept up to date.

Optional: Create a virtual environment

A virtual Python environment is useful for isolating dependencies and avoiding conflicts with other projects.

If you create a virtual environment, you’ll need to activate it before running onyx CLI commands.

python3.11 -m venv ~/.onyx-venv   # create virtual environment
source ~/.onyx-venv/bin/activate  # activate virtual environment

pip install onyx-dot-app
# or pip3 install onyx-dot-app
onyx doctor

If you see any errors or warnings, please double check the system requirements and the Resourcing guide.

Useful Onyx CLI Commands

None exhaustive:

onyx help     # see all commands
onyx doctor   # pre-flight check system requirements
onyx up       # start Onyx Docker stack
onyx down     # stop Onyx Docker stack
onyx clone    # clone the Onyx repo

Launch Onyx

onyx up

Notes about this command

Configure your Deployment

Configure your deployment using a .env file.

cd ~/onyx-dot-app/onyx/deployment/docker_compose
cp env.prod.template .env

You’ll need to restart Onyx after changing any .env variables.

onyx down
onyx up

Launch with Docker

Useful if you want to extend the Onyx codebase or if you need close control over the deployment process.

The standard method to launch Onyx is using Docker Compose.

Install Requirements

Clone the Onyx repo

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

Navigate to the compose files

cd onyx/deployment/docker_compose

Launch Onyx

To pull images from Docker Hub:

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

To build images from source:

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

Configure your Deployment

Configure your deployment using a .env file.

cd ~/onyx-dot-app/onyx/deployment/docker_compose
cp env.prod.template .env

You’ll need to restart Onyx after changing any .env variables.

docker compose -f docker-compose.dev.yml -p onyx-stack down
docker compose -f docker-compose.dev.yml -p onyx-stack up -d --pull always --force-recreate

Next Steps

Learn about Resourcing

Learn about Cloud instances, resourcing by container, and how to scale your Onyx deployment.

Configure your Deployment

Learn about how to configure Onyx using environment variables.

Getting Started

Deployment Guides

Authentication

Configuration

Miscellaneous

Resourcing Overview

Onyx CLI

Launch with Docker

Next Steps

Learn about Resourcing

Configure your Deployment

Getting Started

Deployment Guides

Authentication

Configuration

Miscellaneous

​Resourcing Overview

​Onyx CLI

​Launch with Docker

​Next Steps

Learn about Resourcing

Configure your Deployment

Resourcing Overview

Onyx CLI

Launch with Docker

Next Steps