Documentation generation and delivery
This page describes the implemented private documentation pipeline. The public portfolio has separate reviewed sources; it is not a public mirror of that site.
Generation is separate from deployment
Ansible combines selected observations, explicit metadata and templates to produce documentation. It is run manually, without scheduled commits or automatic publication of generator output. Observed configuration is not used to invent the reasons behind a decision.
Generated pages are updated through their templates and metadata rather than being manually overwritten. Public output follows an allowlist model: only explicitly selected fields should enter a public template.
Implemented delivery path
- Approved committed documentation sources reach the configured Forgejo branch.
- Forgejo Actions assigns a job to the registered Docker-capable runner.
- The Dockerfile installs locked npm dependencies and builds Docusaurus.
- The resulting static files are packaged in an nginx image.
- The job streams the image archive over SSH using a dedicated deployment key.
- A forced-command receiver loads and validates the image revision.
- The receiver starts a candidate on the alternate loopback port and checks HTTP.
- It updates both nginx proxy targets, tests configuration and reloads nginx.
- It compares homepage responses and stops the previous container only after success.
The two backend ports alternate; a port seen in one run is not a permanent architecture constant.
Privileges and controls
| Boundary | Implemented control or limitation |
|---|---|
| Runner | Non-root service account, but Docker engine access remains highly privileged |
| Deployment key | Dedicated key with restrictions and a forced receiver command |
| Receiver input | Limited operations and a full revision identifier |
| SSH trust | Strict host-key verification and non-interactive operation |
| Concurrent deployments | Workflow concurrency control and a receiver lock |
| Candidate | Revision and HTTP checks before switching |
| Existing state | Previous container retained until success; no automatic image cleanup |
The old transfer key and old static directory remain historical paths; they were not silently removed by the migration.
Confirmed execution versus configured behavior
On 20 November 2026, the first confirmed image job reported Job succeeded
and the receiver reported DEPLOY_OK. This demonstrates one completed run.
It does not prove publication of later uncommitted changes or every page.
Recovery logic attempts to restore the previous nginx configuration on a switching or content-comparison failure. A deliberate failure test was not performed, so practical rollback reliability is not claimed.
Known limitations
- HTTP and homepage comparisons are narrower than checking every page and asset.
- The npm lockfile fixes npm dependency versions; base image tags were not pinned to image digests in the documented Dockerfile.
- Runner isolation does not make untrusted Docker-enabled jobs safe.
- This description is not an audit of the whole SSH configuration or backup system.
- Public portfolio automation is future work, not demonstrated by the private workflow.