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

1. 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 for the exact commands.

2. Pull the new images and rebuild

   From the directory that contains your docker-compose.yml:

   docker compose pull
   docker compose up -d --build
   

   The API container applies any pending database updates on startup before accepting traffic.

3. Check the logs

   Confirm the API started cleanly and database updates completed:

   docker compose logs -f api
   

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

   docker compose ps
   
4. Verify the running version

   The health endpoint reports the running version and git SHA:

   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).

Rollback

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

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.

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:

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:

{
  "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.

The dev build string never triggers an “update available” notice, even when a newer version exists in the manifest.