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: environment:
HOME: /tmp HOME: /tmp
volumes: volumes:
- /srv/configs/<project>:/app/config:ro # (2)! - /srv/configs/<workspace>/<project>:/app/config:ro # (2)!
- /srv/logs/<dev>/<project>:/app/logs # (3)! - /srv/logs/<workspace>/<project>:/app/logs # (3)!
- yourapp-data:/app/data # (4)! - yourapp-data:/app/data # (4)!
volumes: volumes:
yourapp-data: yourapp-data:
@ -65,10 +65,20 @@ volumes:
## Paths and mounts ## 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 | | What | Where | How |
| --- | --- | --- | | --- | --- | --- |
| Configs | `/srv/configs/<project>/` | bind mount, host-managed, read-only | | Configs | `/srv/configs/<workspace>/<project>/` | bind mount, host-managed, read-only |
| Logs | `/srv/logs/<dev>/<project>/` | bind mount; live + rolled, scraped | | 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 | | Caches, profiles, scratch | named volume | Docker manages ownership |
!!! note "If your service won't start or its logs aren't persisting" !!! 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" !!! warning "Secrets never go in the image"
We do **not** commit secrets (usually, lol). They stay **gitignored**, live on 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 the host at `/srv/configs/<workspace>/<project>/`, and are bind-mounted
runtime. Add them to `.dockerignore` so a `COPY . .` can't sweep them into a **read-only** at runtime. Add them to `.dockerignore` so a `COPY . .` can't
layer. sweep them into a layer.
Rotating a secret = edit the host file and restart. No rebuild. Rotating a secret = edit the host file and restart. No rebuild.
```bash ```bash
vim /srv/configs/<project>/secrets.env # edit on the host vim /srv/configs/<workspace>/<project>/secrets.env # edit on the host
docker compose restart yourapp # pick up the change — no rebuild 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 This is a public site — it documents generic patterns and conventions. Real
infrastructure specifics (hostnames, internal IPs, exact topology, secrets) stay 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" !!! tip "Point your coding agent here"
Want your agent aware of our libraries, standards, and deploy rules before it Want your agent aware of our libraries, standards, and deploy rules before it