Environment Variables

None of these need to be set; the defaults work. They matter at deployment time: the port, which sites to watch, and how often to check them.

An environment variable overrides the matching appsettings.json value. Nested keys use a double underscore, so Docs:PageSize becomes Docs__PageSize.

Hosting ​

Behind a reverse proxy ​

Rate limits are counted per reader IP. Behind nginx, Caddy, or a container ingress, every request has the proxy's IP, so all readers share one limit and a single bot can lock everyone out.

List your proxy to fix that. Loopback is trusted already, so a proxy on the same host needs nothing:

Proxy__Trusted__0=10.0.0.0/8
Proxy__Trusted__1=172.18.0.5

Proxy__TrustAny=true skips the list, useful when your ingress has no fixed address. Anyone who can reach the port can then claim any IP, so only use it when nothing but the proxy can reach the container. Warden logs the choice at startup.

Monitoring ​

Targets and check interval are set in content/config.json; see the guide for the monitoring block. The only environment setting is the database location:

{
  "Monitoring": {
    "DatabasePath": "data/warden.db"
  }
}

To move history between hosts: dotnet Warden.dll --export-db backup.db writes a copy of the database (safe while Warden is running), and --import-db backup.db inserts its rows into the current database, skipping rows that already exist. At startup Warden logs the number of monitors, heartbeats, and the oldest date in the database.

Content ​

Docs__BasePath prefixes every internal link. Give a static export the same value with --base-path so the two agree.

Docs__Themes__Name sets a theme per deployment. It takes precedence over theme in config.json, and --theme <name> on the command line takes precedence over both.

Health checks ​

GET /health answers 200 with the current build version, page count, and uptime in seconds:

{ "status": "ok", "buildVersion": 17, "pages": 42, "uptimeSeconds": 3600 }

It answers 503 with "status": "empty" when no content has been built. Point an external uptime monitor at this route; it has no rate limit, so polling every few seconds is fine.

Bot protection ​

Puts every page behind a self-hosted ALTCHA proof-of-work challenge, similar to Cloudflare's "Just a moment..." screen but without fingerprinting. Off by default. /health and /api stay reachable either way.

{
  "Altcha": {
    "Enabled": true
  }
}

Admin panel ​

Off by default. Set the OIDC variables below to enable /admin, where you can toggle and reorder monitors and configure webhook notifications.

Register https://your-site/auth/callback as the redirect URI. Warden asks for the openid scope only, uses PKCE, and stores no tokens.

OIDC_ALLOWED_SUBJECTS requires the sub claim. Your provider's user admin should include this value, Keycloak as the user ID, Authentik as sub.

Behind a reverse proxy, list it under Proxy__Trusted__0 as well. Without it Warden cannot tell the request arrived over https, so the session cookie is sent without the Secure flag.

Session and antiforgery keys are stored in data/keys/, next to the database. Mount data/, or every container recreate logs everyone out.

Logs ​

Warnings and errors go to logs/warden-<date>.log beside the binary, one file per day, 14 days kept. Information messages go to the console only, so the file stays small.

These settings are in the Serilog section of appsettings.json: change path to write to a mounted volume, or lower restrictedToMinimumLevel to log more. Serilog__WriteTo__1__Args__path in the environment works too.

In a container ​

services:
  warden:
    image: warden
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
    volumes:
      - ./content:/app/content
      - ./data:/app/data

Mount data/ too. That's where the SQLite database and the session keys live; without a volume both reset on every container recreate. The container runs as UID 1654, so the folder must be writable by that user: chown -R 1654:1654 data.