From 5d55750b7b0381abeb16732e1671b06823dd17eb Mon Sep 17 00:00:00 2001
From: Alex Holliday <ajhollid@gmail.com>
Date: Mon, 13 Jul 2026 09:38:55 -0700
Subject: [PATCH] update docs

---
 README.md                           | 21 +++++++++++++++++++++
 docs/hosting/checkmate-so/README.md |  4 +++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 05eb688ff..2841149ca 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,27 @@ JWT_SECRET="$(openssl rand -hex 32)" docker compose up -d
 
 Then open http://localhost:52345. If the app is reached at another origin (domain or LAN IP), set `CLIENT_HOST` accordingly. To build the image yourself, run `docker build -f docker/Dockerfile -t checkmate .` from a checkout. For TLS, put any reverse proxy (Caddy, Traefik, nginx) in front of port 52345.
 
+### Configuration
+
+The image is configured entirely through environment variables on the server container:
+
+| Variable | Required | Description |
+|---|---|---|
+| `DB_CONNECTION_STRING` | Yes | MongoDB connection string, e.g. `mongodb://mongodb:27017/uptime_db` |
+| `JWT_SECRET` | Yes | Secret used to sign auth tokens; generate one with `openssl rand -hex 32` |
+| `CLIENT_HOST` | Yes | The URL users reach the app at, e.g. `https://checkmate.example.com`; used for CORS and for links in notifications and emails |
+| `LOG_LEVEL` | No | Server log level: `error`, `warn`, `info`, or `debug` (default `debug`) |
+
+The web client needs no configuration by default: it calls the API on the same origin it was served from (`/api/v1`). For setups where the defaults don't apply — for example, the API is reached through a different origin than the page — the server renders overrides into the client at runtime via these optional variables:
+
+| Variable | Description |
+|---|---|
+| `CLIENT_CONFIG_API_BASE_URL` | Full base URL the client calls the API at, e.g. `https://api.example.com/api/v1`; defaults to same-origin `/api/v1` |
+| `CLIENT_CONFIG_CLIENT_HOST` | Origin used when the client builds absolute links (invites, status pages); defaults to the browser's current origin |
+| `CLIENT_CONFIG_LOG_LEVEL` | Browser console log level: `error`, `warn`, `info`, or `debug` (default `error`) |
+
+> **Upgrading from an older image?** The `UPTIME_APP_*` variables (`UPTIME_APP_API_BASE_URL`, `UPTIME_APP_CLIENT_HOST`, `UPTIME_APP_LOG_LEVEL`) are no longer read. In most setups no replacement is needed — the same-origin defaults cover them; if you pointed the client at a different origin, use the `CLIENT_CONFIG_*` equivalents above. The `checkmate-client`, `checkmate-backend`, `checkmate-mongo`, and `checkmate-backend-mono-multiarch` images are no longer updated — switch to `ghcr.io/bluewave-labs/checkmate`, keeping your existing MongoDB service and data volume.
+
 See full installation instructions in the [Checkmate documentation portal](https://checkmate.so/docs). 
 
 Alternatively, you can also use [Coolify](https://coolify.io/), [Elestio](https://elest.io/open-source/checkmate), [K8s](./charts/helm/checkmate/INSTALLATION.md), [Sive Host](https://sive.host) (South Africa), [Cloudzy](https://cloudzy.com/marketplace/checkmate) or [Pikapods](https://www.pikapods.com/) to quickly spin off a Checkmate instance. If you would like to monitor your server infrastructure, you'll need [Capture agent](https://github.com/bluewave-labs/capture). Capture repository also contains the installation instructions.
diff --git a/docs/hosting/checkmate-so/README.md b/docs/hosting/checkmate-so/README.md
index 2a7e9f648..0c06f6948 100644
--- a/docs/hosting/checkmate-so/README.md
+++ b/docs/hosting/checkmate-so/README.md
@@ -29,7 +29,9 @@ Kept next to this compose file on the host:
 
 - `server-prod.env` / `server-staging.env` — Checkmate server env
   (`DB_CONNECTION_STRING`, `JWT_SECRET`, `CLIENT_HOST=https://demo.checkmate.so`
-  etc.). The old `UPTIME_APP_*` client vars are no-ops now and can be removed.
+  etc.). The old `UPTIME_APP_*` client vars are no-ops now and can be removed;
+  if a client override is ever needed, use the `CLIENT_CONFIG_*` vars (see the
+  Configuration section of the root README).
 - `mongo-prod.env` / `mongo-staging.env` — Mongo credentials.
 - `mongo/data-prod` / `mongo/data-staging` — Mongo data directories.