From 3b6e95ed6c2e597f1065b93e367044d3b6f3da40 Mon Sep 17 00:00:00 2001 From: Lucas Rayan Date: Sun, 2 Aug 2026 19:29:54 -0300 Subject: [PATCH] #23: record the other half of the image-tag trap A pinned IMAGE_TAG solves 'latest never re-pulls' and introduces the mirror problem: the pin is an instruction to run that exact image, so deploying without bumping it re-pulls the old build and reports success. Redeploying with 'ignore cache' does not help - that clears the build cache, and nothing is built on the server. Documents the two-step release and the asset-fingerprint check that tells you which image is actually serving, rather than trusting a green deployment log. Co-Authored-By: Claude Opus 5 --- docs/DEPLOYMENT.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 2f82fe5..ad0765f 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -201,6 +201,32 @@ The tags are published by `release.yml`; `docker buildx imagetools inspect ghcr.io//lambdamail/webmail:latest` shows what `latest` currently points at. +**Pinning has a second edge: bump it on every release.** A pinned tag is an +instruction to run *that* image, so a deploy triggered without changing it +re-pulls the same old build and succeeds — the UI simply does not change. +Redeploying with "ignore cache" does not help, because that clears the *build* +cache and nothing here is built on the server; the tag being requested is still +the old one. The two failure modes are mirror images: `latest` never updates +because Docker already has it, and a stale pin never updates because you asked +for it by name. + +So a release is two steps, not one: + +```bash +# 1. point the tag at the new commit +IMAGE_TAG=sha-$(git rev-parse HEAD) +# 2. then deploy +``` + +Confirm which one is actually serving before believing a green deployment: + +```bash +curl -s https:///user/login | grep -o '/_next/static/css/[a-z0-9]*\.css' +``` + +The asset fingerprint changes with every build. If it did not move, the old +image is still running whatever the deployment log said. + ## Troubleshooting **The web UI is up but nothing can log in.** The auth service refuses to start