docs: consolidate historical records and verify public manual publication
Publish documentation / publish (push) Successful in 29s
Publish documentation / publish (push) Successful in 29s
This commit is contained in:
Codex
@@ -0,0 +1,48 @@
|
||||
# Compose reference for maintainers
|
||||
|
||||
This is an internal topology reference, not a second fresh-installation recipe. Operators
|
||||
start with the [Italian](../install/standalone-manual-it.md) or
|
||||
[English](../install/standalone-manual-en.md) manual. It replaces the duplicated four-context
|
||||
Docker guide without changing the runtime.
|
||||
|
||||
The base topology contains frontend, core, catalog-db, qdrant, embedding, embedding-model-init,
|
||||
catalog-migrate and profile-gated workspace-maintenance. Pi runs in core; DWH and generative
|
||||
model endpoints remain installation settings. Reference preprocessing and Memory have distinct
|
||||
lifecycles and collections. See [preprocessing](../contracts/workspace-preprocessing-cli.md).
|
||||
|
||||
## Configuration and migration boundaries
|
||||
|
||||
- Use one physical absolute installation descriptor path, its generated operator environment,
|
||||
Compose project name, base/profile overlays, transport overlays and generated model overlay.
|
||||
Mixing a generic `deploy/env/local.env` invocation with a native `tht` installation creates
|
||||
a different stack; it is not an equivalent lifecycle command.
|
||||
- `THT_INSTALLATION_CONFIG_SOURCE` identifies the protected host descriptor. The read-only
|
||||
backend runtime mount is `/run/thothii-installation/thothii-installation.yaml`, exposed through
|
||||
`THT_INSTALLATION_CONFIG_FILE`; the runtime path is not a host source path.
|
||||
- Catalog runtime/migrator passwords and provider credentials are protected files. A provider's
|
||||
`authentication.apiKeyEnv` names an allowed bundle entry; it is not a raw key. Private CAs
|
||||
are separately mounted PEM files, not bundle values. See the repository's
|
||||
`deploy/secrets/README.md` and the [model catalog guide](../general/pi-configuration.md).
|
||||
- Generate projections after descriptor edits. Do not edit generated model/auth/frontend files.
|
||||
Apply the installation's normal restart process when authored configuration changes.
|
||||
- Explicitly start catalog-db and run catalog-migrate before application rollout on a fresh
|
||||
database or after an approved schema update. That service runs Catalog and Memory migrations;
|
||||
neither normal backend startup nor `tht start` implicitly performs them.
|
||||
- Server deployments retain their reviewed session/auth/network/storage overlays. A writable
|
||||
server Pi-state parent must be initialized with the regular targets expected by the read-only
|
||||
nested mounts; use `scripts/prepare-server-pi-state.sh` with the installation's verified UID/GID.
|
||||
|
||||
## Deployment-specific authority
|
||||
|
||||
For the prepared generic server environment, the base/profile/session override
|
||||
combination is `-f compose.yaml -f deploy/compose.server.yaml
|
||||
-f deploy/compose.session-server.yaml.example`, with `--env-file` supplied before
|
||||
the overrides. Add the reviewed transport/generated overlays for that installation;
|
||||
this fragment alone is not a complete startup command.
|
||||
|
||||
The current [server handoff](server-codex-handoff.md) and
|
||||
[legacy upgrade runbook](server-upgrade-gitea-workspace-v2.md) retain maintenance, backup and
|
||||
rollback gates. Embedded/upstream identity is not standalone OIDC. Local/standalone setup
|
||||
does not authorize replacing a running server stack, resetting volumes, or copying another
|
||||
machine's descriptor. `scripts/run-stack.sh` remains a low-level path for an explicitly
|
||||
prepared generic environment, not the public manual's default startup command.
|
||||
@@ -0,0 +1,90 @@
|
||||
# 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.
|
||||
Theme-generated assets are separate from those five source assets.
|
||||
|
||||
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.
|
||||
- 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.
|
||||
@@ -722,6 +722,6 @@ la nuova installazione è ferma ma ispezionabile.
|
||||
- [OIDC generico](../install/authentication-oidc.md)
|
||||
- [Operazioni workspace](workspaces.md)
|
||||
- [Configurazione dei modelli Pi](../general/pi-configuration.md)
|
||||
- [Contesti Docker](../installazione-docker-4-contesti.md)
|
||||
- [Contesti Docker](compose-reference.md)
|
||||
- [Database Management](database-management.md)
|
||||
- [Analisi locale della sensibilità](sensitivity-analysis.md)
|
||||
|
||||
Reference in New Issue
Block a user