# Example configuration for webmentions-ssg. # # This is a Python configuration file (not INI). Change example.com, paths, the # secret key, and SMTP settings before deploying. # # Default location in production: /etc/webmentions-ssg.cfg import logging # --------------------------------------------------------------------------- # Application # --------------------------------------------------------------------------- DEBUG = False BOOTSTRAP_SERVE_LOCAL = True # BOOTSTRAP_BOOTSWATCH_THEME = "Materia" # --------------------------------------------------------------------------- # Security and reverse proxy # --------------------------------------------------------------------------- # Generate a persistent random key, e.g.: # python -c 'import secrets; print(secrets.token_urlsafe(32))' # Never commit your real key or SMTP password to version control. # 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. 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 # 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. PROXY_FIX_TRUSTED_HOPS = 0 # --------------------------------------------------------------------------- # 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 LOG_FORMAT = "[%(asctime)s]:%(levelname)s:%(name)s %(message)s" LOG_FILE_MAX_BYTES = 20_000_000 LOG_FILE_BACKUP_COUNT = 10 # --------------------------------------------------------------------------- # 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. # # 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 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"} # Optional source allowlist mode. By default, every valid public source is # accepted unless its hostname appears in the admin-managed blocklist. # When enabled, a source must match an allowed domain; blocked entries always # override allowed entries. Manage both lists in the authenticated "Source rules" # page. Entries include subdomains; an empty allowlist rejects all sources. SOURCE_ALLOWLIST_ENABLED = False # 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 # Max stale-row requeues before marking the Webmention failed. Manual # reverification or a new submission after the cooldown resets this counter. 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 # Maximum rows allowed per page in the received Webmentions admin list. # Administrators can enter any page size from 1 through this limit. # The initial page size is 25, or this maximum when it is below 25. RECEIVED_MAX_PAGE_SIZE = 100 # 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 # --------------------------------------------------------------------------- # In-memory storage is for development/testing ONLY. Production requires shared # storage, or the application will refuse to start. Install the appropriate # backend extra/uv group (redis, valkey, memcached, or mongodb). The Redis and # Valkey groups also install Huey's Redis client; see README.md. # Examples: # RATELIMIT_STORAGE_URI = "redis://127.0.0.1:6379/1" # RATELIMIT_STORAGE_URI = "memcached://127.0.0.1:11211" # RATELIMIT_STORAGE_URI = "mongodb://127.0.0.1:27017" # RATELIMIT_STORAGE_URI = "valkey://127.0.0.1:6379" RATELIMIT_STORAGE_URI = "memory://" RATELIMIT_HEADERS_ENABLED = True # Limits per client and across all clients for incoming Webmention submissions. ENDPOINT_RATE_LIMIT = "10/minute;100/hour" ENDPOINT_GLOBAL_RATE_LIMIT = "1000/hour" # Minimum seconds between verifications of the same source/target pair. 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 # 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" # --------------------------------------------------------------------------- # Email digest # --------------------------------------------------------------------------- # 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 MAIL_USE_TLS = True MAIL_USE_SSL = False MAIL_USERNAME = "webmentions@example.com" MAIL_PASSWORD = "REPLACE_WITH_SMTP_PASSWORD" MAIL_DEFAULT_SENDER = "webmentions@example.com"