rethink-public/handbook
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

deploy: fix vanishing commented mounts line in compose annotations

Browse Source 
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 <dev@disqualifier.me>
This commit is contained in:
dsql
2026-07-01 02:22:46 -04:00
parent fe707d5f24
commit c335887dd6
1 changed files with 10 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deploy.md
+10 -9
View File
@@ -134,11 +134,11 @@ services:
volumes: volumes:
- ${LOGS_DIR:-./logs}:/app/logs # (4)! - ${LOGS_DIR:-./logs}:/app/logs # (4)!
- ${CONFIG_DIR:-./config}:/app/config # (5)! - ${CONFIG_DIR:-./config}:/app/config # (5)!
# - ${MOUNTS_DIR:-./mounts}:/app/data # (6)! # - ${MOUNTS_DIR:-./mounts}:/app/data # optional — see below
- cache:/app/cache # (7)! - cache:/app/cache # (6)!
volumes: volumes:
cache: # (8)! cache: # (7)!
``` ```
1. The service key is always **`svc`** — never a repo-specific name, never a 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` 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. default lets you `docker compose up` locally with nothing set and still work.
5. Config → host (**input you edit**), likewise injected. 5. Config → host (**input you edit**), likewise injected.
6. **Optional, commented by default.** A host dir for arbitrary read/write data. 6. Named volume mounted at **`/app/cache`** — ephemeral scratch. The **right-hand
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
path is where your code writes**: `WORKDIR` is `/app`, so if your app writes to 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`) `./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 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 and writes. The volume name is a bare name, auto-namespaced per service at deploy
so it can't collide. 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" !!! tip "Three tiers of storage"
- **`logs`** (output) and **`config`** (input you edit) — **we handle these**: - **`logs`** (output) and **`config`** (input you edit) — **we handle these**: