Document what a new version can refuse, and bump to 1.13.0 (#25)

Three releases in a row have tightened what the config accepts, and until
now the only place that was written down was the error message itself. A new
docs/upgrading.md answers each one: the dry run to do first, what actually
happens per deployment if you skip it, and then a section per refusal
headed by the verbatim message so that pasting a log line finds it.

The seven messages in that page were generated by running -check against a
config that trips each one, not copied from the source. A page like this is
worthless if a character drifts.

The deployment section is the part worth reading twice. A running instance
that reloads keeps its pages. A Kubernetes rollout stalls on 503 readiness
and the old pod keeps serving. Compose restarted comes back healthy on
liveness and serves the getting-started page instead of the site, which is
the one case the dry run exists for, so docker-compose.md now says so where
the image tags are chosen.

Linked from the README table, the docs index and llms.txt, and every pinned
1.12.0 in the chart and the deployment pages moves to 1.13.0.

Author: MorganKryze

README.md

@@ -167,7 +167,7 @@ understanding how a thing works, start anywhere below.
 
 |               |                                                                                                                                                                                                                                                                                                                        |
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Start**     | [Getting started](docs/getting-started.md), the five-minute path                                                                                                                                                                                                                                                       |
+| **Start**     | [Getting started](docs/getting-started.md), the five-minute path · [Upgrading](docs/upgrading.md), what a new version can refuse and how to fix it                                                                                                                                                                     |
 | **Configure** | [Services](docs/configuration/services.md) · [Site](docs/configuration/site.md) · [Text](docs/configuration/text.md) · [Theming](docs/configuration/theming.md) · [Languages](docs/configuration/i18n.md)                                                                                                              |
 | **Deploy**    | [Docker Compose](docs/deployment/docker-compose.md) · [Podman](docs/deployment/podman.md) · [Bare binary](docs/deployment/binary.md) · [Kubernetes](docs/deployment/kubernetes.md) · [Helm](docs/deployment/helm.md) · [Air-gapped](docs/deployment/airgap.md) · [Reverse proxies](docs/deployment/reverse-proxies.md) |
 | **Recipes**   | [Status page with Gatus](docs/recipes/gatus.md) · [Icons](docs/recipes/icons.md) · [Multiple files](docs/recipes/multiple-files.md) · [Migration](docs/recipes/migration.md)                                                                                                                                           |

charts/cairn/Chart.yaml

@@ -7,8 +7,8 @@ type: application
 # the chart, so a published chart always carries the cairn it installs. What
 # is written here only matters to someone running `helm install ./charts/cairn`
 # from a checkout.
-version: 1.12.0
-appVersion: "1.12.0"
+version: 1.13.0
+appVersion: "1.13.0"
 
 # networking.k8s.io/v1 Ingress, which is 1.19 and later. Declaring it here
 # means the templates can use one API version instead of sniffing .Capabilities.

docs/README.md

@@ -6,6 +6,7 @@ reading anything: <https://cairn.libresoftware.cloud>.
 ## First steps
 
 - [Getting started](getting-started.md): zero to a served page in five minutes.
+- [Upgrading](upgrading.md): what a new version can refuse, each message and its fix.
 
 ## Configuration
 

docs/deployment/airgap.md

@@ -14,7 +14,7 @@ page renders, and the icons are simply missing.
 
 | Artifact             | Size     | Where it comes from                                            |
 | -------------------- | -------- | -------------------------------------------------------------- |
-| `cairn-1.12.0.tgz`   | 4 KB     | `helm pull`, the signed artifact rather than the folder in git |
+| `cairn-1.13.0.tgz`   | 4 KB     | `helm pull`, the signed artifact rather than the folder in git |
 | `gatus-1.5.0.tgz`    | 9 KB     | the Gatus project's own chart                                  |
 | `images.tar`         | 26 MB    | `docker save` of cairn and Gatus                               |
 | `assets/icons/*.svg` | a few KB | what `cairn -emit-icons` downloads                             |
@@ -32,14 +32,14 @@ The order matters. `cosign verify` queries the public transparency log, so it is
 not something you get to do on the other side.
 
 ```sh
-helm pull oci://ghcr.io/morgankryze/charts/cairn --version 1.12.0
+helm pull oci://ghcr.io/morgankryze/charts/cairn --version 1.13.0
 
-cosign verify ghcr.io/morgankryze/charts/cairn:1.12.0 \
+cosign verify ghcr.io/morgankryze/charts/cairn:1.13.0 \
   --certificate-identity-regexp '^https://github.com/MorganKryze/cairn/' \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com
 ```
 
-The same two lines for `ghcr.io/morgankryze/cairn:1.12.0`, the image. Keep the
+The same two lines for `ghcr.io/morgankryze/cairn:1.13.0`, the image. Keep the
 output: this is the only moment where you can prove where these bytes came from.
 
 Gatus publishes its own chart, from a classic repository rather than a registry,
@@ -64,7 +64,7 @@ amd64 cluster from an arm64 laptop is the classic way to learn this at
 ```sh
 PLATFORM=linux/amd64
 
-docker pull --platform $PLATFORM ghcr.io/morgankryze/cairn:1.12.0
+docker pull --platform $PLATFORM ghcr.io/morgankryze/cairn:1.13.0
 docker pull --platform $PLATFORM ghcr.io/twin/gatus:v5.36.0
 ```
 
@@ -75,9 +75,9 @@ names nothing you can reason about six months later. To be exact, v5.36.0 is
 Then give both the name they will carry inside, and save them together:
 
 ```sh
-docker tag ghcr.io/morgankryze/cairn:1.12.0 harbor.internal/cairn:1.12.0
+docker tag ghcr.io/morgankryze/cairn:1.13.0 harbor.internal/cairn:1.13.0
 docker tag ghcr.io/twin/gatus:v5.36.0 harbor.internal/gatus:5.36.0
-docker save harbor.internal/cairn:1.12.0 harbor.internal/gatus:5.36.0 -o images.tar
+docker save harbor.internal/cairn:1.13.0 harbor.internal/gatus:5.36.0 -o images.tar
 ```
 
 Retag even if you have no registry. An image named after a host that resolves
@@ -89,7 +89,7 @@ to have a route after all: the mistake becomes loud instead of invisible.
 This is the step nothing downstream will remind you about.
 
 ```sh
-docker run --rm -v ./config:/config ghcr.io/morgankryze/cairn:1.12.0 -emit-icons > get-icons.sh
+docker run --rm -v ./config:/config ghcr.io/morgankryze/cairn:1.13.0 -emit-icons > get-icons.sh
 mkdir -p assets && (cd assets && sh ../get-icons.sh)
 ```
 
@@ -101,7 +101,7 @@ bring the files. See [Icons](../recipes/icons.md).
 ### The Gatus endpoints
 
 ```sh
-docker run --rm -v ./config:/config ghcr.io/morgankryze/cairn:1.12.0 -emit-gatus > gatus-endpoints.yaml
+docker run --rm -v ./config:/config ghcr.io/morgankryze/cairn:1.13.0 -emit-gatus > gatus-endpoints.yaml
 ```
 
 One endpoint per service, named after its id, which is how each pill finds its
@@ -111,7 +111,7 @@ service. More in [Status page](../recipes/gatus.md).
 
 ```sh
 docker run --rm -v ./config:/config:ro -v ./assets:/assets:ro \
-  ghcr.io/morgankryze/cairn:1.12.0 -check
+  ghcr.io/morgankryze/cairn:1.13.0 -check
 ```
 
 **Mount both directories.** Given only `/config`, `-check` cannot see the icons
@@ -142,7 +142,7 @@ the far side of the gap there is no fixing a broken image with a download.
 
 ```sh
 docker load -i images.tar
-docker push harbor.internal/cairn:1.12.0
+docker push harbor.internal/cairn:1.13.0
 docker push harbor.internal/gatus:5.36.0
 ```
 
@@ -152,7 +152,7 @@ Harbor, Zot or `registry:2` you already run. The chart wants one value.
 ```yaml
 image:
   repository: harbor.internal/cairn
-  tag: "1.12.0"
+  tag: "1.13.0"
 # Only if the project is private. The Secrets have to exist in the namespace
 # already; the chart names them, it does not create them.
 imagePullSecrets:
@@ -164,7 +164,7 @@ OCI artifacts, so a project named `helm` holds them next to the images and
 nothing else has to be installed:
 
 ```sh
-helm push cairn-1.12.0.tgz oci://harbor.internal/helm
+helm push cairn-1.13.0.tgz oci://harbor.internal/helm
 helm push gatus-1.5.0.tgz oci://harbor.internal/helm
 ```
 
@@ -199,7 +199,7 @@ it worked:
 
 ```console
 $ kubectl get events --field-selector reason=Pulled
-Container image "harbor.internal/cairn:1.12.0" already present on machine
+Container image "harbor.internal/cairn:1.13.0" already present on machine
 Container image "harbor.internal/gatus:5.36.0" already present on machine
 ```
 
@@ -223,7 +223,7 @@ under `binaryData` on its own.
 # values.yaml
 image:
   repository: harbor.internal/cairn
-  tag: "1.12.0"
+  tag: "1.13.0"
 
 config:
   site.yaml: |
@@ -272,7 +272,7 @@ and one version to name, which is also what Argo CD will read:
 
 ```sh
 helm registry login harbor.internal --ca-file /etc/pki/internal-ca.crt
-helm install cairn oci://harbor.internal/helm/cairn --version 1.12.0 \
+helm install cairn oci://harbor.internal/helm/cairn --version 1.13.0 \
   --ca-file /etc/pki/internal-ca.crt -f values.yaml
 ```
 
@@ -289,7 +289,7 @@ credential store: a `docker login` already done on that host does not count.
 Without a registry, install what you carried:
 
 ```sh
-helm install cairn ./cairn-1.12.0.tgz -f values.yaml
+helm install cairn ./cairn-1.13.0.tgz -f values.yaml
 ```
 
 `linked: false` is a decision rather than an omission. Without it the pills link

docs/deployment/docker-compose.md

@@ -68,6 +68,17 @@ test suite inside the build:
 | `unstable`          | every commit on `main`                                  |
 | a commit hash       | that exact build                                        |
 
+Following `latest` or `stable` means a new version arrives on its own. A
+release occasionally tightens what the config accepts, and this is the
+deployment where that shows: `/healthz` is liveness and stays green, so the
+container comes back up healthy and serves the getting-started page instead of
+your site. One command tells you beforehand, and
+[Upgrading](../upgrading.md) is the page that answers whatever it prints:
+
+```sh
+docker run --rm -v ./config:/config ghcr.io/morgankryze/cairn:stable -check
+```
+
 To build from source instead, replace `image:` with:
 
 ```yaml

docs/deployment/helm.md

@@ -26,8 +26,8 @@ kubectl port-forward svc/cairn 8080:80
 
 Add `--version` with the number from the
 [releases](https://github.com/MorganKryze/cairn/releases) to pin. Chart version
-and cairn version are the same number, always: chart `1.12.0` installs cairn
-`1.12.0`, so there is only ever one version to talk about, and `image.tag` is
+and cairn version are the same number, always: chart `1.13.0` installs cairn
+`1.13.0`, so there is only ever one version to talk about, and `image.tag` is
 there if you ever want to break the pair apart.
 
 ## Feeding it your config
@@ -209,8 +209,8 @@ OCI artifact, so it can be mirrored into whatever registry you already keep, and
 driven from there:
 
 ```sh
-helm pull oci://ghcr.io/morgankryze/charts/cairn --version 1.12.0
-helm push cairn-1.12.0.tgz oci://harbor.internal/helm
+helm pull oci://ghcr.io/morgankryze/charts/cairn --version 1.13.0
+helm push cairn-1.13.0.tgz oci://harbor.internal/helm
 ```
 
 Argo CD needs the repository declared before an Application can name it. Note
@@ -246,7 +246,7 @@ spec:
   source:
     repoURL: harbor.internal/helm
     chart: cairn
-    targetRevision: 1.12.0
+    targetRevision: 1.13.0
     helm:
       valuesObject:
         ingress:
@@ -270,7 +270,7 @@ spec:
   sources:
     - repoURL: harbor.internal/helm
       chart: cairn
-      targetRevision: 1.12.0
+      targetRevision: 1.13.0
       helm:
         valueFiles:
           - $values/cairn/values.yaml
@@ -297,7 +297,7 @@ The chart is signed the same way the image is, keylessly, bound to the workflow
 that published it:
 
 ```sh
-cosign verify ghcr.io/morgankryze/charts/cairn:1.12.0 \
+cosign verify ghcr.io/morgankryze/charts/cairn:1.13.0 \
   --certificate-identity-regexp '^https://github.com/MorganKryze/cairn/' \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com
 ```