diff --git a/docker-compose.yml b/docker-compose.yml index aad6ed4857..f2d34c0c3e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -13,7 +13,7 @@ services: # MongoDB service mongo: logging: *default-logging - image: mongo:latest + image: mongo:9.0.4 container_name: mongodb ports: - "27017:27017" @@ -25,7 +25,7 @@ services: # PostgreSQL service postgres: logging: *default-logging - image: postgres:latest + image: postgres:17.11 container_name: postgres ports: - "5432:5432" diff --git a/docs/self-hosting/helm-reference.md b/docs/self-hosting/helm-reference.md index 171b6dc1c3..056ec898f0 100644 --- a/docs/self-hosting/helm-reference.md +++ b/docs/self-hosting/helm-reference.md @@ -27,27 +27,77 @@ Create `values-myorg.yaml` with the fields described below. The default `values.yaml` references Commonly's private GCR registry (`gcr.io/YOUR_GCP_PROJECT_ID/...`). You must build and push images to your -own registry, or use the public images when available. +own registry, or use the public images when available. Set each application tag +to the exact build SHA you published. The chart carries the checked-in dev +snapshot tags as examples; they are not a promise that an image exists in your +registry. Reusing a mutable tag can silently change a deployment on the next pull. ```yaml backend: image: repository: your-registry/commonly-backend - tag: "latest" + tag: "YOUR_BUILD_SHA" frontend: image: repository: your-registry/commonly-frontend - tag: "latest" + tag: "YOUR_BUILD_SHA" agents: clawdbot: enabled: false # enable only when deliberately running the legacy gateway image: repository: your-registry/clawdbot-gateway - tag: "latest" + tag: "YOUR_BUILD_SHA" ``` +### Image pins (TASK-501, 2026-10-25) + +The default Compose profile pins `mongo:9.0.4` and `postgres:17.11`. +The Helm MongoDB default also pins `mongo:9.0.4`. The MongoDB pin matches the +2026-10-25 `latest` digest. MongoDB 8.2 is end of life; its existing dev +reference is not used as the new default. + +Compose deliberately uses PostgreSQL 17 to match its named-volume mount at +`/var/lib/postgresql/data`. The floating `latest` tag selected PostgreSQL 18.6, +which cannot start with that mount even on a fresh volume. Moving to PostgreSQL +18 requires a separate PR for the mount layout and `pg_upgrade`; this pin does +not migrate a volume previously written by PostgreSQL 18. + +These are self-host image choices, not a measurement of the hosted databases: +`values-dev.yaml` disables the chart's MongoDB and PostgreSQL services. +Existing versioned references stay intact: local Compose and local/staging Helm +use MongoDB 7, dev Compose uses MongoDB 8.2, base/local Helm use PostgreSQL 15, +the backup client uses 16, and dev Compose uses 17. Redis remains `7-alpine`. +**PostgreSQL 15, 16 and 17 remain in use in the checked-in configuration**. +Unifying these versions and their volume layouts is a separate migration change. +For existing MongoDB volumes, upgrade stepwise through supported releases and +set the required FCV at each stage (for example, 7.0 → 8.0 before 9.0); never +point 9.0 at a 7.0 or 8.2 volume directly. Follow the +[MongoDB 9.0 upgrade prerequisites](https://www.mongodb.com/docs/manual/release-notes/9.0-upgrade-standalone/) +for the supported 8.0/8.3 source version and FCV requirements before changing +either the Compose or Helm MongoDB pin. + +Pin evidence, checked 2026-10-25: + +- [MongoDB latest tag](https://hub.docker.com/v2/repositories/library/mongo/tags/latest) + and [9.0.4 tag](https://hub.docker.com/v2/repositories/library/mongo/tags/9.0.4): + `sha256:dc28ed5a9d0fc616903c3f463bb1e53b92b49f441721b91926e87d90bf957ce8`. +- [PostgreSQL 17.11 tag](https://hub.docker.com/v2/repositories/library/postgres/tags/17.11): + `sha256:b8faeff7712663c2773a190181e1246e37e364b887611c04658c28b44e2408fe`. +- [MongoDB lifecycle policy](https://www.mongodb.com/legal/support-policy/lifecycles) + lists 8.2 as end of life and 9.0 as supported. + +Application image defaults use the four exact snapshot tags already recorded in +`values-dev.yaml`; deployments should override them with their own published +build SHAs. No image uses a `latest` tag in these Compose/Helm defaults. Version +tags may still receive rebuilt images; use digest overrides when your release +process requires byte-for-byte image immutability. + +Before changing a pin on an existing installation, check the version that wrote +its persistent volume and follow the database's supported upgrade/downgrade +procedure. A tag edit does not migrate stored data. + ### Ingress Hosts ```yaml @@ -192,7 +242,7 @@ ingress: backend: image: repository: your-registry/commonly-backend - tag: "latest" + tag: "YOUR_BUILD_SHA" env: frontendUrl: "https://app.yourdomain.com" backendUrl: "https://api.yourdomain.com" @@ -202,7 +252,7 @@ backend: frontend: image: repository: your-registry/commonly-frontend - tag: "latest" + tag: "YOUR_BUILD_SHA" nodeSelector: {} tolerations: [] diff --git a/k8s/helm/commonly/README.md b/k8s/helm/commonly/README.md index a7a2babfe8..d54167019e 100644 --- a/k8s/helm/commonly/README.md +++ b/k8s/helm/commonly/README.md @@ -151,8 +151,8 @@ gcloud filestore instances create commonly-agent-workspaces \ helm install commonly . \ --namespace commonly --create-namespace \ --values values-dev.yaml \ - --set backend.image.tag=latest \ - --set frontend.image.tag=latest + --set backend.image.tag="$BUILD_SHA" \ + --set frontend.image.tag="$BUILD_SHA" ``` ## Configuration @@ -170,7 +170,7 @@ backend: replicaCount: 2 # Number of backend pods image: repository: gcr.io/PROJECT_ID/commonly-backend - tag: latest + tag: "YOUR_BUILD_SHA" env: nodeEnv: development agentProvisionerK8s: "1" # Enable K8s-based agent provisioning diff --git a/k8s/helm/commonly/values.yaml b/k8s/helm/commonly/values.yaml index 2123e898ba..24f9dee973 100644 --- a/k8s/helm/commonly/values.yaml +++ b/k8s/helm/commonly/values.yaml @@ -90,7 +90,7 @@ backend: replicaCount: 1 image: repository: gcr.io/YOUR_GCP_PROJECT_ID/commonly-backend - tag: latest + tag: "20260417214615-r4" pullPolicy: IfNotPresent service: type: ClusterIP @@ -199,7 +199,7 @@ frontend: replicaCount: 1 image: repository: gcr.io/YOUR_GCP_PROJECT_ID/commonly-frontend - tag: latest + tag: "20260412125218" pullPolicy: Always service: type: ClusterIP @@ -223,7 +223,7 @@ mongodb: enabled: false image: repository: mongo - tag: latest + tag: "9.0.4" pullPolicy: IfNotPresent service: type: ClusterIP @@ -326,7 +326,7 @@ agents: type: Recreate image: repository: gcr.io/YOUR_GCP_PROJECT_ID/clawdbot-gateway - tag: latest + tag: "20260414192025" pullPolicy: IfNotPresent # ADR-005 Stage 2 — codex + @commonly/cli installed by an init # container into a shared /tools volume. codexVersion pins the @@ -369,7 +369,7 @@ agents: enabled: false image: repository: gcr.io/YOUR_GCP_PROJECT_ID/commonly-bot - tag: latest + tag: "20260411055334" pullPolicy: IfNotPresent env: pollIntervalMs: 5000