ThothII/deploy/secrets

Runtime secrets

The canonical deployment secret is the single local file deploy/secrets/thothii.secrets. Copy the tracked template and protect the copy:

cp deploy/secrets/thothii.secrets.example deploy/secrets/thothii.secrets
chmod 600 deploy/secrets/thothii.secrets

For a normal local installation, tht setup --complete creates the active bundle at deploy/local/secrets/thothii.secrets and creates the two Catalog password files beside it. The generated deploy/local/operator.env contains only absolute paths to those files; never copy secret values into operator.env.

The file uses strict KEY=VALUE lines (comments and blank lines are allowed). The supported installation keys are THT_MODEL_API_KEY, THT_DWH_API_KEY, THT_CA, THT_SSL_CA, THT_OIDC_CLIENT_SECRET, and THT_AUTHENTIK_API_TOKEN. Installation Model Catalog providers may reference exactly one of THT_MODEL_API_KEY, THT_METADATA_API_KEY, ANTHROPIC_API_KEY, AZURE_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, or ZAI_API_KEY through their descriptor apiKeyEnv. An entry for an explicitly configured endpoint that accepts unauthenticated requests may omit apiKeyEnv; hosted/default endpoints must always reference a key. OpenAI-compatible Qwen endpoints that emit reasoning in content can additionally set litellm.disableThinking: true; the adapter sends the server's bounded chat-template flag so the strict JSON result remains parseable. The two authentication keys must be omitted until they have non-empty values in a protected OIDC installation. Other configured values must be non-empty and contain no whitespace. Do not put secrets in the root .env, installation YAML, workspace YAML, URLs, logs, or rendered Compose output.

Session and metadata-generation runtimes read only the provider key named by modelCatalog.providers.<provider>.authentication.apiKeyEnv. They share the declaration and credential reference, not their execution lifecycle. Pi-owned authentication remains available only to session-only built-in providers through authentication.mode: pi_auth.

Workspace database credentials are intentionally not part of this global bundle. Configure each workspace's database binding, password/token, tunnel key and CA in Database Management; the installation stores those values in its encrypted workspace secret store. The workspace Git repository may declare database identity and Evidence, but must never contain these credentials.

Do not add vector or embedding endpoint credentials to the bundle. Active operator manuals use internal Qdrant and Ollama services, so vector/embedding runtime endpoint secrets are not part of the supported installation contract.

Compose mounts the bundle read-only as /run/secrets/thothii.secrets. The host file must be a regular non-symlink file with mode 0600 or 0400; Docker's normal 0444 mode is accepted only for the runtime mount beneath /run/secrets. The core runs as UID 10001. Verify the mount without printing its contents:

docker compose --env-file deploy/env/local.env \
  -f compose.yaml -f deploy/compose.local.yaml \
  run --rm core sh -c 'id && test -r /run/secrets/thothii.secrets'

A private CA PEM chain is not a bundle value: PEM whitespace is rejected by the strict parser. Keep it in the host or secret manager and add a reviewed Compose override that mounts it at /run/secrets/ca-chain.pem and sets THT_SSL_CA (or the adapter-specific setting). The base Compose files intentionally do not create this mount.

Migration from separate secret files

Older installations used THT_*_SECRET_FILE variables and one file per value. Migrate by copying each retained value to its bundle key, validating with the complete base+profile command, and only then deleting the old files. The old variables remain a compatibility path for staged upgrades, but the documented and tested default is an absolute THT_SECRETS_FILE path to the protected bundle.

Hosted providers must use one explicitly named catalog key. Compound providers (Bedrock, Azure OpenAI Responses, Cloudflare Workers AI/Gateway) fail closed until a provider-specific credential adapter is implemented.

User-owned session database secrets

The server-session overlay deliberately does not add session database credentials to the shared bundle. Materialize three distinct Docker secrets from protected host or secret-manager files: session_runtime_password, session_migrator_password, and session_ca.pem. Their host source paths are respectively THT_SESSION_RUNTIME_PASSWORD_SOURCE, THT_SESSION_MIGRATOR_PASSWORD_SOURCE, and THT_SESSION_CA_SOURCE; all must be absolute paths outside the repository. The runtime password is mounted only into core; the migrator password is mounted only into the one-shot session-migrate service. Do not reuse either login for the other role.

session_ca.pem is a PEM file rather than a bundle value because the bundle rejects whitespace. The server workspace receives only its mount path through THT_SESSION_DB_SSLROOTCERT; it uses THT_SESSION_DB_SSLMODE=verify-ca or, normally, verify-full. TLS disable/prefer/require modes are unsupported for session storage.