aboutsummaryrefslogtreecommitdiff
path: root/contrib/webmentions-ssg.example.cfg
blob: 3f3703ef614edf27e017ad0e960862c6fd43dd01 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
# 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

# Optional SQLite-only tuning. Unspecified keys use the built-in defaults;
# setting a value to None leaves that SQLite PRAGMA unchanged. These settings
# apply to SQLAlchemy connections (including binds), not the separate Huey queue.
# They do not affect PostgreSQL or other SQLAlchemy database backends.
#
# Built-in defaults: foreign_keys=True, journal_mode="WAL", busy_timeout=5000
# (milliseconds), trusted_schema=False. The remaining settings are None.
#
# WAL requires a file-backed database on a local filesystem. SQLite also needs
# directory write access for the -wal and -shm sidecar files. In-memory SQLite
# ignores journal_mode, wal_autocheckpoint, and journal_size_limit here.
#
# SQLITE_PRAGMAS = {
#     "busy_timeout": 10000,           # milliseconds waiting for a write lock
#     "synchronous": "NORMAL",         # faster WAL commits; reduced crash durability
#     "cache_size": -8192,             # approx. 8 MiB per connection (negative = KiB)
#     "wal_autocheckpoint": 1000,      # pages; SQLite's built-in default
#     "journal_size_limit": 67108864,  # bytes of retained journal/WAL storage
#     "journal_mode": "WAL",           # or "DELETE", "TRUNCATE", "PERSIST"
#     "foreign_keys": True,            # enforce foreign key constraints
#     "trusted_schema": False,         # disable untrusted schema functions
# }
# You may also set one key through the environment, for example:
# WEBMENTIONS_SSG_SQLITE_PRAGMAS__CACHE_SIZE=-8192
# (environment values are parsed as JSON; lower/upper-case keys are accepted).
# Only known PRAGMAs and correctly typed values are accepted at startup.
# "synchronous" also accepts "FULL", "EXTRA" or "OFF" (unsafe); None leaves
# SQLite's choice alone. Optimizer PRAGMA optimize is NOT run at connect time.

# ---------------------------------------------------------------------------
# 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 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 "Moderation"
# page. Entries include subdomains; an empty allowlist rejects all sources.
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 * * *"
# Required when DIGEST_EMAIL is set: the public hostname of the Webmentions SSG
# *admin interface* (not your static site's SITE_BASE_URL). Flask's url_for
# builds the digest's absolute dashboard and details links outside a request.
SERVER_NAME = "webmentions.example.com"
PREFERRED_URL_SCHEME = "https"
# APPLICATION_ROOT = "/manage"  # If the admin is hosted under a path prefix.

# ---------------------------------------------------------------------------
# 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"