Skip to main content
This page explains Onyx’s release process, versioning scheme, and how updates are delivered to different deployment channels.

​
Release Channels

Onyx maintains multiple release channels to provide stable and development versions for different use cases.

​
GitHub

Our GitHub Releases publish images to Docker Hub. Onyx has two types of releases:
  • Latest stable version - Production-ready releases
  • Pre-release version - Beta releases for testing
The main branch of the Onyx repository is our development branch.
Although we try to keep main stable through CI/CD tests and code reviews, we do not recommend using main in production environments.

​
Docker Hub

Docker Hub hosts the actual container images. New images are published every night from the main branch and when a new release is cut. To identify the latest images programmatically, use our API endpoint: 
https://cloud.onyx.app/api/versions
This endpoint returns the current latest stable and beta versions available on Docker Hub.
If you don’t specify a version when deploying Onyx, you will get the latest nightly builds.

​
Versioning Scheme

Onyx follows Semantic Versioning (SemVer) with a clear, predictable format. Standard Version Format: 
major.minor.hotfix
Pre-release Version Format: 
major.minor.hotfix-beta.betahotfix
Examples:
  • Stable release: 1.2.3
  • Pre-release: 1.3.0-beta.1
  • Beta hotfix: 1.3.0-beta.2
  • Major version - Incremented on breaking changes
  • Minor version - Incremented on new features, bugfixes, and backwards-compatible changes
  • Hotfix version - Incremented only when backporting bugfixes to releases

​
Docker Files and Helm Charts

Changes to Docker files and Helm charts increment the version numbers in their respective files.

​
Release Schedule

Onyx follows a predictable weekly release cycle. Every Monday:
  • The last pre-release version is promoted to stable
  • main is frozen as the new pre-release

​
Hotfix Process

  • Critical bug fixes are backported to stable releases as necessary
  • Hotfixes bypass the normal weekly cycle for urgent production issues
  • Both stable and pre-release branches receive hotfixes when applicable

​
Update Best Practices

To maintain a stable deployment, we recommend staying on the latest stable release. These are tagged with a version number like v1.2.3.
1

Check Versions API for Stable Version Tag

Compare your current version with the version tag of the latest stable release. The versions endpoint is public and does not require authentication.
curl -X GET "https://cloud.onyx.app/api/versions"
Look for the stable: onyx key in the response.
Example Response
{
  "stable":{
    "onyx":"v1.8.1",
    "relational_db":"postgres:15.2-alpine",
    "index":"vespaengine/vespa:8.277.17",
    "nginx":"nginx:1.23.4-alpine"},
    "dev":{
      "onyx":"v1.9.0-beta.0",
      "relational_db":"postgres:15.2-alpine",
      "index":"vespaengine/vespa:8.277.17",
      "nginx":"nginx:1.23.4-alpine"
    },
    "migration":{
      "onyx":"airgapped-intfloat-nomic-migration",
      "relational_db":"postgres:15.2-alpine",
      "index":"vespaengine/vespa:8.277.17",
      "nginx":"nginx:1.23.4-alpine"
    }
  }
}
2

Launch Onyx with the Version Tag

How you launch the specific Onyx version will depend on your deployment process.
Don’t forget the v prefix! I.e. v1.2.3 is correct, 1.2.3 is incorrect.
Specify the version tag in the environment.
IMAGE_TAG=<v.MAJOR.MINOR.HOTFIX> docker compose -f docker-compose.dev.yml -p onyx-stack up -d --pull always --force-recreate
Pull the release branch from GitHub or just the tagged version and build the images.The release branch is where the latest stable version is published. Release branches are named release/v<MAJOR>.<MINOR>.In the Onyx repo:
From Release Branch
git fetch origin release/v1.2
git switch release/v1.2

docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
From Tagged Version
git fetch origin tag v1.2.3
git switch --detach v1.2.3

docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate
To specify a version when deploying with Helm, set the global: version value in your values.yaml file.
values.yaml
global:
  version: "v1.2.3"
⌘I