From f936672da21c9fb9880a4ef00fa3a19076b915d4 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 25 Oct 2026 01:45:38 -0700 Subject: [PATCH 1/3] fix(self-host): pin floating Compose and Helm images Co-authored-by: kite Agent-Model: codex/gpt-6.1-sol/medium --- docker-compose.yml | 4 +-- docs/self-hosting/helm-reference.md | 42 ++++++++++++++++++++++++----- k8s/helm/commonly/README.md | 6 ++--- k8s/helm/commonly/values.yaml | 10 +++---- 4 files changed, 46 insertions(+), 16 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index aad6ed4857..8ab76fca95 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:8.2 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..ac01e2be08 100644 --- a/docs/self-hosting/helm-reference.md +++ b/docs/self-hosting/helm-reference.md @@ -27,27 +27,57 @@ 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 MongoDB to `mongo:8.2`, matching the existing +`docker-compose.dev.yml` line, and PostgreSQL to `postgres:17.11` within the dev +profile's existing major 17. The Helm MongoDB default also pins `mongo:8.2`. +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 version lines stay intact: the local Compose profile and local/staging +Helm overrides use MongoDB 7; 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 are all in use in the checked-in configuration**; unifying them is a +separate compatibility/migration change. This PR does not change existing +versioned image references or volume layouts. + +PostgreSQL's 17.11 tag was checked against the official Docker image +[version manifest](https://github.com/docker-library/postgres/blob/master/versions.json) +on 2026-10-25. 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 +222,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 +232,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..bad43a0839 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: "8.2" 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 From 86c6f0d9ffd0072609a599188cd18bd1af2c44f4 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 25 Oct 2026 02:02:28 -0700 Subject: [PATCH 2/3] fix(self-host): preserve current latest image versions when pinning Co-authored-by: kite Agent-Model: codex/gpt-6.1-sol/medium --- docker-compose.yml | 4 +-- docs/self-hosting/helm-reference.md | 51 +++++++++++++++++++---------- k8s/helm/commonly/values.yaml | 2 +- 3 files changed, 36 insertions(+), 21 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 8ab76fca95..c0c01dc8a2 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -13,7 +13,7 @@ services: # MongoDB service mongo: logging: *default-logging - image: mongo:8.2 + image: mongo:9.0.4 container_name: mongodb ports: - "27017:27017" @@ -25,7 +25,7 @@ services: # PostgreSQL service postgres: logging: *default-logging - image: postgres:17.11 + image: postgres:18.6 container_name: postgres ports: - "5432:5432" diff --git a/docs/self-hosting/helm-reference.md b/docs/self-hosting/helm-reference.md index ac01e2be08..f1fc8109a2 100644 --- a/docs/self-hosting/helm-reference.md +++ b/docs/self-hosting/helm-reference.md @@ -53,26 +53,41 @@ agents: ### Image pins (TASK-501, 2026-10-25) -The default Compose profile pins MongoDB to `mongo:8.2`, matching the existing -`docker-compose.dev.yml` line, and PostgreSQL to `postgres:17.11` within the dev -profile's existing major 17. The Helm MongoDB default also pins `mongo:8.2`. +The default Compose profile pins `mongo:9.0.4` and `postgres:18.6`. +The Helm MongoDB default also pins `mongo:9.0.4`. On 2026-10-25, Docker Hub +reported matching digests for `mongo:latest` and `mongo:9.0.4`, and for +`postgres:latest` and `postgres:18.6`. These pins preserve what the floating tags +selected at that check, instead of changing their major versions to match a +different profile. MongoDB 8.2 is end of life; its existing dev reference is +not used as the new default. + 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 version lines stay intact: the local Compose profile and local/staging -Helm overrides use MongoDB 7; 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 are all in use in the checked-in configuration**; unifying them is a -separate compatibility/migration change. This PR does not change existing -versioned image references or volume layouts. - -PostgreSQL's 17.11 tag was checked against the official Docker image -[version manifest](https://github.com/docker-library/postgres/blob/master/versions.json) -on 2026-10-25. 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. +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**; +the default Compose pin is 18.6. Unifying these versions and their volume +layouts is a separate compatibility/migration change. A PostgreSQL 18 image +requires the PostgreSQL 18 volume layout; pinning does not repair a volume +created for an older version. + +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 latest tag](https://hub.docker.com/v2/repositories/library/postgres/tags/latest) + and [18.6 tag](https://hub.docker.com/v2/repositories/library/postgres/tags/18.6): + `sha256:edb0c08dc33befd0262ab3b5cf1c4f3f8cfd8b09e88c05b45adee29d6761ddb6`. +- [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 diff --git a/k8s/helm/commonly/values.yaml b/k8s/helm/commonly/values.yaml index bad43a0839..24f9dee973 100644 --- a/k8s/helm/commonly/values.yaml +++ b/k8s/helm/commonly/values.yaml @@ -223,7 +223,7 @@ mongodb: enabled: false image: repository: mongo - tag: "8.2" + tag: "9.0.4" pullPolicy: IfNotPresent service: type: ClusterIP From d51f36c7a3f125acd22cbfc3924b157943e6adf9 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 25 Oct 2026 03:12:33 -0700 Subject: [PATCH 3/3] fix(self-host): retain PostgreSQL 17 volume compatibility Co-authored-by: kite Agent-Model: codex/gpt-6.1-sol/medium --- docker-compose.yml | 2 +- docs/self-hosting/helm-reference.md | 35 ++++++++++++++++------------- 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index c0c01dc8a2..f2d34c0c3e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -25,7 +25,7 @@ services: # PostgreSQL service postgres: logging: *default-logging - image: postgres:18.6 + 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 f1fc8109a2..056ec898f0 100644 --- a/docs/self-hosting/helm-reference.md +++ b/docs/self-hosting/helm-reference.md @@ -53,33 +53,38 @@ agents: ### Image pins (TASK-501, 2026-10-25) -The default Compose profile pins `mongo:9.0.4` and `postgres:18.6`. -The Helm MongoDB default also pins `mongo:9.0.4`. On 2026-10-25, Docker Hub -reported matching digests for `mongo:latest` and `mongo:9.0.4`, and for -`postgres:latest` and `postgres:18.6`. These pins preserve what the floating tags -selected at that check, instead of changing their major versions to match a -different profile. MongoDB 8.2 is end of life; its existing dev reference is -not used as the new default. +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**; -the default Compose pin is 18.6. Unifying these versions and their volume -layouts is a separate compatibility/migration change. A PostgreSQL 18 image -requires the PostgreSQL 18 volume layout; pinning does not repair a volume -created for an older version. +**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 latest tag](https://hub.docker.com/v2/repositories/library/postgres/tags/latest) - and [18.6 tag](https://hub.docker.com/v2/repositories/library/postgres/tags/18.6): - `sha256:edb0c08dc33befd0262ab3b5cf1c4f3f8cfd8b09e88c05b45adee29d6761ddb6`. +- [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.