Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(deploy): publish standalone compose as GHCR artifact, run from images (CHOO-1428) (#26)

Louis Amaudruzf68c0c5e68b0
diff --git a/.env.example b/.env.example
index 98d94d401..b6cce1039 100644
--- a/.env.example
+++ b/.env.example
@@ -1,6 +1,15 @@
# Switch local development configuration
# Copy to .env: cp .env.example .env
+# ── Standalone images (GHCR) ─────────────────────────────────────────────────
+# Coordinates for the published switch-core / gateway / setup images that the
+# standalone stack pulls. Defaults resolve to the latest GHCR release; pin
+# SWITCH_VERSION to a released tag (e.g. 0.3.0) for a reproducible stack.
+# Repo users building from source (`just standalone-up`) can ignore these.
+SWITCH_REGISTRY=ghcr.io
+SWITCH_IMAGE_NAMESPACE=sandbox-quantum
+SWITCH_VERSION=latest
+
# ── Switch database (docker compose) ──────────────────────────────────────────
DB_HOST=localhost
DB_PORT=5432
diff --git a/.github/workflows/switch-release.yml b/.github/workflows/switch-release.yml
index 2b6f32043..4d1e6b622 100644
--- a/.github/workflows/switch-release.yml
+++ b/.github/workflows/switch-release.yml
@@ -1,8 +1,9 @@
name: switch release
# Builds and publishes the Switch core stack — the switch-core, gateway, and
-# setup container images plus the Helm chart — so adopters can deploy without
-# building from source. See RELEASING.md for the full procedure.
+# setup container images, the Helm chart, and the standalone Docker Compose file
+# (as an OCI artifact) — so adopters can deploy without building from source.
+# See RELEASING.md for the full procedure.
#
# Trigger by pushing a tag like `switch-v0.2.0` (the version after `switch-v`
# MUST match pyproject.toml `[project].version`; the prep job verifies this).
@@ -143,3 +144,38 @@ jobs:
run: |
helm push "$RUNNER_TEMP/chart/switch-${{ needs.prep.outputs.version }}.tgz" \
"oci://$REGISTRY/$IMAGE_NAMESPACE/charts"
+
+ compose:
+ name: Publish standalone compose (OCI artifact)
+ needs: prep
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ packages: write
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Set up ORAS
+ uses: oras-project/setup-oras@v1
+
+ - name: Log in to GHCR (ORAS)
+ if: ${{ needs.prep.outputs.push == 'true' }}
+ run: |
+ echo "${{ secrets.GITHUB_TOKEN }}" | \
+ oras login "$REGISTRY" -u "${{ github.actor }}" --password-stdin
+
+ - name: Push compose artifact
+ # Publishes deploy/local/standalone-docker-compose.yml to GHCR as an OCI
+ # artifact, stamped with the same version as the images so a single tag
+ # pins the whole standalone stack. switchdash bundles this exact file at
+ # build time. `latest` moves with each release.
+ if: ${{ needs.prep.outputs.push == 'true' }}
+ working-directory: deploy/local
+ run: |
+ oras push \
+ "$REGISTRY/$IMAGE_NAMESPACE/standalone-compose:${{ needs.prep.outputs.version }},latest" \
+ --artifact-type application/vnd.switch.compose.v1+yaml \
+ --annotation "org.opencontainers.image.version=${{ needs.prep.outputs.version }}" \
+ --annotation "org.opencontainers.image.source=https://github.com/${{ github.repository }}" \
+ standalone-docker-compose.yml:application/yaml
diff --git a/RELEASING.md b/RELEASING.md
index b650cef09..634c8c732 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -1,16 +1,17 @@
# Releasing Switch
This describes how to cut a release of the **Switch core stack** — the
-`switch-core`, `gateway`, and `setup` container images plus the Helm chart. The
-switchdash desktop app releases separately (see
-`.github/workflows/switchdash-release.yml` and `dash/docs/INSTALL.md`).
+`switch-core`, `gateway`, and `setup` container images, the Helm chart, and the
+standalone Docker Compose file. The switchdash desktop app releases separately
+(see `.github/workflows/switchdash-release.yml` and `dash/docs/INSTALL.md`).
## Versioning
- Switch follows [Semantic Versioning](https://semver.org): `MAJOR.MINOR.PATCH`.
- The canonical `switch-core` version is `version` in `core/pyproject.toml`.
-- The Helm chart and the three images are published under the **same** version
- as the git tag, so a single tag pins the whole stack.
+- The Helm chart, the three images, and the standalone compose artifact are
+ published under the **same** version as the git tag, so a single tag pins the
+ whole stack.
## Cutting a release
@@ -39,12 +40,12 @@ build without creating a release.
## Where artifacts are published
-Both images and the chart go to **GitHub Container Registry (GHCR)** by default.
-While the repository is private the packages are private too; they become public
-automatically when the repository/packages are made public at the public-repo
-move (CHOO-1260). The registry and namespace are workflow env vars
-(`REGISTRY`, `IMAGE_NAMESPACE`) so retargeting to another registry (e.g. ECR) is
-a one-line change, not a rewrite.
+The images, the chart, and the standalone compose artifact all go to **GitHub
+Container Registry (GHCR)** by default. While the repository is private the
+packages are private too; they become public automatically when the
+repository/packages are made public at the public-repo move (CHOO-1260). The
+registry and namespace are workflow env vars (`REGISTRY`, `IMAGE_NAMESPACE`) so
+retargeting to another registry (e.g. ECR) is a one-line change, not a rewrite.
Consuming the published artifacts:
@@ -55,8 +56,31 @@ docker pull ghcr.io/<owner>/switch-core:<version>
# chart
helm install switch oci://ghcr.io/<owner>/charts/switch --version <version> \
-f my-values.yaml
+
+# standalone compose (OCI artifact) — pull the file, then run it
+oras pull ghcr.io/<owner>/standalone-compose:<version>
+SWITCH_VERSION=<version> docker compose -f standalone-docker-compose.yml up -d
```
+## The standalone compose as a versioned contract
+
+`deploy/local/standalone-docker-compose.yml` is published to GHCR as an OCI
+artifact (`standalone-compose:<version>`, plus `latest`) on every release,
+stamped with the same version as the images. It is a **versioned contract**:
+its service names, compose profiles, and env vars are an interface that
+consumers — chiefly switchdash's local-server mode — pin against. Treat changes
+to that interface as you would any public API change.
+
+- **Images, not builds.** Services reference published GHCR images via
+ `SWITCH_REGISTRY` / `SWITCH_IMAGE_NAMESPACE` / `SWITCH_VERSION` (see
+ `.env.example`). Repo users who want the build-from-source flow layer
+ `standalone-docker-compose.build.yml` on top — that is what `just
+ standalone-up` runs.
+- **Profiles.** Core services (`postgres`, `tuwunel`, `switch`) always start.
+ Optional services are opt-in behind profiles: `collab` (`init-db`,
+ `mattermost`, `setup`) and `gateway` (`gateway`). Enable with
+ `--profile collab --profile gateway` or `COMPOSE_PROFILES`.
+
## PyPI
`switch-core` is **not** published to PyPI. It is consumed as a container image
@@ -70,8 +94,11 @@ Everything that hardcodes the repo coordinates (`sandbox-quantum/switch`) is
centralized, so retargeting the repo is a configuration flip, not a code
change. The full list:
-- **Image + chart registry** — `REGISTRY` / `IMAGE_NAMESPACE` env vars in
- `.github/workflows/switch-release.yml`.
+- **Image + chart + compose registry** — `REGISTRY` / `IMAGE_NAMESPACE` env
+ vars in `.github/workflows/switch-release.yml`.
+- **Standalone compose image defaults** — `SWITCH_REGISTRY` /
+ `SWITCH_IMAGE_NAMESPACE` in `.env.example` (and the inline `${…:-default}`
+ fallbacks in `deploy/local/standalone-docker-compose.yml`).
- **Python package URLs** — `[project.urls]` in `core/pyproject.toml`.
- **Plugin marketplace source** — `SWITCH_MARKETPLACE_SOURCE` in
`dash/packages/plugins/src/distribution.ts` (used by the Claude
diff --git a/deploy/local/standalone-docker-compose.build.yml b/deploy/local/standalone-docker-compose.build.yml
new file mode 100644
index 000000000..3ec5dc80f
--- /dev/null
+++ b/deploy/local/standalone-docker-compose.build.yml
@@ -0,0 +1,28 @@
+# Build-from-source override for the standalone stack.
+#
+# The base standalone-docker-compose.yml pulls published GHCR images. Repo
+# users who want to build the switch-core / gateway / setup images from the
+# working tree layer this override on top, which re-adds the `build:` blocks.
+# Compose still tags the built images with the base file's `image:` name, so
+# `docker compose up` uses the local build instead of pulling.
+#
+# docker compose -f standalone-docker-compose.yml -f standalone-docker-compose.build.yml \
+# --project-directory . up -d --build
+#
+# This is what `just standalone-up` runs.
+
+services:
+ switch:
+ build:
+ context: .
+ dockerfile: deploy/shared_resources/images/Dockerfile.switch
+
+ gateway:
+ build:
+ context: .
+ dockerfile: deploy/shared_resources/images/Dockerfile.gateway
+
+ setup:
+ build:
+ context: .
+ dockerfile: deploy/shared_resources/images/Dockerfile.setup
diff --git a/deploy/local/standalone-docker-compose.yml b/deploy/local/standalone-docker-compose.yml
index fb98466af..5aa1a0a04 100644
--- a/deploy/local/standalone-docker-compose.yml
+++ b/deploy/local/standalone-docker-compose.yml
@@ -1,3 +1,26 @@
+# Standalone all-in-one Switch stack, running published GHCR images.
+#
+# This file is a VERSIONED CONTRACT: service names, profiles, and the env vars
+# below are the interface switchdash (and any other consumer) pins against. It
+# is itself published to GHCR as an OCI artifact per `switch-v*` release, tagged
+# with the same version as the images. Change the interface deliberately.
+#
+# Images are pulled from GHCR — nothing is built. Repo users who want the
+# build-from-source flow add the build override (see `just standalone-up`):
+# docker compose -f standalone-docker-compose.yml -f standalone-docker-compose.build.yml up
+#
+# Profiles keep optional services opt-in:
+# (core, no profile) postgres, tuwunel, switch — always started
+# collab init-db, mattermost, setup — Mattermost bridge + seeder
+# gateway gateway — operator dashboard
+# Select them with `--profile collab --profile gateway` or COMPOSE_PROFILES.
+#
+# Image coordinates are env-interpolated so the same file retargets registries
+# and pins versions without edits:
+# SWITCH_REGISTRY (default ghcr.io)
+# SWITCH_IMAGE_NAMESPACE (default sandbox-quantum)
+# SWITCH_VERSION (default latest)
+
services:
postgres:
image: postgres:16-alpine
@@ -17,6 +40,7 @@ services:
init-db:
image: postgres:16-alpine
+ profiles: ["collab"]
environment:
PGPASSWORD: ${DB_PASSWORD}
entrypoint: >
@@ -45,6 +69,7 @@ services:
mattermost:
image: mattermost/mattermost-team-edition:latest
+ profiles: ["collab"]
ports:
- "8065:8065"
volumes:
@@ -66,9 +91,7 @@ services:
condition: service_completed_successfully
switch:
- build:
- context: .
- dockerfile: deploy/shared_resources/images/Dockerfile.switch
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:-latest}
ports:
- "8000:8000"
environment:
@@ -94,18 +117,16 @@ services:
condition: service_started
gateway:
- build:
- context: .
- dockerfile: deploy/shared_resources/images/Dockerfile.gateway
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/gateway:${SWITCH_VERSION:-latest}
+ profiles: ["gateway"]
ports:
- "3000:3000"
depends_on:
- switch
setup:
- build:
- context: .
- dockerfile: deploy/shared_resources/images/Dockerfile.setup
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/setup:${SWITCH_VERSION:-latest}
+ profiles: ["collab"]
restart: on-failure
environment:
SWITCH_URL: http://switch:8000
diff --git a/justfile b/justfile
index d5bf8b34f..f930e47ea 100644
--- a/justfile
+++ b/justfile
@@ -79,15 +79,18 @@ gateway-build:
cd gateway && npm run build
# ── Standalone deployment (all-in-one Docker, no host toolchain) ──────────────
+# Repo users build from source: the build override re-adds the `build:` blocks
+# so images come from the working tree, not GHCR. All profiles are enabled to
+# bring up the full all-in-one stack (Mattermost bridge + gateway).
standalone-up:
- docker compose -f deploy/local/standalone-docker-compose.yml --project-directory . up -d --build
+ docker compose -f deploy/local/standalone-docker-compose.yml -f deploy/local/standalone-docker-compose.build.yml --profile collab --profile gateway --project-directory . up -d --build
standalone-down:
- docker compose -f deploy/local/standalone-docker-compose.yml --project-directory . down
+ docker compose -f deploy/local/standalone-docker-compose.yml --profile collab --profile gateway --project-directory . down
standalone-reset:
#!/usr/bin/env bash
set -euo pipefail
read -r -p "⚠️ This deletes ALL standalone data volumes (rooms, messages, agents, users). Continue? [y/N] " ans
[[ "$ans" =~ ^[Yy]$ ]] || { echo "Aborted."; exit 1; }
- docker compose -f deploy/local/standalone-docker-compose.yml --project-directory . down -v
+ docker compose -f deploy/local/standalone-docker-compose.yml --profile collab --profile gateway --project-directory . down -v