56 lines
3.2 KiB
Markdown
56 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
./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.
|