# StarPunk configuration template (v2.14.0) # # Copy to .env and fill in your values. DO NOT commit .env. # Every variable here is read by starpunk/config.py. Uncommented lines are # the ones you normally set; commented lines show the built-in default and # only need uncommenting to change it. Real environment variables take # precedence over .env. # ============================================================================= # SITE # ============================================================================= # Public URL of the site (a trailing slash is added if missing) # (default: http://localhost:5000) SITE_URL=http://localhost:5000 # Site name: page titles and feeds (default: StarPunk) SITE_NAME=My StarPunk Site # Author name; must be non-empty but is not currently displayed: pages use # the h-card discovered at ADMIN_ME (default: Unknown) SITE_AUTHOR=Your Name # Feed description (default: A minimal IndieWeb CMS) SITE_DESCRIPTION=My personal IndieWeb site # ============================================================================= # AUTHENTICATION # ============================================================================= # Your identity URL (REQUIRED unless DEV_MODE=true). Used as the author h-card # source and as the "me" of Micropub tokens. It should link to this site's # IndieAuth metadata so Micropub apps can find StarPunk (ADR-064). ADMIN_ME=https://your-website.com # Session secret (REQUIRED: the app refuses to start without it) # Generate with: python3 -c "import secrets; print(secrets.token_hex(32))" SESSION_SECRET=REPLACE_WITH_RANDOM_SECRET # Flask secret key (default: SESSION_SECRET) # FLASK_SECRET_KEY= # Admin session lifetime in days (default: 30) # SESSION_LIFETIME=30 # Admin login via OpenID Connect (all four REQUIRED unless DEV_MODE=true) # Register StarPunk as a confidential client with your provider (e.g. Pocket ID) # using the callback URL: /auth/callback OIDC_ISSUER=https://id.example.com OIDC_CLIENT_ID= OIDC_CLIENT_SECRET= # The provider's subject ("sub") of the one account allowed to log in. # Pocket ID: the user's ID shown in the admin user list. OIDC_ADMIN_SUB= # Name shown on the login button (default: single sign-on) OIDC_PROVIDER_NAME=Pocket ID # Lifetime of the Micropub access tokens StarPunk's IndieAuth server issues, # in days (default: 90) # INDIEAUTH_TOKEN_LIFETIME_DAYS=90 # ============================================================================= # DATA STORAGE (the container image sets /data, /data/notes, /data/starpunk.db) # ============================================================================= # Base data directory: notes (DATA_PATH/notes), media, logs, # threads_token.json (default: ./data) DATA_PATH=./data # Created at startup; note files are always written under DATA_PATH/notes, # so keep this equal to that (default: ./data/notes) NOTES_PATH=./data/notes # SQLite database (default: ./data/starpunk.db) DATABASE_PATH=./data/starpunk.db # ============================================================================= # FLASK / LOGGING # ============================================================================= # development or production (default: production) FLASK_ENV=production # 1 = debug on, 0 = off (default: 0). `flask run --debug` turns it on locally. FLASK_DEBUG=0 # DEBUG, INFO, WARNING, ERROR or CRITICAL (default: INFO) LOG_LEVEL=INFO # Overrides the version shown in the footer and /health (default: the # package version, starpunk.__version__). Normally leave unset. # VERSION= # ============================================================================= # DEVELOPMENT LOGIN (never in production) # ============================================================================= # DEV_MODE=true adds /dev/login, which logs you in as DEV_ADMIN_ME without # OIDC, and makes ADMIN_ME and OIDC_* optional (default: false) # DEV_MODE=false # Identity used by /dev/login (required when DEV_MODE=true) # DEV_ADMIN_ME=http://localhost:5000/ # ============================================================================= # REVERSE PROXY # ============================================================================= # Behind a reverse proxy (Caddy, nginx): take the client address from # X-Forwarded-For. Without it every visitor shares the proxy's address, so one # busy client can rate-limit everyone on /webmention and /websub. # Only enable when the proxy sets X-Forwarded-For itself (Caddy does). # (default: false) TRUSTED_PROXY=false # CSRF tokens on admin forms, logout and the IndieAuth consent (default: true). # Leave on; tests turn it off unless they test it. CSRF_ENABLED=true # ============================================================================= # FEEDS # ============================================================================= # Items per feed (default: 50) # FEED_MAX_ITEMS=50 # Feed cache lifetime in seconds; changes to notes clear it (default: 300) # FEED_CACHE_SECONDS=300 # FEED_CACHE_ENABLED=true # Cached feed variants kept (default: 50) # FEED_CACHE_MAX_SIZE=50 # ============================================================================= # WEBMENTION # ============================================================================= # Webmention endpoint at /webmention, its Link header, and showing responses # (webmentions and backfeed) on notes; sending is not affected (default: true) # WEBMENTION_ENABLED=true # Background worker that verifies received webmentions, sends outgoing ones, # and sends response notifications (v2.14.0) (default: true) # WEBMENTION_WORKER_ENABLED=true # Hosts never sent webmentions, comma-separated, e.g. self-hosted apps that # don't accept them. Links to this site itself are always skipped (v2.18.3) # WEBMENTION_SKIP_HOSTS=git.example.com,photos.example.com # Seconds between queue checks (default: 10) and after an error (default: 60) # WEBMENTION_POLL_INTERVAL=10 # WEBMENTION_ERROR_BACKOFF=60 # Items per worker pass (default: 5) # WEBMENTION_BATCH_SIZE=5 # Show verified mentions without moderation (default: true) # WEBMENTION_AUTO_APPROVE=true # Rate limits on /webmention: requests per window per client IP (default: 60) # and per source domain (default: 10); window in seconds (default: 60) # WEBMENTION_RATE_LIMIT_ENABLED=true # WEBMENTION_RATE_LIMIT_IP=60 # WEBMENTION_RATE_LIMIT_DOMAIN=10 # WEBMENTION_RATE_LIMIT_WINDOW=60 # ============================================================================= # WEBSUB (v2.10.0) # ============================================================================= # Built-in hub at /websub for this site's feeds. Set WEBSUB_HUB_URL to use # another hub instead (StarPunk then pings it on changes). (default: true) WEBSUB_ENABLED=true # WEBSUB_HUB_URL=https://hub.example.com/ # Subscriptions in total, pending included (default: 1000) # WEBSUB_MAX_SUBSCRIPTIONS=1000 # Per callback server (resolved address) (default: 25) # WEBSUB_MAX_PER_HOST=25 # Seconds between hub worker passes (default: 5) # WEBSUB_POLL_INTERVAL=5 # ============================================================================= # CROSSPOSTING / POSSE (optional; a target is enabled when its credentials # are set) # ============================================================================= # GoToSocial or any Mastodon-API server (v2.1.0, ADR-065). Create an app # token with scopes: write:statuses write:media, plus read:search # write:favourites for native likes and boosts (v2.5.0), plus read:statuses # read:accounts (or read) for backfeed (v2.13.0) GOTOSOCIAL_URL= GOTOSOCIAL_ACCESS_TOKEN= # Name shown in the editor and Micropub apps (default: GoToSocial) # GOTOSOCIAL_NAME=GoToSocial # public, unlisted or private (default: public) # GOTOSOCIAL_VISIBILITY=public # Server limits (defaults: 5000 characters, 4 images) # GOTOSOCIAL_MAX_CHARS=5000 # GOTOSOCIAL_MAX_MEDIA=4 # Bluesky (v2.2.0, ADR-066). Use an app password, not your account password. BLUESKY_HANDLE= BLUESKY_APP_PASSWORD= # PDS / entryway (default: https://bsky.social) # BLUESKY_SERVICE=https://bsky.social # BLUESKY_NAME=Bluesky # BLUESKY_MAX_CHARS=300 # Threads (v2.6.0, ADR-069). A long-lived user token with threads_basic, # threads_content_publish and threads_delete (plus threads_read_replies and # threads_manage_insights for backfeed, v2.13.0); StarPunk refreshes it daily and # keeps the current one in DATA_PATH/threads_token.json. # How to get one: docs/design/v2.6.0/2026-10-31-threads-crossposting.md THREADS_ACCESS_TOKEN= # Your Threads username (for the Micropub syndicate-to uid) THREADS_USERNAME= # THREADS_NAME=Threads # THREADS_MAX_CHARS=500 # THREADS_MAX_MEDIA=4 # Seconds between syndication worker passes (default: 10) # SYNDICATION_POLL_INTERVAL=10 # Backfeed (v2.13.0, ADR-073): bring likes, reposts, quotes and replies to the # crossposts back to the note as responses. Needs the read scopes above, and # runs in the syndication worker, so at least one target must be configured. # BACKFEED_ENABLED=false # Stop checking a note's responses after this many days (default: 90) # BACKFEED_MAX_AGE_DAYS=90 # ============================================================================= # NOTIFICATIONS (v2.14.0, ADR-074; optional) # ============================================================================= # Apprise URLs to notify, space- or comma-separated # (https://github.com/caronc/apprise/wiki). Empty: notifications off. # Examples: gotifys://gotify.example.com/APPTOKEN ntfys://my-topic # apprises://apprise.example.com/KEY (an apprise-api server) # NOTIFY_URLS= # What to notify: reply, mention, quote, like, repost, bookmark, problems # (a crosspost that failed for good, a silo refusing backfeed). Names are # case-insensitive; unknown ones are ignored. # NOTIFY_EVENTS=reply,mention,quote,problems # Priority of every message, added to URLs that don't set one: # low, moderate, normal, high, emergency (Gotify also takes 0-10) # NOTIFY_PRIORITY=normal # ============================================================================= # DEBUGGING # ============================================================================= # Keep uploads that fail processing in DATA_PATH/debug for diagnosis # (default: false); cleaned up by age (default: 7 days) and total size # (default: 100 MB) # DEBUG_SAVE_FAILED_UPLOADS=false # DEBUG_FILE_MAX_AGE_DAYS=7 # DEBUG_FILE_MAX_SIZE_MB=100