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

rename <dev> path segment to <workspace>, unify /srv paths

Browse Source 
Host paths now follow one shape: /srv/<kind>/<workspace>/<project>/ across
configs, logs, and mounts (mounts added as its own row; configs gains the
workspace segment it was missing).

- deploy.md: compose volumes, paths table, secrets path + rotation snippet
  all use <workspace>; add a yellow (warning) admonition ABOVE the table
  explaining it — individual dev = lowercase username (ricky, xattam),
  shared/official project = workspace (bots, web, apis) — so it stands out
  from the all-blue palette and reads before the table.
- index.md: placeholder example uses <workspace>.

Verified in-browser; mkdocs build --strict clean.

Signed-off-by: disqualifier <dev@disqualifier.me>
This commit is contained in:
disqualifier 2026-06-29 23:50:42 -04:00
parent 5f91d73e1f
commit 6498c5b6d5
2 changed files with 22 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/deploy.md
View File

@ -48,9 +48,9 @@ services:
environment:
HOME: /tmp
volumes:
- /srv/configs/<project>:/app/config:ro # (2)!
- /srv/logs/<dev>/<project>:/app/logs # (3)!
- yourapp-data:/app/data # (4)!
- /srv/configs/<workspace>/<project>:/app/config:ro # (2)!
- /srv/logs/<workspace>/<project>:/app/logs # (3)!
- yourapp-data:/app/data # (4)!
volumes:
yourapp-data:
@ -65,10 +65,20 @@ volumes:
## Paths and mounts
Everything host-side follows one shape: `/srv/<kind>/<workspace>/<project>/`.
!!! warning "What `<workspace>` is"
`<workspace>` is the owning bucket for a project.
- **An individual dev?** It's your **lowercase username** — `ricky`, `xattam`, …
- **A shared / official project?** It's the **workspace** it belongs to —
`bots`, `web`, `apis`, …
| What | Where | How |
| --- | --- | --- |
| Configs | `/srv/configs/<project>/` | bind mount, host-managed, read-only |
| Logs | `/srv/logs/<dev>/<project>/` | bind mount; live + rolled, scraped |
| Configs | `/srv/configs/<workspace>/<project>/` | bind mount, host-managed, read-only |
| Logs | `/srv/logs/<workspace>/<project>/` | bind mount; live + rolled, scraped |
| Mounts (other host-visible data) | `/srv/mounts/<workspace>/<project>/` | bind mount, host-managed |
| Caches, profiles, scratch | named volume | Docker manages ownership |
!!! note "If your service won't start or its logs aren't persisting"
@ -133,13 +143,13 @@ services:
!!! warning "Secrets never go in the image"
We do **not** commit secrets (usually, lol). They stay **gitignored**, live on
the host at `/srv/configs/<project>/`, and are bind-mounted **read-only** at
runtime. Add them to `.dockerignore` so a `COPY . .` can't sweep them into a
layer.
the host at `/srv/configs/<workspace>/<project>/`, and are bind-mounted
**read-only** at runtime. Add them to `.dockerignore` so a `COPY . .` can't
sweep them into a layer.
Rotating a secret = edit the host file and restart. No rebuild.
```bash
vim /srv/configs/<project>/secrets.env # edit on the host
docker compose restart yourapp # pick up the change — no rebuild
vim /srv/configs/<workspace>/<project>/secrets.env # edit on the host
docker compose restart yourapp # pick up the change — no rebuild
```

3
docs/index.md
View File

@ -5,7 +5,8 @@ coding standards, and how to get a project deployed.
This is a public site — it documents generic patterns and conventions. Real
infrastructure specifics (hostnames, internal IPs, exact topology, secrets) stay
out of it; examples use placeholders like `<dev>`, `<project>`, and `/srv/...`.
out of it; examples use placeholders like `<workspace>`, `<project>`, and
`/srv/...`.
!!! tip "Point your coding agent here"
Want your agent aware of our libraries, standards, and deploy rules before it