aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDennis Fink2026-10-25 22:39:48 +0100
committerDennis Fink2026-10-26 21:31:01 +0100
commit2407e015bf8f1f67ed42b5622ae5095aa6477895 (patch)
treef66cef307f848619d79716a5516b30352a9a89a4
parent3202ab81f162bff9525ee02315c627d9c9feaabb (diff)
downloadwebmentions-ssg-2407e015bf8f1f67ed42b5622ae5095aa6477895.tar.gz
webmentions-ssg-2407e015bf8f1f67ed42b5622ae5095aa6477895.zip
docs(core): add example production configuration
Provide a complete sample configuration covering Flask, database, logging, receiver and sender limits, Huey, scanning, and email notifications. Document expected production paths and highlight secrets and deployment settings that must be customized.
Diffstat (limited to '')
-rw-r--r--contrib/webmentions-ssg.example.cfg103
1 files changed, 103 insertions, 0 deletions
diff --git a/contrib/webmentions-ssg.example.cfg b/contrib/webmentions-ssg.example.cfg
new file mode 100644
index 0000000..d92726e
--- /dev/null
+++ b/contrib/webmentions-ssg.example.cfg
@@ -0,0 +1,103 @@
+# 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.
+SECRET_KEY = "REPLACE_WITH_A_LONG_RANDOM_SECRET"
+
+# Only transmit session cookies over HTTPS connections.
+# Recommended for production deployments using HTTPS.
+# Set to False only when developing locally over plain HTTP.
+SESSION_COOKIE_SECURE = True
+
+# Prevent JavaScript from accessing session cookies via document.cookie.
+# Helps protect session cookies from theft through XSS attacks.
+SESSION_COOKIE_HTTPONLY = True
+
+# Restrict session cookies to same-site requests to help mitigate CSRF.
+# "Lax" allows normal navigation from external sites while restricting
+# cookies on most cross-site requests.
+SESSION_COOKIE_SAMESITE = "Lax"
+
+# ---------------------------------------------------------------------------
+# 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"
+LOGFILE_MAX_BYTES = 20_000_000
+LOGFILE_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_HOSTNAMES = {"example.com", "www.example.com"}
+
+# Limits for fetching/verifying incoming sources.
+REQUEST_TIMEOUT = 5.0 # seconds; also used for outgoing requests
+MAX_REDIRECTS = 20 # also used for outgoing requests
+MAX_SOURCE_BYTES = 1_000_000
+
+# ---------------------------------------------------------------------------
+# 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.
+SOURCE_DIRECTORY = "/var/www/example.com/public"
+
+# Needed for pages without absolute canonical URLs.
+SOURCE_BASE_URL = "https://example.com/"
+
+# Huey cron expression: minute hour day-of-month month day-of-week.
+SCANNER_SCHEDULE = "0 * * * *" # every hour
+
+# Do not send Webmentions to your own site. Glob patterns are supported here.
+IGNORED_HOSTNAMES = ("example.com", "*.example.com")
+MAX_TARGET_BYTES = 1_000_000
+
+# ---------------------------------------------------------------------------
+# Background tasks (Huey)
+# ---------------------------------------------------------------------------
+# Use a shared, persistent backend for production app and worker processes.
+# Redis must be running and reachable by both.
+HUEY_URL = "redis://127.0.0.1:6379/0"
+
+# ---------------------------------------------------------------------------
+# Email notifications for newly verified received Webmentions
+# ---------------------------------------------------------------------------
+# Set NOTIFICATION_EMAIL = None to disable notification emails.
+NOTIFICATION_EMAIL = "admin@example.com"
+
+# 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"