Skip to content

Documentation deployment and recovery

Target and isolation

The documentation target is https://hrsdk-platform-docs.hr-tools.io/ on SSH alias sophial-sdk. This is a public static site. Its Nginx virtual host has no robot-control proxy routes or authentication requirement. Existing SDK applications on the host keep their own configuration and access policy.

The public site is deployed on this host. See the deployment verification record for observed HTTP/TLS checks and remaining QA limits.

Build validation

Run from hrsdk_platform_docs:

python3 scripts/inventory.py
python3 scripts/ros_reference.py
python3 scripts/cli_reference.py
python3 scripts/api_contracts.py
python3 scripts/ros_callbacks.py
python3 scripts/config_reference.py
python3 scripts/coverage.py
python3 scripts/audit_contracts.py
.venv/bin/mkdocs build --strict
python3 scripts/check_site.py

The source generators inspect sibling repositories without starting robot nodes. The checker validates built local links/anchors and scans common credential formats. It is not a complete secret-detection proof; review public content and ensure only the generated site is uploaded.

One-time host setup

  1. Confirm the DNS A record points to the deployment host; add IPv6 only if serving is verified.
  2. Add a dedicated port-80 Nginx server for the documentation name and ACME webroot. Validate with nginx -t before reload.
  3. Obtain the domain certificate with Certbot webroot mode. Do not replace the existing SDK certificate or site configuration.
  4. Install the dedicated HTTP/HTTPS template from ops/hrsdk-platform-docs.nginx.conf, validate, then reload Nginx.
  5. Install ops/certbot-reload-nginx.sh as an executable docs-scoped renewal deploy hook. Verify renewal with a domain-specific Certbot dry run and check the renewal timer. Keep certificate private keys on the host.

The existing host already has Nginx and Certbot. Setup must inspect its current state before applying changes; the template assumes the standard existing Let's Encrypt TLS include and DH parameter files.

Repeatable content deployment

.venv/bin/python scripts/deploy.py

The script rebuilds strictly, runs the local checker, computes per-file checksums, uploads only generated assets and verifies checksums on the host. Releases live under /var/www/hrsdk-platform-docs/releases/<UTC-time>-<content-hash>. Activation atomically replaces current; it does not reload or restart robot services.

The script keeps the newest three uploaded releases and preserves an active older rollback target. A failed upload is not activated. Inspect and remove incomplete release directories only after confirming they are inactive. Do not delete the entire hosting directory as a cleanup shortcut.

Public verification

After activation verify:

curl --fail --head https://hrsdk-platform-docs.hr-tools.io/
curl --head http://hrsdk-platform-docs.hr-tools.io/
curl --fail https://hrsdk-platform-docs.hr-tools.io/search/search_index.json -o /dev/null

Check representative nested pages, styles/scripts, actual search interaction, mobile layout, a missing path returning HTTP 404, and unauthenticated access. Check the existing SDK site's response remains unchanged. An SSH activation message is not sufficient to declare the public deployment healthy.

Rollback

List retained release IDs, select the intended known-good release and activate it:

ssh sophial-sdk 'ls -1 /var/www/hrsdk-platform-docs/releases'
.venv/bin/python scripts/deploy.py --rollback RELEASE_ID

The rollback path validates the identifier, verifies stored file checksums and atomically switches the symlink. Recheck HTTPS and nested pages afterward. Content rollback does not revert DNS, certificates or Nginx configuration; back up those separately before one-time infrastructure changes.