aboutsummaryrefslogtreecommitdiff
path: root/contrib/webmentions-ssg.example.cfg
blob: 8dd347bce05c7fa1b940be3fe19e9681f913fc27 (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
# 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"}

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