> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Release Process & Updates

> Onyx release process, versioning, and recommended update process

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

## Release Channels

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

### GitHub

Our [GitHub Releases](https://github.com/onyx-dot-app/onyx/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](https://github.com/onyx-dot-app/onyx) is our development branch.

<Warning>
  Although we try to keep `main` stable through CI/CD tests and code reviews,
  we do not recommend using `main` in production environments.
</Warning>

### Docker Hub

[Docker Hub](https://hub.docker.com/r/onyxdotapp/onyx) 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.

<Tip>
  If you don't specify a version when deploying Onyx, you will get the latest nightly builds.
</Tip>

## Versioning Scheme

Onyx follows [Semantic Versioning (SemVer)](https://semver.org/) 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`

<Note>
  - **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
</Note>

### 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`.

<Steps>
  <Step title="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.

    ```bash theme={null}
    curl -X GET "https://cloud.onyx.app/api/versions"
    ```

    Look for the `stable: onyx` key in the response.

    ```json Example Response expandable theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Step>

  <Step title="Launch Onyx with the Version Tag">
    How you launch the specific Onyx version will depend on your deployment process.

    <Note>
      Don't forget the `v` prefix! I.e. `v1.2.3` is correct, `1.2.3` is incorrect.
    </Note>

    <AccordionGroup>
      <Accordion title="Docker Pull Images">
        Specify the version tag in the environment.

        ```bash theme={null}
        IMAGE_TAG=<v.MAJOR.MINOR.HOTFIX> docker compose -f docker-compose.dev.yml -p onyx-stack up -d --pull always --force-recreate
        ```
      </Accordion>
    </AccordionGroup>

    <Accordion title="Docker Build Images">
      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:

      ```bash From Release Branch theme={null}
      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
      ```

      ```bash From Tagged Version theme={null}
      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
      ```
    </Accordion>

    <Accordion title="Helm">
      To specify a version when deploying with Helm, set the `global: version` value in your `values.yaml` file.

      ```yaml values.yaml theme={null}
      global:
        version: "v1.2.3"
      ```
    </Accordion>
  </Step>
</Steps>