Configuration Reference

Environment variables and deployment modes for self-hosted Noirdoc.

Overview

Noirdoc is configured entirely through environment variables. This page covers all supported variables organized by deployment mode and feature area. Variables marked as required must be set for the proxy to start.

Deployment modes

Noirdoc supports two deployment modes, controlled by the MODE variable:

• Standalone (MODE=standalone) — Single-tenant deployment with a static bearer token. No user management, no JWT authentication. Recommended for single-team or single-application deployments.
• Cloud (MODE=cloud) — Multi-tenant deployment with JWT authentication and an admin portal. See Managed Service for the portal guide.

Both modes share the same proxy core — PII detection, pseudonymization, streaming, and file handling work identically regardless of mode.

Core settings (all modes)

Variable	Required	Default	Description
MODE	No	cloud	standalone or cloud
DATABASE_URL	Yes	—	PostgreSQL connection string. Example: postgresql+asyncpg://noirdoc:secret@postgres:5432/noirdoc
REDIS_URL	Yes	—	Redis connection string. Example: redis://redis:6379/0
ENCRYPTION_KEY	Yes	—	Fernet key for encrypting provider API keys at rest.

Generating an encryption key

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Store this key securely. If it is lost, all encrypted provider keys become unrecoverable.

Standalone mode

These variables apply only when MODE=standalone.

Variable	Required	Default	Description
STANDALONE_BEARER_TOKEN	Yes	—	Static bearer token for client authentication
STANDALONE_PROVIDER	Yes	—	LLM provider: openai, anthropic, azure_openai, openrouter
STANDALONE_PROVIDER_KEY	Yes	—	API key for the configured provider
STANDALONE_PROVIDER_BASE_URL	No	Provider default	Custom base URL (Azure, self-hosted models)

In standalone mode:

• There are no user accounts, no JWT, and no portal.
• Clients authenticate via the Authorization: Bearer <STANDALONE_BEARER_TOKEN> header.
• A single provider is configured through environment variables.
• All proxy features (detection, pseudonymization, streaming, file handling) work identically to cloud mode.

Using with the OpenAI SDK

Since Noirdoc is a drop-in proxy compatible with the OpenAI API format, point the base URL at your instance and use your standalone bearer token as the API key:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="your-secret-token",
)

The same approach works in Node.js, curl, LangChain, or any other OpenAI-compatible client.

Token rotation

Update the STANDALONE_BEARER_TOKEN environment variable and restart the proxy. There is no grace period for the old token — once the proxy restarts, only the new token is accepted.

Cloud mode

These variables apply only when MODE=cloud.

Variable	Required	Default	Description
JWT_SECRET	No	Derived from ENCRYPTION_KEY	Secret for JWT tokens. Set explicitly for multi-instance deployments.
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	No	15	Access token lifetime
JWT_REFRESH_TOKEN_EXPIRE_DAYS	No	7	Refresh token lifetime
BOOTSTRAP_ADMIN_EMAIL	No	—	Admin email created on first startup
BOOTSTRAP_ADMIN_PASSWORD	No	—	Admin password. Must be set with email.
CORS_ORIGINS	No	*	Allowed CORS origins. Set to your frontend domain in production.

On first startup, Noirdoc creates an admin user from the bootstrap variables. Use the Portal API to manage tenants and providers afterward.

PII detection

Variable	Required	Default	Description
DETECTION_LANGUAGES	No	de,en	Comma-separated language codes
DETECTION_SCORE_THRESHOLD	No	0.35	Confidence threshold (0-1)

Pseudonym mappings

Variable	Required	Default	Description
DEFAULT_MAPPING_TTL_DAYS	No	30	Days mappings persist. 0 = request-scoped only.

Request forwarding

Variable	Required	Default	Description
FORWARD_TIMEOUT	No	120	Upstream timeout in seconds

Logging

Variable	Required	Default	Description
LOG_LEVEL	No	info	debug, info, warning, error
LOG_FORMAT	No	json	json or text

Example configurations

Minimal standalone

environment:
  - MODE=standalone
  - DATABASE_URL=postgresql+asyncpg://noirdoc:secret@postgres:5432/noirdoc
  - REDIS_URL=redis://redis:6379/0
  - ENCRYPTION_KEY=your-fernet-key
  - STANDALONE_BEARER_TOKEN=my-secret-token
  - STANDALONE_PROVIDER=openai
  - STANDALONE_PROVIDER_KEY=sk-your-openai-key

Cloud mode with bootstrap admin

environment:
  - MODE=cloud
  - DATABASE_URL=postgresql+asyncpg://noirdoc:secret@postgres:5432/noirdoc
  - REDIS_URL=redis://redis:6379/0
  - ENCRYPTION_KEY=your-fernet-key
  - JWT_SECRET=a-separate-jwt-secret
  - BOOTSTRAP_ADMIN_EMAIL=admin@yourcompany.com
  - BOOTSTRAP_ADMIN_PASSWORD=change-this-immediately
  - CORS_ORIGINS=https://portal.yourcompany.com

Security notes

• Never commit secrets to version control. Use Docker secrets, a .env file excluded from git, or a secrets manager.
• ENCRYPTION_KEY is the most critical secret — it protects all stored provider keys. Rotate it only if you re-encrypt all stored keys first.
• Set CORS_ORIGINS to a specific domain in production rather than using the wildcard *.
• Use strong, randomly generated values for bearer tokens and passwords.