- 'The whole flow' is now plain prose, not an abstract box.
- Restore the v2 diagram shape (git -> staging via develop-if-gitflow AND
git -> deployment, converging on docker) instead of the linear main-only
one, keeping the simplified 'libs (rethink-public, pip)' wording.
- Spread admonition types for variety across pages: index agent-callout
tip -> example; environments uv.lock note -> info; standards logging
note -> info. (deploy already mixes success/danger/example/warning/tip.)
Verified in-browser: whole-flow reads as text, diagram renders in the v2
shape; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
Collapse the deploy sub-pages back into one deploy.md (tabs, not separate
pages), add a working mermaid flow diagram, and rework the top per feedback.
- Mermaid: enable via superfences fence_div_format (the fence_code_format
<pre><code> wrapper broke mermaid's render — div format fixes it); vendor
mermaid.min.js locally (no CDN dependency for a self-hosted site) + a small
init that renders each block once and survives instant-nav.
- Content tabs Compose / Dockerfile / Secrets hold the three pieces together
on one page (inline comments in the code, no annotation +).
- 'What can run here' tip moved above the flow; section renamed
'Preparing for Deploy' with the 'you don't run deploy commands' point folded
sparsely into the intro (standalone note removed); 'svc never changes'
called out.
- Flow diagram (below the tabs): build group now includes our libraries; git
-> staging shown as develop-if-gitflow (dotted); deployment (no MR-to-main)
-> docker image built + run on the fleet.
- Revert inbound links to deploy.md.
Verified in-browser: diagram renders with all nodes, tabs switch, section
order correct; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
The Deploy page got long and the code annotations rendered inconsistently
(some as (n) numbers, some as clickable +, and a marker on a fully-commented
line made that line vanish). Fix both:
- Deploy is now a HUB (docs/deploy/index.md): the intro + collision rule +
central-deploy note, then card links to three focused sub-pages. Deploy
stays the single global-nav entry; sub-pages are not_in_nav, reached from
the hub cards.
- deploy/compose.md — compose convention, storage tiers, how deploy fills
it in, subprocess/browser knobs, checklist
- deploy/dockerfile.md — services-account image, COPY, layer caching, uv
- deploy/secrets.md — keeping secrets out of the image
- Replace code annotations with INLINE COMMENTS on the compose/Dockerfile
examples: everything visible at once, no + to click, and the commented
MOUNTS_DIR line no longer disappears.
- Update inbound links (index card, standards, workflow, environments) to
deploy/ and deploy/compose.md; nav Deploy -> deploy/index.md with
not_in_nav for the sub-pages.
Verified in-browser: hub cards link correctly, sub-pages render with visible
inline comments (0 annotation markers), left nav shows only Deploy;
mkdocs build --strict clean (validates not_in_nav + all cross-links).
Signed-off-by: disqualifier <dev@disqualifier.me>
Supersedes the prior 'name everything after the repo' guidance, which caused
container-name collisions at fleet scale. The dev's compose now names nothing
repo-specific; the deploy layer injects identity and host paths.
deploy.md:
- replace the 'One name everywhere' danger callout with 'Your compose names
nothing repo-specific' (no container_name, no hardcoded names/paths)
- rewrite the compose example to the standard: svc service key,
restart: unless-stopped (required — host unit is oneshot), host paths via
${LOGS_DIR}/${CONFIG_DIR}/${MOUNTS_DIR} with :-./ local fallbacks, bare
'cache' volume. Keep user: "1337:1337" + HOME=/tmp (the services account
identity — not repo-specific)
- add 'How deploy fills it in' (injected env vars a dev can rely on + the
resulting docker ps names) and 'Onboarding a service' (deploy <host>
<workspace> <git-url> [name], deploy key handled via Gitea API)
- update paths to <name>, subprocess example to svc, checklist to the new
rules; drop docker CLI from secret rotation (host-side edit, we restart)
standards.md:
- add a 'Service compose' section: short convention + Right/Wrong tabs
(the nova before/after), linking to the Deploy guide for the full detail
Kept the services-account (1337) section and uid-agnostic Dockerfile notes.
Verified in-browser; mkdocs build --strict clean (cross-ref anchor resolves).
Signed-off-by: disqualifier <dev@disqualifier.me>
deploy.md:
- fix logs path to /srv/logs/<dev>/<project>
- reframe permissions as a deployer-side heads-up (bind-mount ownership is
handled at deploy time; 'if your bot won't start or logs vanish, flag us')
instead of a dev task / heavy footgun
- git in the image only when the container needs it (host always has git)
- NEW: layer caching (requirements before code copy)
- NEW: subprocess/browser workloads — init:true (tini + PID-1 shell-wrapper
gotcha), shm_size 2gb, mem_limit; with code annotations and a warning
- refresh the compose-needs checklist accordingly
standards.md:
- NEW: licensing — no per-file headers; single top-level LICENSE only when a
repo is for outside use
Verified: mkdocs build --strict clean; new deploy sections rendered.
Signed-off-by: disqualifier <dev@disqualifier.me>
- Pull the rethink lambda logo (assets/img/logo.svg) into docs/assets and
wire it as theme.logo + favicon — matches the Gitea brand mark.
- standards.md: fold six thin sections into three fuller ones (Files and
style / Documentation / Quality and error handling), each illustrated
with python snippets, a flake8 output block, Do/Don't tabbed examples,
a traceback, and a log line. Admonitions for the run-it-locally tip and
the lib-logging note.
- libraries.md: add a collapsible 'using a library' example (pyproject
pin + import/usage python snippet).
Verified in-browser: logo renders in the header, snippets/tabs/traceback/
log blocks render against the dark theme, libraries example expands.
mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
dsql