ThothII/deploy/secrets/README.md

Runtime secrets and private CA

Secret values in this directory are ignored by Git and remain local to the cloned ThothII directory. This self-contained layout is the default installation documented in docs/installazione-docker-4-contesti.md; an enterprise deployment may point the same *_SECRET_FILE variables at an external secret-manager materialization instead.

Compose mounts each file read-only beneath /run/secrets. The core process runs as UID 10001; the mounted files must be readable by that UID. Docker Compose file-backed secrets are normally mounted read-only with mode 0444. This mode is accepted only for runtime paths beneath /run/secrets, where the container mount is read-only and scoped to services that declare the secret. Source files on the host must have no group/other bits (0600 or 0400). Verify with:

docker compose -f compose.yaml -f deploy/compose.production.yaml \
  --profile external run --rm core sh -c 'id && test -r /run/secrets/thoth_ca.pem'

The CA file should contain only the public PEM certificate chain. API-key files should contain one value with no surrounding quotes.

THT_MODEL_API_KEY_SECRET_FILE supplies one generic hosted-model key to the core. The backend reads it afresh for each Pi child and maps it to the selected provider's native environment name; the generic path/value is not placed in settings, health output, argv, or logs. Supported hosted providers include Anthropic, OpenAI, Google/Gemini, DeepSeek, Z.AI, Groq, Mistral, OpenRouter, xAI, and Cerebras. Local Ollama/LM Studio providers require no file. Compound providers such as Bedrock, Azure OpenAI Responses, and Cloudflare Workers AI/Gateway fail closed because they require multiple credential/configuration values. Unknown hosted providers fail closed until an explicit mapping is added.

Rotating the initialized local-vector bootstrap password

Replacing THT_VECTOR_BOOTSTRAP_PASSWORD_SECRET_FILE or changing its contents does not rotate an initialized PostgreSQL cluster. Use the supported workflow against the running local-vector project:

./scripts/vector-rotate-bootstrap-password.sh \
  deploy/secrets/vector_bootstrap_password \
  deploy/secrets/vector_bootstrap_password.next

The command authenticates using the current file, changes only the authenticated bootstrap role, verifies a new login, and only then atomically replaces the current deployment secret file. If old authentication or new-login verification fails, it exits without changing the deployment file; verification failure also attempts to restore the old database password over the still-open authenticated connection. After success, run the printed vector-reconcile/migration/core command.

THT_VECTOR_BOOTSTRAP_USER is authoritative for database initialization, reconciliation, and rotation; non-default bootstrap role names are supported. Bootstrap, migrator, reader, and writer secret files must be non-empty and contain no whitespace (including trailing newlines). Rotation rejects invalid files before contacting PostgreSQL or staging a deployment-file replacement.

Keep the staged new file on the same trusted host, mode 0600, and retain a secure backup until the post-rotation reconciliation and application health checks pass.