Configuration

All settings are provided as environment variables. Nested configuration models use __ as the delimiter.

Root (`SECRETARY_`)

Variable	Required	Default	Description
`SECRETARY_SECRET_KEY`	✅	—	Random string (≥ 32 chars) used to sign JWT session tokens. Generate with `openssl rand -hex 32`.
`SECRETARY_API_TOKEN`		`null`	Static bearer token required on `/api/webhook/paperless`. If unset, the webhook is unauthenticated.
`SECRETARY_RULES_DIR`		`./rules.d`	Path to the directory containing YAML rule files.

Variable	Required	Default	Description
`SECRETARY_PAPERLESS__URL`	✅	—	Base URL of your Paperless-ngx instance, e.g. `https://paperless.example.com`.
`SECRETARY_PAPERLESS__TOKEN`	✅	—	Paperless-ngx REST API token.
`SECRETARY_PAPERLESS__SSL_VERIFY`		`true`	Set to `false` to disable TLS certificate verification (self-signed certs).
`SECRETARY_PAPERLESS__DEFAULT_PAGE_SIZE`		`500`	Page size used for list API calls.
`SECRETARY_PAPERLESS__BATCH_CONCURRENCY`		`10`	Maximum number of concurrent Paperless API requests during batch runs.
`SECRETARY_PAPERLESS__NOTE_HEADER`		`Processing Notes`	Markdown header prepended when Secretary appends notes to a document.
`SECRETARY_PAPERLESS__NOTE_ITEM_FORMAT`		`* {note}`	Format string for individual note items. `{note}` is replaced by the note text.

Variable	Default	Description
`SECRETARY_WEBSERVER__HOST`	`0.0.0.0`	Bind host for the uvicorn process.
`SECRETARY_WEBSERVER__PORT`	`7777`	Bind port for the uvicorn process (inside the container).
`SECRETARY_WEBSERVER__BASE_PATH`	`/`	URL base path. Useful when hosting Secretary under a sub-path behind a reverse proxy, e.g. `/secretary/`.
`SECRETARY_WEBSERVER__ACCESS_LOG`	`true`	Enable the uvicorn HTTP access log.
`SECRETARY_WEBSERVER__WS_LOG`	`true`	Enable the websockets library log.
`SECRETARY_WEBSERVER__ADMIN_USERNAME`	`null`	Web UI admin username. Both username and password must be set to enable login.
`SECRETARY_WEBSERVER__ADMIN_PASSWORD`	`null`	Web UI admin password.
`SECRETARY_WEBSERVER__SESSION_MAX_AGE`	`604800`	JWT session cookie lifetime in seconds (default: 7 days).

Variable	Default	Description
`SECRETARY_MQTT__ENABLED`	`false`	Enable the MQTT entrypoint.
`SECRETARY_MQTT__HOST`	`127.0.0.1`	MQTT broker hostname or IP.
`SECRETARY_MQTT__PORT`	`1883`	MQTT broker port.
`SECRETARY_MQTT__USERNAME`	`null`	MQTT broker username.
`SECRETARY_MQTT__PASSWORD`	`null`	MQTT broker password.
`SECRETARY_MQTT__TLS`	`false`	Enable TLS for the MQTT connection.
`SECRETARY_MQTT__RUN_TOPIC`	`secretary/run`	Topic Secretary subscribes to for incoming run-trigger messages.
`SECRETARY_MQTT__RESULT_TOPIC`	`secretary/result`	Topic Secretary publishes execution results to.

Variable	Default	Description
`SECRETARY_DB__SQLITE_PATH`	`./secretary.db`	Path to the SQLite database file used for execution history.
`SECRETARY_DB__PURGE_INTERVAL_HOURS`	`1`	How often (in hours) to run the automatic history purge job.
`SECRETARY_DB__DRY_RUN_RETENTION_HOURS`	`24`	How long (in hours) to retain dry-run execution records.
`SECRETARY_DB__EXECUTION_RETENTION_HOURS`	`336`	How long (in hours) to retain real execution records (default: 14 days).

If you expose Secretary at https://my-server.example.com/secretary/, set:

environment:
  SECRETARY_WEBSERVER__BASE_PATH: "/secretary/"

nginx or Traefik must strip or forward the prefix accordingly.