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

# Upgrades

> Upgrade your self-hosted Hyperspeed installation to a new version.

Upgrading Hyperspeed is an operator-driven process. Database schema updates run automatically when the API starts, so there is no separate migration step.

## Recommended upgrade flow

<Steps>
  <Step title="Back up first">
    Take a Postgres dump and a MinIO snapshot or mirror before touching the running stack. If something goes wrong, this is your recovery path.

    See [Backups](/administration/backups) for the exact commands.
  </Step>

  <Step title="Pull the new images and rebuild">
    From the directory that contains your `docker-compose.yml`:

    ```bash theme={null}
    docker compose pull
    docker compose up -d --build
    ```

    The API container applies any pending database updates on startup before accepting traffic.
  </Step>

  <Step title="Check the logs">
    Confirm the API started cleanly and database updates completed:

    ```bash theme={null}
    docker compose logs -f api
    ```

    Look for database update completion messages and the usual "server listening" line. Check container health:

    ```bash theme={null}
    docker compose ps
    ```
  </Step>

  <Step title="Verify the running version">
    The health endpoint reports the running version and git SHA:

    ```bash theme={null}
    curl https://your-instance/health
    ```

    The response includes `version` and `git_sha` when the image was built with those values injected (see **Version metadata** below).
  </Step>
</Steps>

## Rollback

If the new version has a critical problem, restore from the backup you took before upgrading.

<Warning>
  Avoid partial rollbacks — for example, rolling back only the API container while the database has already been updated. Schema changes may not be backward compatible. Restore the full backup (database + object storage) to a known-good state.
</Warning>

## Breaking changes

### `DEPLOYMENT_MODE` removed

The `DEPLOYMENT_MODE` environment variable no longer exists. The API always behaves as a single-organization self-hosted installation. Remove `DEPLOYMENT_MODE` from your `.env` file and any Compose overrides.

### Multiple organizations no longer supported

Support for multiple organizations in one instance was tied to the removed `saas` deployment mode. If your instance contains more than one organization (for example, after a legacy migration), the API will log a warning at startup and refuse to create additional organizations. Before upgrading, consolidate to a single organization per instance — export or archive extra organizations, or split them into separate deployments.

## Version metadata

Pass `VERSION` and `GIT_SHA` as Docker build arguments when building the API image so `GET /health` reports real values:

```bash theme={null}
docker compose build \
  --build-arg VERSION=1.2.0 \
  --build-arg GIT_SHA=$(git rev-parse HEAD)
```

With the default Compose file, you can also set `HYPERSPEED_VERSION` and `HYPERSPEED_GIT_SHA` in `.env` and the build args will be forwarded automatically.

## Optional update notices

The dashboard can display a non-intrusive banner when a newer version is available. This feature is opt-in: no network requests to GitHub or your manifest host are made until a user enables it in their dashboard settings.

To enable the feature, set one of the following environment variables on the API:

| Variable | Behavior |
| - | - |
| `UPSTREAM_GITHUB_REPO` | Set to `owner/name`. Opted-in browsers will call the GitHub releases API to check for a newer tag. |
| `UPDATE_MANIFEST_URL` | Set to an HTTPS URL returning a JSON manifest. Takes precedence over `UPSTREAM_GITHUB_REPO` if both are set. |

### Manifest format

If you use `UPDATE_MANIFEST_URL`, the endpoint must return JSON in this shape:

```json theme={null}
{
  "version": "1.2.0",
  "release_notes_url": "https://github.com/org/repo/releases/tag/v1.2.0",
  "upgrade_guide_url": "https://example.com/docs/upgrade"
}
```

`version` is required and must be a semver-compatible string. `release_notes_url` and `upgrade_guide_url` are optional and are shown as links in the banner.

<Note>
  The `dev` build string never triggers an "update available" notice, even when a newer version exists in the manifest.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.