From 8c91edf137299b666ea4be7a78f094def1b07503 Mon Sep 17 00:00:00 2001
From: Johan Lundberg <lundberg@sunet.se>
Date: Wed, 18 Feb 2026 12:54:43 +0100
Subject: [PATCH] docs: add example config file and update README

---
 README.md               | 37 ++++++++++++++++++++++++++++++++++++-
 porchlight.example.toml | 23 +++++++++++++++++++++++
 2 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 porchlight.example.toml

diff --git a/README.md b/README.md
index 1afad76..78f18cf 100644
--- a/README.md
+++ b/README.md
@@ -82,7 +82,9 @@ uv run porchlight initial-admin admin --group admin --group superusers
 
 ### Configuration
 
-All settings are read from environment variables with the `OIDC_OP_` prefix:
+All settings are read from environment variables with the `OIDC_OP_` prefix.
+Settings can also be provided via a TOML config file (see below). Environment
+variables always take priority over file values.
 
 | Variable | Default | Description |
 |---|---|---|
@@ -93,9 +95,42 @@ All settings are read from environment variables with the `OIDC_OP_` prefix:
 | `OIDC_OP_SIGNING_KEY_PATH` | `data/keys` | OIDC signing key storage |
 | `OIDC_OP_INVITE_TTL` | `86400` | Magic link expiry in seconds |
 | `OIDC_OP_MANAGE_CLIENT_ID` | `manage-app` | Client ID for the management UI |
+| `OIDC_OP_CONFIG_FILE` | `porchlight.toml` | Path to TOML config file |
 
 Database migrations run automatically on startup.
 
+### Configuration file
+
+Copy `porchlight.example.toml` to `porchlight.toml` and edit to suit your
+deployment. The file supports all the same settings as environment variables
+(without the `OIDC_OP_` prefix), plus OIDC client registrations.
+
+```toml
+issuer = "https://auth.example.com"
+session_secret = "your-random-secret"
+
+[clients.my-webapp]
+client_secret = "change-me-to-a-long-random-string"
+redirect_uris = ["https://app.example.com/callback"]
+response_types = ["code"]
+scope = ["openid", "profile", "email"]
+token_endpoint_auth_method = "client_secret_basic"
+```
+
+Each `[clients.<client-id>]` section registers an OIDC Relying Party on
+startup. Only `client_secret` and `redirect_uris` are required; the other
+fields have sensible defaults (`response_types = ["code"]`,
+`scope = ["openid"]`, `token_endpoint_auth_method = "client_secret_basic"`).
+
+To use a config file at a different path:
+
+```bash
+export OIDC_OP_CONFIG_FILE=/etc/porchlight/config.toml
+```
+
+If the config file does not exist, it is silently ignored and all settings
+fall back to environment variables and defaults.
+
 ## Development Setup
 
 ### Prerequisites
diff --git a/porchlight.example.toml b/porchlight.example.toml
new file mode 100644
index 0000000..801155b
--- /dev/null
+++ b/porchlight.example.toml
@@ -0,0 +1,23 @@
+# Porchlight OIDC Provider Configuration
+#
+# Copy this file to porchlight.toml and edit to suit your deployment.
+# Environment variables (OIDC_OP_*) override values set here.
+# To use a different path: export OIDC_OP_CONFIG_FILE=/path/to/config.toml
+
+issuer = "https://auth.example.com"
+
+# debug = false
+# session_secret = "generate-a-random-string-here"
+# sqlite_path = "data/oidc_op.db"
+# signing_key_path = "data/keys"
+# invite_ttl = 86400
+
+# Register OIDC Relying Party clients below.
+# Each [clients.<client-id>] section defines one client.
+
+# [clients.my-webapp]
+# client_secret = "change-me-to-a-long-random-string"
+# redirect_uris = ["https://app.example.com/callback"]
+# response_types = ["code"]
+# scope = ["openid", "profile", "email"]
+# token_endpoint_auth_method = "client_secret_basic"