Skip to content

VPS deployment

The production host serves several projects. Treat each path as a separate boundary.

Public path map

Path Owner Exposure
/ Project list Static HTML
/themis/ Themis workspace Nginx proxy to the Themis container
/themis/docs/ Themis documentation Static MkDocs HTML
/analytics-agent/ Themis-only agent demo Nginx proxy to the isolated public agent
/apollo/ Apollo Existing Apollo route; do not modify from Themis deployment
/datahub-ui/ Shared DataHub UI Existing shared route

Deployment shape

Build the documentation on the deployment machine or in CI. Upload only the contents of build/docs-site/ to a dedicated directory:

/var/www/azharizz/themis/docs/

Nginx serves that directory with a prefix-specific alias. The /themis/ proxy remains below the longer /themis/docs/ location. This prevents a docs request from reaching the application API.

Safe deployment sequence

  1. Build with mkdocs build --strict.
  2. Create a versioned temporary directory on the VPS.
  3. Copy the static output into the temporary directory.
  4. Validate the file list. It must contain HTML, CSS, JavaScript, and search assets only.
  5. Switch the current symlink or copy the directory atomically.
  6. Install the Nginx configuration from the repository.
  7. Run nginx -t.
  8. Reload Nginx only after the test passes.
  9. Check /themis/docs/, /themis/, /apollo/, /datahub-ui/, and /analytics-agent/.

Do not store documentation backups with a .conf suffix in /etc/nginx/sites-enabled/. Nginx includes every matching file in that directory. Keep backups outside the included directory.

HTTPS

The public site must redirect HTTP to HTTPS. The certificate is managed by Certbot on the VPS. Use the existing certificate configuration. Do not create a second server block for the docs path.

Persistence after restart

Static docs survive a Docker restart because they are stored on the VPS filesystem. The Themis service and the public Analytics Agent use their own persistent Docker volumes. Do not place docs inside a container layer that can be lost during a rebuild.

The release receipt bridge uses a dedicated THEMIS_EVIDENCE_READ_TOKEN and an exact THEMIS_EVIDENCE_RELEASE_IDS allowlist. The public agent uses a separate THEMIS_EVIDENCE_MCP_TOKEN. Jaeger all-in-one uses the named themis-jaeger-data Badger volume with BADGER_EPHEMERAL=false; this keeps bounded trace evidence available after container recreation. Do not publish Jaeger port 16686 or the MCP port 8765 on the host. The Compose stack prepares the named volume with a short-lived, tightly capability-limited initializer and runs Jaeger as UID 10001.

Apollo protection checklist

Before and after a docs deployment:

  • keep the Apollo container and its port unchanged;
  • do not copy Apollo configuration into the Themis docs directory;
  • do not add an Apollo engine to a public Themis config;
  • do not alter /apollo/ locations while adding /themis/docs/;
  • check that /apollo/ still returns its normal page;
  • check that /datahub-ui/ still returns its normal response;
  • check that Nginx has one active azharizz.blog server block for this config.