Self-Hosting Overview

Architecture, deployment modes, and system requirements.

Commercial license required

Self-hosting Noirdoc requires a commercial license. Contact us to request access to the Docker image and license details.

Why self-host?

Noirdoc Cloud handles everything for you, but some organizations require full control over their data pipeline. Self-hosting lets you run the entire Noirdoc proxy on your own infrastructure — your servers, your network, your rules. Pseudonym mappings and provider API keys never leave your environment.

Architecture

A self-hosted Noirdoc deployment consists of three core services:

  • Proxy — the FastAPI application (Python 3.13+) served by Uvicorn. Handles PII detection, pseudonymization, request forwarding, and response restoration.
  • PostgreSQL — stores tenants, portal configurations, provider settings, and audit data. Requires PostgreSQL 14 or higher.
  • Redis — stores pseudonym mappings for cross-request persistence. Mappings are encrypted at rest using the configured Fernet key.

An optional fourth service, Caddy, can be placed in front of the proxy to provide automatic HTTPS via Let’s Encrypt. This is recommended for production deployments exposed to the internet but not required for internal or development setups.

Client App  -->  [Caddy (optional)]  -->  Noirdoc Proxy  -->  LLM Provider
                                              |       |
                                           Postgres  Redis

Deployment modes

Noirdoc supports two deployment modes, controlled by the MODE environment variable.

Cloud mode (MODE=cloud)

Cloud mode is the full multi-tenant deployment. It includes:

  • JWT-based authentication with access and refresh tokens
  • Multi-tenant isolation — each tenant has its own providers, keys, and mappings
  • Admin portal for managing users, tenants, and provider configurations
  • Bootstrap admin creation via environment variables

Use cloud mode when you need to serve multiple teams or organizations from a single Noirdoc instance, or when you want the full admin portal experience.

Standalone mode (MODE=standalone)

Standalone mode is a simplified single-tenant deployment. It removes all user and tenant management in favor of a single static bearer token. This is the easiest way to self-host Noirdoc for a single team or application.

  • No user accounts, no JWT tokens, no portal
  • Authentication via a static STANDALONE_BEARER_TOKEN
  • A single provider configured through environment variables
  • All other features — PII detection, pseudonymization, streaming, file handling — work identically

See the Configuration Reference for detailed setup instructions.

System requirements

Minimum hardware

  • CPU: 2 cores (4 recommended — the NER model benefits from parallel inference)
  • RAM: 4 GB minimum, 8 GB recommended (the NER model loads into memory on startup)
  • Disk: 10 GB for the Docker image and database storage

Software

  • Docker Engine 24+ and Docker Compose V2
  • Alternatively, Python 3.13+ with pip for bare-metal installs (not recommended for production)

Network

  • Outbound HTTPS access to your LLM provider (e.g., api.openai.com, api.anthropic.com)
  • Inbound access on port 8000 (proxy) or 443 (if using Caddy for HTTPS)

Health check

Every Noirdoc instance exposes a health endpoint at GET /health. Use it for container orchestration, load balancer probes, or monitoring:

curl http://localhost:8000/health
{
  "status": "ok",
  "version": "1.0.0",
  "mode": "standalone"
}

The mode field reflects the active deployment mode. The version field returns the running Noirdoc release.

Next steps