memhouse 0.18.8 → 0.18.10

package/examples/03-team-house/README.md

@@ -0,0 +1,129 @@
+# 03 — a team house
+
+One house, three people. An administrator invites alice, bob and carol; each installs on
+their own machine and ships. Then alice shares her memory two ways — everything with bob,
+one project with carol — and the script reads with each person's own credential to show
+exactly who can see what. Finally she withdraws both shares.
+
+## The model in four lines
+
+- Every member owns `mem.<member>_*`: five rooms (sessions, messages, tool_calls, meta,
+  events) and three stat tables. One grant on that pattern is their whole access.
+- Housemates cannot read, list, or touch each other's rooms.
+- A **full share** (`memhouse share bob`) grants `SELECT ON mem.alice_*`: every room,
+  every project, every machine, and anything ever pasted into a session.
+- A **scoped share** (`memhouse share carol --only project=alpha`) grants the three
+  transcript rooms only, each behind a row policy. The stat tables, meta and events are
+  not shared at all, because they carry no per-session filter.
+
+## What it does
+
+1. The admin runs `memhouse invite <name> --url <house>` three times. Each writes
+   `<name>.env`: the member's URL, user, password and house. **That file is a password**;
+   hand it over the way you would hand over a password.
+2. Each member runs `memhouse install --env <name>.env` in their own home. With `--yes`
+   the install also rotates the invited password to one only that machine knows, and
+   deletes the spent file. Then each ships two made-up sessions (projects `alpha` and
+   `beta`).
+3. alice: `memhouse share bob`, `memhouse share carol --only project=alpha`,
+   `memhouse share --list`.
+4. Reads, each with that person's own credential, straight against ClickHouse.
+5. alice: `memhouse share bob --revoke`, `memhouse share carol --revoke`; the reads are
+   denied again.
+
+At exit the script drops the three users and their rooms (`KEEP=1` keeps them).
+
+## Needs
+
+- Node.js 24 or newer, `npm install -g memhouse`, and `curl`
+- A **throwaway** ClickHouse and its administrator — a scratch container, a lab. The script
+  refuses to start if users named alice, bob or carol exist, and at exit it drops the ones
+  it created. [04](../04-self-hosted-team/) stands one up, or
+  a scratch container (the password comes from your environment, not the command line;
+  remove it afterwards with `docker rm -f -v memhouse-scratch`):
+
+  ```bash
+  CLICKHOUSE_PASSWORD="$MEMHOUSE_ADMIN_PASSWORD" docker run -d --name memhouse-scratch \
+    -p 127.0.0.1:8123:8123 -e CLICKHOUSE_USER=admin -e CLICKHOUSE_PASSWORD \
+    -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 clickhouse/clickhouse-server:26.7.1.1315
+  ```
+
+## Run
+
+```bash
+export MEMHOUSE_URL=https://memhouse.example.com     # what the members will reach
+export MEMHOUSE_ADMIN_USER=admin
+with-secret MEMHOUSE_ADMIN_PASSWORD=keychain:clickhouse-admin -- ./run.sh
+```
+
+A `localhost` URL works too (the script passes `--allow-local`); for real members it is
+wrong, because their `localhost` is their own machine.
+
+| Variable | Default | |
+|---|---|---|
+| `MEMHOUSE_URL` | (required) | the house endpoint the members use |
+| `MEMHOUSE_ADMIN_USER` / `MEMHOUSE_ADMIN_PASSWORD` | (required) | the administrator |
+| `MEMHOUSE_BIN` | `memhouse` | the command to run |
+| `EXAMPLE_DIR` | a new temp dir | where the three homes live |
+| `KEEP` | `0` | `1` keeps the members and their rooms |
+
+## What you should see
+
+From a run against ClickHouse 26.7.1.1315, memhouse 0.18.9 (temp paths shortened):
+
+```
+== 1. the admin invites three members
+  ✓ invite written: …/alice.env
+  ✓ invite written: …/bob.env
+  ✓ invite written: …/carol.env
+
+== 2. each member installs from their file, on their own machine (here: their own home)
+  alice:   ✓ installed
+  alice:   ✓ password rotated — this credential is now yours alone
+  alice:   ✓ removed the spent invite file …/alice.env
+  alice: [memhouse] shipped 2 sessions (0 skipped) → 6 msg rows, 2 tool rows in 0.3s
+  (bob and carol the same)
+
+== 3. alice shares: everything with bob, project alpha only with carol
+  ✓ 'bob' can now read every session in your rooms (mem.alice_*)
+  ✓ 'carol' can read your rooms in 'mem' where project=alpha
+  who can read your rooms in 'mem' — memhouse's own record, not ClickHouse's grant table:
+    bob              granted 2026-10-07  (all your rooms)
+    carol            granted 2026-10-07 scope=project=alpha
+      alice_messages project = 'alpha'
+      alice_sessions project = 'alpha'
+      alice_tool_calls project = 'alpha'
+
+== 4. who reads what — each with their own credential
+  alice, her own messages by project           alpha,beta 6
+  bob (full share), alice's messages           alpha,beta 6
+  carol (alpha only), alice's messages         alpha 3
+  bob, alice's session_stats                   2 rows
+  carol, alice's session_stats                 denied
+  carol, alice's meta                          denied
+  carol, bob's messages (never shared)         denied
+
+== 5. alice withdraws both shares
+  ✓ revoked 'bob' — SELECT withdrawn and 3 row policies dropped
+  ✓ revoked 'carol' — SELECT withdrawn and 3 row policies dropped
+  bob, alice's messages                        denied
+  carol, alice's messages                      denied
+removed alice, bob, carol, their rooms and their homes
+```
+
+The revoke line for bob counts the three policy drops memhouse attempts on every revoke;
+a full share has no policies, so none existed to drop.
+
+## For real
+
+- **The admin** runs `memhouse invite <name> --url <house URL>` once per person and hands
+  each file over a trusted channel (a password manager, `croc`, in person) — not chat or
+  e-mail. Add `--admin-user` when the admin credential is not kept on that machine; the
+  password comes from `MEMHOUSE_ADMIN_PASSWORD` or `--admin-password-file -`.
+- **Each member** runs `memhouse install --env <name>.env` on their laptop, without the
+  fixture flags, then `memhouse start` (or `memhouse service install`) to keep shipping.
+- **Sharing** is the member's own decision and needs no admin: `memhouse share <user>`,
+  `--only project=<p>` (also `session=`, `host=`, `source=`, `folder=`, `since=`,
+  `until=`), `--revoke`, `--list`.
+- A grantee reads the shared rooms with their own credential: `/mem:recall` and the other
+  agent skills, or SQL against `mem.<owner>_messages`.

package/examples/03-team-house/run.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# Example 03 — a team house: one admin, three members, two kinds of share.
+#
+# The admin invites alice, bob and carol into one house. Each installs from their invite
+# file into a home of their own (standing in for three laptops), and ships made-up
+# sessions. Then alice shares: everything with bob, project `alpha` only with carol. The
+# script reads with each person's own credential to show what they can and cannot see,
+# and finally revokes both shares.
+#
+# Run it against a THROWAWAY ClickHouse — a lab, a scratch container. It refuses to start
+# if users named alice, bob or carol already exist.
+#
+#   with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- ./run.sh
+#   KEEP=1 ...  keep the three members and their rooms afterwards (default: removed)
+#
+# Environment:
+#   MEMHOUSE_URL              required  the house's HTTP endpoint, as the members will reach it
+#   MEMHOUSE_ADMIN_USER       required  an account that can create users and grant
+#   MEMHOUSE_ADMIN_PASSWORD   required  its password — lent by with-secret, never on argv
+#   MEMHOUSE_BIN              optional  the memhouse command (default: memhouse)
+#   EXAMPLE_DIR               optional  where the three homes live (default: a new temp dir)
+set -euo pipefail
+
+HERE=$(cd "$(dirname "$0")" && pwd)
+MH=${MEMHOUSE_BIN:-memhouse}
+mh() { $MH "$@"; }
+: "${MEMHOUSE_URL:?set MEMHOUSE_URL to the house endpoint the members will use}"
+: "${MEMHOUSE_ADMIN_USER:?set MEMHOUSE_ADMIN_USER}"
+: "${MEMHOUSE_ADMIN_PASSWORD:?lend it with: with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- $0}"
+unset MEMHOUSE_USER MEMHOUSE_PASSWORD MEMHOUSE_DB
+URL=$MEMHOUSE_URL
+WORK=${EXAMPLE_DIR:-$(mktemp -d)}
+mkdir -p "$WORK"
+PEOPLE="alice bob carol"
+
+# SQL over HTTP with the password fed to curl on stdin (-K -), so it is never in argv.
+admin_q() {
+  printf 'user = "%s:%s"\n' "$MEMHOUSE_ADMIN_USER" "$MEMHOUSE_ADMIN_PASSWORD" \
+    | curl -sS -K - --data-binary "$1" "$URL/"
+}
+# The same, as one member, with the credential their own install keeps.
+as() {
+  local who=$1 sql=$2
+  ( set -a; . "$WORK/$who/env"; set +a
+    printf 'user = "%s:%s"\n' "$MEMHOUSE_USER" "$MEMHOUSE_PASSWORD" ) \
+    | curl -sS -K - --data-binary "$sql" "$URL/" 2>&1 | head -1
+}
+denied() { case "$1" in *ACCESS_DENIED*|*"Not enough privileges"*) return 0;; *) return 1;; esac; }
+
+cleanup() {
+  [ "${KEEP:-0}" = "1" ] && { echo "KEEP=1: members and rooms left in place; homes in $WORK"; return; }
+  [ "${CREATED:-0}" = "1" ] || return 0
+  for p in $PEOPLE; do
+    admin_q "DROP USER IF EXISTS $p" >/dev/null 2>&1 || true
+    for t in $(admin_q "SELECT name FROM system.tables WHERE database = 'mem' AND startsWith(name, '${p}_') FORMAT TSV" 2>/dev/null); do
+      admin_q "DROP TABLE IF EXISTS mem.$t SYNC" >/dev/null 2>&1 || true
+    done
+  done
+  rm -rf "$WORK"
+  echo "removed alice, bob, carol, their rooms and their homes"
+}
+trap cleanup EXIT
+
+# Refuse anything this run did not make: the users, and any table under their room prefixes
+# (orphaned rooms can outlive their users). The cleanup below drops by those prefixes, so it
+# may only run when this check proved them empty first.
+existing=$(admin_q "SELECT count() FROM system.users WHERE name IN ('alice','bob','carol') FORMAT TSV")
+[ "$existing" = "0" ] || { echo "refusing: users alice/bob/carol already exist on this server — use a throwaway ClickHouse"; exit 1; }
+rooms=$(admin_q "SELECT count() FROM system.tables WHERE database = 'mem' AND (startsWith(name, 'alice_') OR startsWith(name, 'bob_') OR startsWith(name, 'carol_')) FORMAT TSV")
+[ "$rooms" = "0" ] || { echo "refusing: mem.alice_*/bob_*/carol_* tables already exist ($rooms) — use a throwaway ClickHouse"; exit 1; }
+CREATED=1
+
+# A loopback URL is right only through a tunnel; invite refuses one unless told so.
+case "$URL" in http://localhost*|http://127.0.0.1*|https://localhost*|https://127.0.0.1*) LOCAL=--allow-local;; *) LOCAL=;; esac
+
+echo "== 1. the admin invites three members"
+# The admin needs no install of their own: an empty home, so nothing stored is read.
+export MEMHOUSE_HOME="$WORK/admin"; mkdir -p "$MEMHOUSE_HOME"
+for p in $PEOPLE; do
+  # One env file per person. It IS a password: hand it over through a trusted channel.
+  out=$(cd "$WORK" && mh invite "$p" --url "$URL" --admin-user "$MEMHOUSE_ADMIN_USER" --out "$WORK/$p.env" $LOCAL 2>&1) \
+    || { printf '%s\n' "$out"; exit 1; }
+  printf '%s\n' "$out" | grep "invite written"
+done
+
+echo
+echo "== 2. each member installs from their file, on their own machine (here: their own home)"
+for p in $PEOPLE; do
+  export MEMHOUSE_HOME="$WORK/$p"; mkdir -p "$MEMHOUSE_HOME"
+  node "$HERE/../fixtures/make-sessions.js" "$MEMHOUSE_HOME/sessions" "$p" alpha beta >/dev/null
+  # --yes also rotates the invited password to one only this home knows, and deletes the file.
+  out=$(unset MEMHOUSE_ADMIN_USER MEMHOUSE_ADMIN_PASSWORD
+        mh install --env "$WORK/$p.env" --editors claude --claude-roots "$MEMHOUSE_HOME/sessions" --yes --no-ship 2>&1) \
+    || { printf '%s\n' "$out"; exit 1; }
+  printf '%s\n' "$out" | grep -E "installed$|rotat|removed the spent" | sed "s/^/  $p: /" || true
+  (unset MEMHOUSE_ADMIN_USER MEMHOUSE_ADMIN_PASSWORD; mh ship) | sed "s/^/  $p: /"
+done
+unset MEMHOUSE_HOME
+
+echo
+echo "== 3. alice shares: everything with bob, project alpha only with carol"
+export MEMHOUSE_HOME="$WORK/alice"
+mh share bob --yes
+mh share carol --only project=alpha --yes
+mh share --list
+
+echo
+echo "== 4. who reads what — each with their own credential"
+show() { printf '  %-44s %s\n' "$1" "$2"; }
+show "alice, her own messages by project"   "$(as alice "SELECT arrayStringConcat(arraySort(groupUniqArray(project)), ',') || ' ' || toString(count()) FROM mem.alice_messages FORMAT TSV")"
+show "bob (full share), alice's messages"   "$(as bob   "SELECT arrayStringConcat(arraySort(groupUniqArray(project)), ',') || ' ' || toString(count()) FROM mem.alice_messages FORMAT TSV")"
+show "carol (alpha only), alice's messages" "$(as carol "SELECT arrayStringConcat(arraySort(groupUniqArray(project)), ',') || ' ' || toString(count()) FROM mem.alice_messages FORMAT TSV")"
+r=$(as bob "SELECT count() FROM mem.alice_session_stats FORMAT TSV");   show "bob, alice's session_stats"   "$(denied "$r" && echo denied || echo "$r rows")"
+r=$(as carol "SELECT count() FROM mem.alice_session_stats FORMAT TSV"); show "carol, alice's session_stats" "$(denied "$r" && echo denied || echo "$r rows")"
+r=$(as carol "SELECT count() FROM mem.alice_meta FORMAT TSV");          show "carol, alice's meta"          "$(denied "$r" && echo denied || echo "$r rows")"
+r=$(as carol "SELECT count() FROM mem.bob_messages FORMAT TSV");        show "carol, bob's messages (never shared)" "$(denied "$r" && echo denied || echo "$r rows")"
+
+echo
+echo "== 5. alice withdraws both shares"
+mh share bob --revoke --yes
+mh share carol --revoke --yes
+r=$(as bob "SELECT count() FROM mem.alice_messages FORMAT TSV");   show "bob, alice's messages"   "$(denied "$r" && echo denied || echo "$r rows")"
+r=$(as carol "SELECT count() FROM mem.alice_messages FORMAT TSV"); show "carol, alice's messages" "$(denied "$r" && echo denied || echo "$r rows")"
+unset MEMHOUSE_HOME

package/examples/04-self-hosted-team/.env.example

@@ -0,0 +1,22 @@
+# Copy to .env beside compose.yml and chmod 600 it: it holds the admin password.
+#   cp .env.example .env && chmod 600 .env
+
+# The name members reach the house at. DNS must point it at this machine.
+MEMHOUSE_DOMAIN=memhouse.example.com
+# An e-mail address gets a Let's Encrypt certificate (ports 80 and 443 must be reachable
+# from the internet). `internal` uses Caddy's own CA instead — for testing, or a private
+# network whose machines trust that CA.
+MEMHOUSE_TLS=you@example.com
+
+# The server's administrator. Invites members; nothing ships as it.
+MEMHOUSE_ADMIN_USER=admin
+# Generate one:  openssl rand -base64 24
+MEMHOUSE_ADMIN_PASSWORD=
+
+# Nightly backup, UTC, and how many to keep.
+BACKUP_AT=03:17
+BACKUP_KEEP=14
+
+# Pinned versions. Read README.md "Upgrading ClickHouse" before changing CLICKHOUSE_TAG.
+CLICKHOUSE_TAG=26.7.1.1315
+CADDY_TAG=2.10

package/examples/04-self-hosted-team/README.md

@@ -0,0 +1,187 @@
+# 04 — a self-hosted house for a team
+
+The full deployment: ClickHouse on a server you run, behind TLS, backed up every night,
+with members shipping from their own laptops. One compose file holds all of it.
+
+```
+ member laptops                         your server (docker compose)
+ ─────────────                          ─────────────────────────────────────────────
+ memhouse shipper ──https:443──▶ caddy ──http──▶ clickhouse ◀── backup (nightly)
+ /mem skills, dashboard            (TLS)         (not published)     │
+                                                    │ data volume    ▼ backups volume
+```
+
+| Service | Image | Role |
+|---|---|---|
+| `clickhouse` | `clickhouse/clickhouse-server:26.7.1.1315` | the house. No published port; reachable only through Caddy. |
+| `caddy` | `caddy:2.10` | TLS on 443: a Let's Encrypt certificate for your domain, or Caddy's own CA. Port 80 answers the ACME challenge and redirects. |
+| `backup` | the ClickHouse image | at `BACKUP_AT` (UTC) writes the house **and its accounts** to the `backups` volume; keeps the newest `BACKUP_KEEP` (14). |
+
+ClickHouse is configured inline (`configs:` in [compose.yml](compose.yml)): the `backups`
+disk, and `users_without_row_policies_can_read_rows` set explicitly to `true`, which
+memhouse's scoped shares depend on (`memhouse share --only` measures it and refuses when it
+is off). The image creates your admin account at first start and removes the passwordless
+`default` user.
+
+## Needs
+
+- A Linux server with Docker and Compose v2.23.1 or newer (`docker compose version`)
+- A DNS name pointing at it, with ports 80 and 443 reachable from the internet for a Let's
+  Encrypt certificate. On a private network, use `MEMHOUSE_TLS=internal` instead (see
+  [TLS](#tls)).
+- On each member's machine: Node.js 24 and `npm install -g memhouse`
+
+## Set up
+
+```bash
+cp .env.example .env && chmod 600 .env
+$EDITOR .env          # MEMHOUSE_DOMAIN, MEMHOUSE_TLS, MEMHOUSE_ADMIN_PASSWORD (openssl rand -base64 24)
+docker compose up -d
+./smoke.sh            # optional: proves the stack end to end, then cleans up after itself
+```
+
+`.env` holds the admin password; it is git-ignored and should stay mode 600. Keep a copy
+of the password in your secret store: you need it to invite people and to restore.
+
+### TLS
+
+- **Public server** — `MEMHOUSE_TLS=you@example.com`. Caddy gets and renews a Let's Encrypt
+  certificate for `MEMHOUSE_DOMAIN`. Members need nothing extra.
+- **Private network** — `MEMHOUSE_TLS=internal`. Caddy signs with its own CA. Every client
+  must trust it: copy it out once and point Node at it on each member machine.
+
+  ```bash
+  docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./memhouse-ca.crt
+  # on each member machine, in the shell profile or the service environment:
+  export NODE_EXTRA_CA_CERTS=/path/to/memhouse-ca.crt
+  ```
+
+## Invite members
+
+From any machine with memhouse, with the admin password lent for one command:
+
+```bash
+with-secret MEMHOUSE_ADMIN_PASSWORD=keychain:memhouse-admin -- \
+  memhouse invite alice --url https://memhouse.example.com --admin-user admin
+```
+
+That creates the user `alice`, grants her `mem.alice_*` and nothing else, and writes
+`invite-alice.env`. **The file is a password**: hand it over through a password manager or
+`croc`, not chat. [03](../03-team-house/) walks through invites and sharing in detail.
+
+## Members: install and keep shipping
+
+On alice's laptop:
+
+```bash
+npm install -g memhouse
+memhouse install --env invite-alice.env    # offers to rotate the password, then deletes the file
+memhouse service install                   # ship at login: systemd user unit or launchd agent
+memhouse plugins install claude            # /mem:recall and the other agent skills
+```
+
+`memhouse service status` shows the unit; `memhouse status` shows freshness and every
+machine writing to her rooms. Without a service, `memhouse start` runs the shipper and the
+dashboard as background processes until logout.
+
+## Smoke test
+
+`./smoke.sh` brings the stack up with `.env`, then, through the proxy only: checks the
+certificate, that the `default` user is gone, invites a member `smoke`, installs it from
+the invite file, ships two made-up sessions, reads them back as the member, backs up and
+restores the member's messages, and checks the nightly job. At exit it drops `smoke` and
+its rooms (`KEEP=1` keeps them). `SKIP_UP=1` tests a stack that is already running; see
+the top of the script.
+
+From a run with `MEMHOUSE_TLS=internal` on a Linux VM with Docker:
+
+```
+smoke test against https://localhost:18443
+  ok    the proxy answers over TLS (certificate verified)
+  ok    the passwordless default user is gone
+  ok    admin reaches ClickHouse 26.7.1.1315
+  ok    admin invited member 'smoke'
+  ok    the member installed from the invite file, over https
+  ok    shipped: shipped 2 sessions (0 skipped) → 6 msg rows, 2 tool rows in 0.6s
+  ok    the member reads its 6 messages back through the proxy
+  ok    the member cannot create tables outside mem.smoke_*
+  ok    BACKUP to the backups disk
+  ok    RESTORE from it
+  ok    the restored copy holds the same 6 rows
+  ok    the backup service has written a nightly backup since the server started
+
+12 passed, 0 failed
+```
+
+## Backups and restore
+
+Every night the `backup` service runs
+
+```sql
+BACKUP DATABASE mem, TABLE system.users, TABLE system.roles, TABLE system.row_policies,
+       TABLE system.settings_profiles, TABLE system.quotas
+TO Disk('backups', 'mem-YYYY-MM-DD-HH_MM.zip')
+```
+
+and deletes all but the newest `BACKUP_KEEP`. The accounts are in the same file on
+purpose: users, their password hashes, their grants and the row policies of scoped shares
+live outside the database, and a restored house without them is one nobody can log in to.
+`docker compose logs backup` shows each run.
+
+**Get the backups off the server.** The `backups` volume sits on the same disk as the data;
+copy the files somewhere else on a schedule of your own:
+
+```bash
+# The files belong to ClickHouse inside the volume (mode 640); hand the copies to you.
+docker run --rm -e OWNER="$(id -u):$(id -g)" -v memhouse-team_backups:/b:ro -v "$PWD":/out \
+  alpine sh -c 'cp /b/mem-*.zip /out/ && chown "$OWNER" /out/mem-*.zip'
+```
+
+**Restore** onto a fresh stack (same compose file, same `.env`, empty volumes):
+
+```bash
+docker compose up -d
+docker compose cp mem-2026-10-07-21_17.zip clickhouse:/backups/
+# the server reads backups as the clickhouse user; a copied-in file arrives as root
+docker compose exec clickhouse chown clickhouse:clickhouse /backups/mem-2026-10-07-21_17.zip
+```
+
+then, as the admin:
+
+```sql
+RESTORE DATABASE mem, TABLE system.users, TABLE system.roles, TABLE system.row_policies,
+        TABLE system.settings_profiles, TABLE system.quotas
+FROM Disk('backups', 'mem-2026-10-07-21_17.zip')
+```
+
+Members come back with their own passwords and grants, so their machines keep shipping
+once the DNS name points at the new server. Restoring accounts fails if a user of the same
+name already exists, which is why this is a restore onto a fresh stack. To look inside a
+backup without touching the live house, restore just the data under another name:
+`RESTORE DATABASE mem AS mem_check FROM Disk('backups', '<file>')`, then
+`DROP DATABASE mem_check`.
+
+Tested on ClickHouse 26.7.1.1315: a nightly file copied off the server with the command
+above, a fresh stack (`down -v`, `up`), the copy put back and restored — the data came
+back, and the member logged in with its original password.
+
+## Upgrading ClickHouse
+
+1. Read the ClickHouse changelog between the two versions. memhouse's CI runs against
+   25.11 and 26.7; memhouse adapts its text-index DDL to the server's grammar on its own.
+2. Take a backup now: `BACKUP_ON_START=1 docker compose up -d --force-recreate backup`
+   writes one immediately (check `docker compose logs backup`), and copy it off the server.
+3. Set `CLICKHOUSE_TAG` in `.env` to the new version, then
+   `docker compose pull clickhouse backup && docker compose up -d`.
+4. Check from a member machine: `memhouse doctor`, `memhouse status`. Or run
+   `SKIP_UP=1 ./smoke.sh` with the target variables set.
+
+Do not go back to an older ClickHouse on the same data volume; going back means restoring
+a backup onto the older version.
+
+## Teardown
+
+```bash
+docker compose down        # stops everything, keeps the data, backups and certificates
+docker compose down -v     # ALSO deletes the house, the backups and the certificates
+```

package/examples/04-self-hosted-team/compose.yml

@@ -0,0 +1,158 @@
+# memhouse — a self-hosted team house.
+#
+# Three services, one file:
+#   clickhouse  the house. Not published: reachable only through the proxy.
+#   caddy       TLS in front of ClickHouse's HTTP port. A real certificate from Let's
+#               Encrypt for MEMHOUSE_DOMAIN, or Caddy's own CA (MEMHOUSE_TLS=internal).
+#   backup      the house and its accounts, every night, to their own volume; the
+#               last BACKUP_KEEP kept.
+#
+# Everything the containers need is inline (the `configs:` blocks), so this file is the
+# whole deployment. Settings come from a `.env` file beside it — see .env.example.
+#
+#   cp .env.example .env && chmod 600 .env    # then edit it
+#   docker compose up -d
+#
+# Pinned to the ClickHouse version memhouse's own production house runs. Upgrading is
+# changing CLICKHOUSE_TAG and `docker compose up -d` — see README.md first.
+#
+# Compose interpolates `$` everywhere in this file, config contents included, which is
+# why the shell variables inside the backup script are written `$$`.
+
+name: memhouse-team
+
+services:
+  clickhouse:
+    image: docker.io/clickhouse/clickhouse-server:${CLICKHOUSE_TAG:-26.7.1.1315}
+    restart: unless-stopped
+    environment:
+      # The image creates this account at first start and removes the passwordless
+      # `default` user. It administers the server: it invites members, nothing ships as it.
+      CLICKHOUSE_USER: ${MEMHOUSE_ADMIN_USER:-admin}
+      CLICKHOUSE_PASSWORD: ${MEMHOUSE_ADMIN_PASSWORD:?set MEMHOUSE_ADMIN_PASSWORD in .env}
+      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
+    configs:
+      - source: clickhouse-memhouse
+        target: /etc/clickhouse-server/config.d/memhouse.xml
+    volumes:
+      - data:/var/lib/clickhouse
+      - backups:/backups
+    ulimits:
+      nofile: { soft: 262144, hard: 262144 }
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8123/ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+      start_period: 10s
+
+  caddy:
+    image: docker.io/library/caddy:${CADDY_TAG:-2.10}
+    restart: unless-stopped
+    depends_on:
+      clickhouse: { condition: service_healthy }
+    environment:
+      MEMHOUSE_DOMAIN: ${MEMHOUSE_DOMAIN:?set MEMHOUSE_DOMAIN in .env}
+      MEMHOUSE_TLS: ${MEMHOUSE_TLS:-internal}
+    ports:
+      - "${MEMHOUSE_HTTPS_PORT:-443}:443"
+      # Port 80 answers Let's Encrypt's HTTP challenge and redirects everything else.
+      - "${MEMHOUSE_HTTP_PORT:-80}:80"
+    configs:
+      - source: caddyfile
+        target: /etc/caddy/Caddyfile
+    volumes:
+      - caddy-data:/data
+
+  backup:
+    image: docker.io/clickhouse/clickhouse-server:${CLICKHOUSE_TAG:-26.7.1.1315}
+    restart: unless-stopped
+    depends_on:
+      clickhouse: { condition: service_healthy }
+    entrypoint: ["/bin/bash", "/backup.sh"]
+    # The image declares a VOLUME at /var/lib/clickhouse; this service runs no server, and
+    # without the tmpfs every recreate would leave an anonymous volume behind.
+    tmpfs: [/var/lib/clickhouse]
+    environment:
+      CLICKHOUSE_USER: ${MEMHOUSE_ADMIN_USER:-admin}
+      CLICKHOUSE_PASSWORD: ${MEMHOUSE_ADMIN_PASSWORD:?set MEMHOUSE_ADMIN_PASSWORD in .env}
+      MEMHOUSE_DB: ${MEMHOUSE_DB:-mem}
+      BACKUP_AT: ${BACKUP_AT:-03:17}
+      BACKUP_KEEP: ${BACKUP_KEEP:-14}
+      BACKUP_ON_START: ${BACKUP_ON_START:-0}
+    configs:
+      - source: backup-script
+        target: /backup.sh
+    volumes:
+      - backups:/backups
+
+configs:
+  clickhouse-memhouse:
+    content: |
+      <clickhouse>
+        <!-- memhouse's scoped shares (memhouse share USER with a scope) filter the grantee
+             with row policies. A reader WITHOUT a policy must keep seeing rows, or scoping one
+             person hides the house from everyone else; `memhouse share` measures this and
+             refuses when it is off. Set explicitly so an image default can never move it. -->
+        <access_control_improvements>
+          <users_without_row_policies_can_read_rows>true</users_without_row_policies_can_read_rows>
+        </access_control_improvements>
+        <!-- Where BACKUP ... TO Disk('backups', ...) writes. -->
+        <storage_configuration>
+          <disks>
+            <backups><type>local</type><path>/backups/</path></backups>
+          </disks>
+        </storage_configuration>
+        <backups>
+          <allowed_disk>backups</allowed_disk>
+          <allowed_path>/backups/</allowed_path>
+        </backups>
+      </clickhouse>
+
+  caddyfile:
+    content: |
+      {$$MEMHOUSE_DOMAIN} {
+        # `internal`: Caddy's own CA (testing, or a private network whose clients trust
+        # it). An e-mail address: a Let's Encrypt certificate for MEMHOUSE_DOMAIN.
+        tls {$$MEMHOUSE_TLS}
+        reverse_proxy clickhouse:8123
+      }
+
+  backup-script:
+    content: |
+      #!/bin/bash
+      # Nightly backup at BACKUP_AT (UTC), keeping the newest BACKUP_KEEP. One file holds
+      # the house AND the accounts: users, their grants and the row policies of scoped
+      # shares live outside the database, and a restore without them is a house nobody
+      # can log in to. README.md has the restore.
+      set -uo pipefail
+      ACCESS="TABLE system.users, TABLE system.roles, TABLE system.row_policies, TABLE system.settings_profiles, TABLE system.quotas"
+      run() {
+        if [ "$$(clickhouse-client --host clickhouse --query "EXISTS DATABASE $$MEMHOUSE_DB")" != "1" ]; then
+          echo "$$(date -u +%FT%TZ) no database '$$MEMHOUSE_DB' yet (no member has installed) — nothing to back up"
+          return
+        fi
+        name="$$MEMHOUSE_DB-$$(date -u +%Y-%m-%d-%H_%M).zip"
+        if clickhouse-client --host clickhouse --query \
+             "BACKUP DATABASE $$MEMHOUSE_DB, $$ACCESS TO Disk('backups', '$$name')" >/dev/null; then
+          echo "$$(date -u +%FT%TZ) backup written: $$name"
+        else
+          echo "$$(date -u +%FT%TZ) backup FAILED: $$name" >&2
+        fi
+        ls -1t /backups/"$$MEMHOUSE_DB"-*.zip 2>/dev/null | tail -n +"$$((BACKUP_KEEP + 1))" | while read -r old; do
+          rm -f -- "$$old" && echo "$$(date -u +%FT%TZ) pruned: $$(basename "$$old")"
+        done
+      }
+      [ "$$BACKUP_ON_START" = "1" ] && run
+      while true; do
+        now=$$(date -u +%s)
+        next=$$(date -u -d "today $$BACKUP_AT" +%s)
+        [ "$$next" -le "$$now" ] && next=$$(date -u -d "tomorrow $$BACKUP_AT" +%s)
+        sleep $$((next - now))
+        run
+      done
+
+volumes:
+  data:
+  backups:
+  caddy-data: