Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
feat(deploy): publish standalone compose as GHCR artifact, run from images (CHOO-1428) (#26)
Louis Amaudruzf68c0c5e68b0
diff --git a/.env.example b/.env.exampleindex 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=localhostDB_PORT=5432diff --git a/.github/workflows/switch-release.yml b/.github/workflows/switch-release.ymlindex 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/yamldiff --git a/RELEASING.md b/RELEASING.mdindex b650cef09..634c8c732 100644--- a/RELEASING.md+++ b/RELEASING.md@@ -1,16 +1,17 @@# Releasing SwitchThis 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># charthelm 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`) iscentralized, so retargeting the repo is a configuration flip, not a codechange. 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 Claudediff --git a/deploy/local/standalone-docker-compose.build.yml b/deploy/local/standalone-docker-compose.build.ymlnew file mode 100644index 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.setupdiff --git a/deploy/local/standalone-docker-compose.yml b/deploy/local/standalone-docker-compose.ymlindex 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_successfullyswitch:- 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_startedgateway:- 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:- switchsetup:- 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-failureenvironment:SWITCH_URL: http://switch:8000diff --git a/justfile b/justfileindex 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 --buildstandalone-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 . downstandalone-reset:#!/usr/bin/env bashset -euo pipefailread -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