aboutsummaryrefslogtreecommitdiff
path: root/contrib/webmentions-ssg.example.cfg
diff options
context:
space:
mode:
authorDennis Fink2026-11-16 08:57:31 +0100
committerDennis Fink2026-11-16 08:57:31 +0100
commiteb404d9a1a328278c92753e65100579e7ad98e48 (patch)
treec29918fd1720adf8a11ab88c129f2aea4951c70d /contrib/webmentions-ssg.example.cfg
parent9b00526ab79257b65cedd71595848f09ecf84279 (diff)
downloadwebmentions-ssg-eb404d9a1a328278c92753e65100579e7ad98e48.tar.gz
webmentions-ssg-eb404d9a1a328278c92753e65100579e7ad98e48.zip
refactor(core): organize configuration by subsystem
Group default and example settings into consistent application, security, networking, receiver, scanner, sender, rate-limit, and mail sections. Reorder configuration declarations without changing their values or behavior.
Diffstat (limited to 'contrib/webmentions-ssg.example.cfg')
-rw-r--r--contrib/webmentions-ssg.example.cfg175
1 files changed, 91 insertions, 84 deletions
diff --git a/contrib/webmentions-ssg.example.cfg b/contrib/webmentions-ssg.example.cfg
index 33f43af..8dd347b 100644
--- a/contrib/webmentions-ssg.example.cfg
+++ b/contrib/webmentions-ssg.example.cfg
@@ -8,14 +8,14 @@
import logging
# ---------------------------------------------------------------------------
-# Flask / Application
+# Application
# ---------------------------------------------------------------------------
DEBUG = False
BOOTSTRAP_SERVE_LOCAL = True
# BOOTSTRAP_BOOTSWATCH_THEME = "Materia"
# ---------------------------------------------------------------------------
-# Flask / Security
+# Security and reverse proxy
# ---------------------------------------------------------------------------
# Generate a persistent random key, e.g.:
# python -c 'import secrets; print(secrets.token_urlsafe(32))'
@@ -23,25 +23,26 @@ BOOTSTRAP_SERVE_LOCAL = True
# Production refuses to start without a real, persistent key (>=32 random bytes);
# set the same SECRET_KEY in the web process and every worker.
# Changing this key invalidates all existing signed login sessions.
-# Upgrading to password-bound sessions also requires users to sign in again once.
SECRET_KEY = "REPLACE_WITH_A_LONG_RANDOM_SECRET"
-# When deployed behind a trusted reverse proxy, set this to the EXACT number
-# of trusted hops that set X-Forwarded-For and X-Forwarded-Proto. Use 1 for a
+# When deployed behind a trusted reverse proxy, set this to the EXACT number of
+# trusted hops that set X-Forwarded-For and X-Forwarded-Proto. Use 1 for a
# single nginx instance directly in front of the application; 0 (default)
# ignores forwarded headers. Do not enable this if the backend is reachable
# directly or if the proxy fails to overwrite untrusted forwarded headers.
-# See README.md for an nginx example and multi-proxy caveats.
PROXY_FIX_TRUSTED_HOPS = 0
# ---------------------------------------------------------------------------
-# Database and logging
+# Database
# ---------------------------------------------------------------------------
# SQLite with an absolute file path (four slashes after sqlite:).
# Ensure the service user can write to this directory.
SQLALCHEMY_DATABASE_URI = "sqlite:////var/lib/webmentions-ssg/webmentions-ssg.db"
SQLALCHEMY_TRACK_MODIFICATIONS = False
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
# Ensure the service user can write to the log file / directory.
LOG_FILE = "/var/log/webmentions-ssg.log"
LOG_LEVEL = logging.INFO
@@ -50,34 +51,57 @@ LOG_FILE_MAX_BYTES = 20_000_000
LOG_FILE_BACKUP_COUNT = 10
# ---------------------------------------------------------------------------
-# Receiving Webmentions
+# Background tasks (Huey)
# ---------------------------------------------------------------------------
-# Required: exact hostnames permitted in the 'target' field of an incoming
-# Webmention. Include each hostname you serve; wildcards are not supported.
-ALLOWED_TARGET_HOSTNAMES = {"example.com", "www.example.com"}
-
-# Maximum size of an incoming HTTP request body, including form encoding.
-# This global Flask limit also applies to login and administration routes.
-MAX_CONTENT_LENGTH = 64 * 1024
-# Independent UTF-8 byte limit for each URL submitted to /endpoint.
-# Increase cautiously: a longer URL consumes additional storage and network IO.
-MAX_WEBMENTION_URL_BYTES = 8192
-# Delete failed/deleted received Webmentions this many days after their most
-# recent update; verified, pending, and outgoing records are never purged.
-# Deleted status pages return 404; the same pair can be resubmitted afterward.
-RECEIVED_RETENTION_DAYS = 30
-# Daily at 03:00 UTC (Huey's default timezone).
-RECEIVED_RETENTION_SCHEDULE = "0 3 * * *"
+# Use a shared, persistent backend for production app and worker processes.
+# Huey messages and results use a restricted JSON serializer; do not configure
+# a pickle serializer in either process. Keep both on the same app version.
+#
+# SECURITY: Only the web app and trusted worker should be able to write to the
+# broker. Redis should bind to loopback or a private network, with protected
+# mode, firewall rules, authentication/dedicated ACLs and TLS when remote. Do
+# not expose Redis to public networks or untrusted tenants: even without
+# pickle, an attacker who can write jobs can invoke registered tasks. For
+# file/SQLite backends, restrict directory and database permissions to the
+# app/worker account. For Postgres, use a dedicated least-privilege role and
+# private/ACL-restricted network access.
+#
+# Production startup refuses the implicit memory:// fallback, as well as
+# blackhole://, since neither can reliably deliver work to a separate process.
+# File and SQLite backends follow SQLAlchemy's path convention, not RFC 8089:
+# three slashes for relative paths, four for absolute paths.
+# HUEY_URL = "file:///huey-queue" # Relative: ./huey-queue
+# HUEY_URL = "file:////var/lib/webmentions-ssg/huey-queue" # Absolute
+# HUEY_URL = "sqlite:////var/lib/webmentions-ssg/huey.db" # Absolute
+HUEY_URL = "redis://127.0.0.1:6379/0"
+# ---------------------------------------------------------------------------
+# Outbound HTTP requests (shared by receiver and sender)
+# ---------------------------------------------------------------------------
# Defense in depth: restrict the Huey worker service account with outbound
# firewall/network-policy rules that block loopback, RFC1918, link-local, ULA,
# and cloud metadata ranges, including IPv6. The application also pins
# validated DNS IPs, but deployment-level filtering is still necessary.
-# Limits for fetching/verifying incoming sources.
+# Limits for verifying sources and delivering Webmentions.
REQUEST_TIMEOUT_SECONDS = 5.0 # seconds per socket operation (both directions)
REQUEST_TOTAL_TIMEOUT_SECONDS = 30.0 # seconds overall, including DNS, redirects and body
MAX_REDIRECTS = 20 # also used for outgoing requests
+
+# ---------------------------------------------------------------------------
+# Receiver
+# ---------------------------------------------------------------------------
+# Required: exact hostnames permitted in the 'target' field of an incoming
+# Webmention. Include each hostname you serve; wildcards are not supported.
+ALLOWED_TARGET_HOSTNAMES = {"example.com", "www.example.com"}
+
+# Maximum size of an incoming HTTP request body, including form encoding. This
+# global Flask limit also applies to login and administration routes.
+MAX_CONTENT_LENGTH = 64 * 1024
+# Independent UTF-8 byte limit for each URL submitted to /endpoint.
+# Increase cautiously: a longer URL consumes additional storage and network IO.
+MAX_WEBMENTION_URL_BYTES = 8192
+# Maximum response body size for fetching an incoming source.
MAX_RECEIVED_SOURCE_BYTES = 1_000_000
# Requeue stuck verifications and lost queued tasks after 15 minutes.
VERIFICATION_STALE_AFTER_SECONDS = 900
@@ -87,6 +111,41 @@ VERIFICATION_MAX_RECOVERIES = 3
# Huey cron expression: every five minutes (in UTC).
VERIFICATION_RECOVERY_SCHEDULE = "*/5 * * * *"
+# Delete failed/deleted received Webmentions this many days after their most
+# recent update; verified, pending, and outgoing records are never purged.
+# Deleted status pages return 404; the same pair can be resubmitted afterward.
+RECEIVED_RETENTION_DAYS = 30
+# Daily at 03:00 UTC (Huey's default timezone).
+RECEIVED_RETENTION_SCHEDULE = "0 3 * * *"
+
+# ---------------------------------------------------------------------------
+# Scanner
+# ---------------------------------------------------------------------------
+# Folder containing generated pages named index.html. Set to None to disable
+# scanning. Its root-level index.html is not scanned.
+SITE_OUTPUT_DIRECTORY = "/var/www/example.com/public"
+
+# Needed for pages without absolute canonical URLs.
+SITE_BASE_URL = "https://example.com/"
+
+# Huey cron expression: minute hour day-of-month month day-of-week.
+SOURCE_SCAN_SCHEDULE = "0 * * * *" # every hour
+
+# ---------------------------------------------------------------------------
+# Sender
+# ---------------------------------------------------------------------------
+# Do not send Webmentions to your own site. Glob patterns are supported here.
+IGNORED_TARGET_HOSTNAMES = ("example.com", "*.example.com")
+MAX_DISCOVERY_TARGET_BYTES = 1_000_000
+
+# Temporary delivery failures use persisted exponential backoff: 1, 2, 4, 8,
+# then 16 hours between attempts with these defaults. After six total attempts
+# for a revision, the failure becomes terminal. A changed source or explicit
+# manual resend starts a fresh retry budget.
+SEND_MAX_ATTEMPTS = 6
+SEND_RETRY_BASE_SECONDS = 3600
+SEND_RETRY_MAX_SECONDS = 86400
+
# ---------------------------------------------------------------------------
# Rate limiting
# ---------------------------------------------------------------------------
@@ -109,76 +168,24 @@ ENDPOINT_GLOBAL_RATE_LIMIT = "1000/hour"
ENDPOINT_REVERIFY_COOLDOWN_SECONDS = 600
# Limit login POST attempts per client IP, and separately for each submitted
-# username across IPs (case-folded and hashed before being used as a key).
-# Both limits apply to POSTs, even unsuccessful validation attempts. A per-user
+# username across IPs (case-folded and hashed before being used as a key). Both
+# limits apply to POSTs, even unsuccessful validation attempts. A per-user
# bucket can be deliberately exhausted to temporarily deny that account login;
# keep its allowance higher than the per-IP limit and monitor for abuse.
LOGIN_RATE_LIMIT = "5/minute;30/hour"
LOGIN_USERNAME_RATE_LIMIT = "20/minute;100/hour"
# ---------------------------------------------------------------------------
-# Sending Webmentions from a statically generated site
+# Email digest
# ---------------------------------------------------------------------------
-# Folder containing generated pages named index.html. Set to None to disable
-# scanning. Its root-level index.html is not scanned.
-SITE_OUTPUT_DIRECTORY = "/var/www/example.com/public"
-
-# Needed for pages without absolute canonical URLs.
-SITE_BASE_URL = "https://example.com/"
-
-# Huey cron expression: minute hour day-of-month month day-of-week.
-SOURCE_SCAN_SCHEDULE = "0 * * * *" # every hour
-
-# Temporary delivery failures use persisted exponential backoff: 1, 2, 4,
-# 8, then 16 hours between attempts with these defaults. After six total
-# attempts for a revision, the failure becomes terminal. A changed source or
-# explicit manual resend starts a fresh retry budget.
-SEND_MAX_ATTEMPTS = 6
-SEND_RETRY_BASE_SECONDS = 3600
-SEND_RETRY_MAX_SECONDS = 86400
-
-# Do not send Webmentions to your own site. Glob patterns are supported here.
-IGNORED_TARGET_HOSTNAMES = ("example.com", "*.example.com")
-MAX_DISCOVERY_TARGET_BYTES = 1_000_000
-
-# ---------------------------------------------------------------------------
-# Background tasks (Huey)
-# ---------------------------------------------------------------------------
-# Use a shared, persistent backend for production app and worker processes.
-# Huey messages and results use a restricted JSON serializer; do not configure
-# a pickle serializer in either process. Keep both on the same app version.
-#
-# SECURITY: Only the web app and trusted worker should be able to write to the
-# broker. Redis should bind to loopback or a private network, with protected
-# mode, firewall rules, authentication/dedicated ACLs and TLS when remote.
-# Do not expose Redis to public networks or untrusted tenants: even without
-# pickle, an attacker who can write jobs can invoke registered tasks.
-# For file/SQLite backends, restrict directory and database permissions to
-# the app/worker account. For Postgres, use a dedicated least-privilege role
-# and private/ACL-restricted network access.
-#
-# MIGRATION FROM PICKLE: Drain outstanding jobs on the old trusted deployment
-# first, stop all producers and workers, and clear or migrate old queue,
-# scheduled-task and result data before restarting *both* with JSON.
-# Old pickle payloads cannot be read by the new serializer. Do not deserialize
-# legacy data from any backend that untrusted parties could have modified.
-# Production startup refuses the implicit memory:// fallback, as well as
-# blackhole://, since neither can reliably deliver work to a separate process.
-# File and SQLite backends follow SQLAlchemy's path convention, not RFC 8089:
-# three slashes for relative paths, four for absolute paths.
-# HUEY_URL = "file:///huey-queue" # Relative: ./huey-queue
-# HUEY_URL = "file:////var/lib/webmentions-ssg/huey-queue" # Absolute
-# HUEY_URL = "sqlite:////var/lib/webmentions-ssg/huey.db" # Absolute
-HUEY_URL = "redis://127.0.0.1:6379/0"
-
-# ---------------------------------------------------------------------------
-# Email notifications for newly verified received Webmentions
-# ---------------------------------------------------------------------------
-# Set DIGEST_EMAIL = None to disable notification emails.
+# Set DIGEST_EMAIL = None to disable notification digest emails.
DIGEST_EMAIL = "admin@example.com"
# Daily notification digest at 08:00 UTC (Huey defaults to UTC).
DIGEST_SCHEDULE = "0 8 * * *"
+# ---------------------------------------------------------------------------
+# Mail (SMTP)
+# ---------------------------------------------------------------------------
# Example SMTP-over-STARTTLS setup; adapt to your mail provider.
MAIL_SERVER = "smtp.example.com"
MAIL_PORT = 587