99 lines
4.7 KiB
Markdown
99 lines
4.7 KiB
Markdown
# Publishing the public manual
|
|
|
|
This is an internal operator runbook. Publishing documentation must not recreate
|
|
the ThothII application, Gitea, proxy, DWH or other documentation containers.
|
|
|
|
## Three separate states
|
|
|
|
1. `main` contains reviewed source and the public allowlist in `mkdocs.yml`.
|
|
2. Gitea Actions builds and validates the generated `pages` branch. A successful
|
|
Actions run alone does **not** update the live site.
|
|
3. The live [manual](https://git.tylconsulting.it/thothii-docs/) is served by the
|
|
dedicated `thothii-docs` nginx container on the host reached through the existing
|
|
trusted SSH alias `contabo`. Its Compose project/service are `thothii-docs`/`docs`.
|
|
|
|
This procedure is manual. No timer, webhook, credential or automatic deployment
|
|
has been added. Use the operator's existing SSH authorization and known host key;
|
|
never disable host verification to make a publication work.
|
|
|
|
## Build and stage
|
|
|
|
From a clean ThothII `main` checkout already pushed to Gitea:
|
|
|
|
```sh
|
|
git status --short
|
|
git rev-parse HEAD
|
|
./scripts/build-docs.sh
|
|
bash scripts/auth-docs-smoke.sh
|
|
bash scripts/verify-dwh-auth-docs.sh
|
|
bash scripts/test-auth-docs-smoke.sh
|
|
bash scripts/test-verify-dwh-auth-docs.sh
|
|
```
|
|
|
|
The strict build also verifies the public boundary: exactly 20 navigation pages,
|
|
five approved source assets, no internal pages/assets, and matching search entries.
|
|
The locked Windmill theme requires a separate exact allowlist of 25 static assets;
|
|
MkDocs applies `exclude_docs` to those files too. Never replace the list with broad
|
|
directory exceptions. Sources under `docs/` may not shadow theme asset paths.
|
|
The verifier follows stylesheet/script/image references and CSS font references
|
|
from generated pages and fails when a local dependency is absent.
|
|
|
|
Choose a unique release identifier consisting of UTC timestamp and source SHA.
|
|
Record the current symlink and container identity before proceeding:
|
|
|
|
```sh
|
|
ssh -oBatchMode=yes -oStrictHostKeyChecking=yes contabo \
|
|
'readlink /srv/thothii-docs/current; docker inspect --format "{{.Id}} {{.State.Health.Status}}" thothii-docs'
|
|
```
|
|
|
|
On the server, create `/srv/thothii-docs/releases/RELEASE/site` only if RELEASE
|
|
does not exist. Copy the current `nginx.conf` unchanged into the new release.
|
|
Transfer the local built `site/` into that new empty directory with rsync over
|
|
the same verified SSH connection. Do not use `--delete` against `current`, and do
|
|
not edit routing, TLS, network or authentication configuration.
|
|
|
|
## Activate only this site
|
|
|
|
Replace RELEASE below with the validated identifier, not a user-supplied path.
|
|
Keep the previously recorded release for rollback.
|
|
|
|
```sh
|
|
cd /srv/thothii-docs
|
|
test -f releases/RELEASE/site/index.html
|
|
test -f releases/RELEASE/nginx.conf
|
|
docker exec thothii-docs nginx -t
|
|
ln -s releases/RELEASE current.next
|
|
mv -Tf current.next current
|
|
docker compose --project-name thothii-docs -f docker-compose.yml \
|
|
up -d --no-deps --force-recreate docs
|
|
```
|
|
|
|
Check that `current.next` does not already exist before creating it; stop if it
|
|
does, because another publication or recovery may be in progress. Changing the
|
|
symlink alone is insufficient: an existing Docker bind mount still resolves to
|
|
the old release. The service recreation above remounts the new directory. It may
|
|
briefly interrupt this manual only.
|
|
|
|
## Verify, record, or roll back
|
|
|
|
- Wait for `docker inspect` to report this container healthy; verify mounted
|
|
paths and nginx configuration. Stop after a bounded timeout (for example 60 s).
|
|
- Without login/cookies, require HTTP 200 for home, search and both
|
|
`install/standalone-manual-it/` and `install/standalone-manual-en/`.
|
|
- Compare live home and `search/search_index.json` checksums to the build. Search
|
|
must contain only the 20 approved pages, never plans, reports or architecture.
|
|
- Check the actual stylesheet and JavaScript URLs in both installation pages:
|
|
HTTP 200, CSS served as `text/css`, JavaScript with a valid script content type,
|
|
and fonts available. In a browser confirm the stylesheets load and the layout is
|
|
styled. HTML 200 alone is not enough to accept a publication.
|
|
- Require HTTP 404 for retired/internal paths, including `architecture/overview/`,
|
|
`plans/2026-09-08-memory-management/`, and `operations/compose-reference/`.
|
|
- Record source SHA, release ID, previous release and checks in the cleanup/release
|
|
record. Do not call the publication complete solely because `pages` was pushed.
|
|
|
|
If health or public verification fails, point `current` back to the recorded
|
|
previous release using a fresh temporary symlink and the same atomic rename, then
|
|
recreate **only** service `docs` with the same Compose command. Verify health and
|
|
old site availability. Do not delete either release during recovery. Historical
|
|
releases are retained; pruning them requires a separate retention decision.
|