From c335887dd6b3293c0ab87a3f2036103115931eb1 Mon Sep 17 00:00:00 2001 From: disqualifier Date: Wed, 1 Jul 2026 02:22:46 -0400 Subject: [PATCH] deploy: fix vanishing commented mounts line in compose annotations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A '# (6)!' annotation marker on a fully-commented YAML line made Material's annotation JS swallow the whole line into the tooltip — so the commented '# - ${MOUNTS_DIR...}' line disappeared, leaving an orphan marker with no visible code (which is why '(6)' seemed missing). Fix: drop the marker from the commented line, keep it as plain visible YAML ('# optional — see below'), and move its explanation to prose below the annotation list. Renumber cache/volume markers 7->6, 8->7. Verified in-browser: commented mounts line now renders visibly; no orphan marker. build --strict clean. Signed-off-by: disqualifier --- docs/deploy.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/deploy.md b/docs/deploy.md index ffe0699..0d6feaa 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -134,11 +134,11 @@ services: volumes: - ${LOGS_DIR:-./logs}:/app/logs # (4)! - ${CONFIG_DIR:-./config}:/app/config # (5)! - # - ${MOUNTS_DIR:-./mounts}:/app/data # (6)! - - cache:/app/cache # (7)! + # - ${MOUNTS_DIR:-./mounts}:/app/data # optional — see below + - cache:/app/cache # (6)! volumes: - cache: # (8)! + cache: # (7)! ``` 1. The service key is always **`svc`** — never a repo-specific name, never a @@ -151,17 +151,18 @@ volumes: 4. Logs → host (**output**), path **injected** by the deploy layer. The `:-./logs` default lets you `docker compose up` locally with nothing set and still work. 5. Config → host (**input you edit**), likewise injected. -6. **Optional, commented by default.** A host dir for arbitrary read/write data. - The deploy layer injects `MOUNTS_DIR` and auto-creates the dir — but you - **uncomment** the line and pick the container path (`/app/data` here), since - that's app-specific and can't be auto-mounted. -7. Named volume mounted at **`/app/cache`** — ephemeral scratch. The **right-hand +6. Named volume mounted at **`/app/cache`** — ephemeral scratch. The **right-hand path is where your code writes**: `WORKDIR` is `/app`, so if your app writes to `./cache` (or `/app/cache`), that's this mount. Same rule for logs (`/app/logs`) and config (`/app/config`) — match the container path to where your code reads and writes. The volume name is a bare name, auto-namespaced per service at deploy so it can't collide. -8. Declare bare (`cache`, not `myapp_cache`). Deploy auto-prefixes it. +7. Declare bare (`cache`, not `myapp_cache`). Deploy auto-prefixes it. + +The commented **`${MOUNTS_DIR}`** line is the optional third tier — a host dir for +arbitrary read/write data. The deploy layer injects `MOUNTS_DIR` and auto-creates the +dir, but the mount line is **opt-in**: uncomment it and pick the container path +(`/app/data` above) yourself, since that's app-specific and can't be auto-mounted. !!! tip "Three tiers of storage" - **`logs`** (output) and **`config`** (input you edit) — **we handle these**: