aboutsummaryrefslogtreecommitdiff
path: root/contrib/webmentions-ssg.example.cfg
blob: 33f43afb1c02702e15eb305e40df50ec3d777543 (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
# 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

# ---------------------------------------------------------------------------
# Flask / Application
# ---------------------------------------------------------------------------
DEBUG = False
BOOTSTRAP_SERVE_LOCAL = True
# BOOTSTRAP_BOOTSWATCH_THEME = "Materia"

# ---------------------------------------------------------------------------
# Flask / Security
# ---------------------------------------------------------------------------
# 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.
# 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
# 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
# ---------------------------------------------------------------------------
# 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

# 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

# ---------------------------------------------------------------------------
# Receiving Webmentions
# ---------------------------------------------------------------------------
# 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 * * *"

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

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

# ---------------------------------------------------------------------------
# Sending Webmentions from a statically generated site
# ---------------------------------------------------------------------------
# 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.
DIGEST_EMAIL = "admin@example.com"
# Daily notification digest at 08:00 UTC (Huey defaults to UTC).
DIGEST_SCHEDULE = "0 8 * * *"

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