Skip to content

Your favorite shift management application!

12.7 KB
Raw Blame
# ==============================================================================
# BetterShift Environment Configuration
# ==============================================================================
# Copy this file to .env and adjust it.
#
# Convention used throughout this file:
#   * An UNCOMMENTED line is worth a look on every deployment.
#   * A COMMENTED line shows the built-in default -- uncomment it only to
#     change that default. Leaving it commented is always safe.
#
# Sections:
#   1. Required               -- the app is not production-ready without these
#   2. Localization           -- timezone and language
#   3. Access control         -- who may register, who may look without login
#   4. Security               -- CSP fallback for reverse-proxy script injection
#   5. OAuth providers        -- optional social login
#   6. Custom OIDC provider   -- optional enterprise SSO
#   7. Reverse proxy          -- required for correct client IPs behind a proxy
#   8. Storage                -- database location
#   9. GitHub integration     -- version and release check
#   10. Rate limiting          -- all optional, defaults are sensible
#   11. Local development      -- dev-server settings, ignored in production
#   12. Telemetry              -- opt-in, anonymous usage statistics


# ==============================================================================
# 1. REQUIRED
# ==============================================================================

# Authentication master switch. Enabled unless set to exactly "false".
AUTH_ENABLED=true  # Set to false to run without accounts (everything public)

# REQUIRED if AUTH_ENABLED=true:
# SECURITY: leaving this empty is not a safe default. The server still starts —
# the missing value is only logged as a startup warning — but authentication is
# then misconfigured: with NODE_ENV=production better-auth refuses to run
# without a real secret and every auth request fails, and outside production it
# falls back to a well-known shared default that offers no protection at all.
# Set a real value before going anywhere near production. Changing it later
# invalidates every existing session (all users are logged out).
BETTER_AUTH_SECRET=  # Generate with: npx @better-auth/cli secret

# The public URL users reach this instance at, scheme included and without a
# trailing slash. It is where OAuth callbacks return to, and it is the default
# CSRF origin, so the localhost default below only works for local testing.
BETTER_AUTH_URL=http://localhost:3000


# ==============================================================================
# 2. LOCALIZATION
# ==============================================================================

# Timezone used for shift times. The container has no timezone of its own and
# would otherwise fall back to UTC, which shifts every displayed time.
TZ=Europe/Berlin

# Language of the UI when the browser asks for none in particular.
# An unknown value is not fatal -- it warns and falls back to "en".
DEFAULT_LOCALE=en  # Options: cs, de, en, es, fr, it


# ==============================================================================
# 3. ACCESS CONTROL
# ==============================================================================

ALLOW_USER_REGISTRATION=true  # Enable/disable new user signups
# Guest access (viewing calendars without login) is controlled live from the
# admin panel under System Settings -- there is no env var for it anymore.

# Origins accepted for CSRF-protected requests, comma-separated.
# Defaults to BETTER_AUTH_URL alone, which is correct for most deployments.
# BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:3000,https://yourdomain.com

# Session lifetime and refresh interval, in seconds.
# SESSION_MAX_AGE=604800    # 7 days
# SESSION_UPDATE_AGE=86400  # 1 day


# ==============================================================================
# 4. SECURITY
# ==============================================================================

# script-src carries a per-request nonce plus 'strict-dynamic'. Some reverse
# proxies rewrite the page to inject their own scripts and reconstruct your
# existing inline scripts in the process, which drops their nonce attribute --
# notably Cloudflare's Rocket Loader. The nonce policy then blocks the app's
# own hydration scripts too, and the app fails to load. If that happens and
# you cannot turn Rocket Loader (or whatever is rewriting the page) off, set
# this to true: script-src falls back to 'self' 'unsafe-inline', the same
# policy our other apps run without a nonce.
# CSP_STRICT_DYNAMIC_BYPASS=false


# ==============================================================================
# 5. OAUTH PROVIDERS (optional)
# ==============================================================================
# A provider appears on the login page as soon as its CLIENT_ID is set; the
# matching CLIENT_SECRET is then required or startup validation complains.
# Note: CLIENT_IDs are sent to the browser for UI detection
#       CLIENT_SECRETs remain server-only
# Callback URLs: {BETTER_AUTH_URL}/api/auth/callback/{provider}

# Google OAuth
# GOOGLE_CLIENT_ID=
# GOOGLE_CLIENT_SECRET=

# GitHub OAuth
# GITHUB_CLIENT_ID=
# GITHUB_CLIENT_SECRET=

# Discord OAuth
# DISCORD_CLIENT_ID=
# DISCORD_CLIENT_SECRET=


# ==============================================================================
# 6. CUSTOM OIDC PROVIDER (optional)
# ==============================================================================
# With CUSTOM_OIDC_ENABLED=true, the ISSUER, CLIENT_ID and CLIENT_SECRET below
# all become required.
# Note: Client IDs are sent to the browser for UI detection
#       Client Secrets remain server-only
# Callback URL: {BETTER_AUTH_URL}/api/auth/oauth2/callback/custom-oidc

# CUSTOM_OIDC_ENABLED=false
# CUSTOM_OIDC_NAME=Custom SSO  # Display name on login button
# CUSTOM_OIDC_CLIENT_ID=
# CUSTOM_OIDC_CLIENT_SECRET=
# CUSTOM_OIDC_ISSUER=https://sso.example.com/.well-known/openid-configuration
# CUSTOM_OIDC_SCOPES=openid profile email  # Space-separated list


# ==============================================================================
# 7. REVERSE PROXY
# ==============================================================================

# Which header carries the real client IP. Rate limits and audit-log entries
# are keyed off it, so it must be a header your proxy sets itself and the
# client cannot forge.
#
#   Cloudflare (also when Caddy/nginx sits behind it):  CF-Connecting-IP
#   Caddy / nginx / Traefik on their own:               X-Real-IP
#   No proxy at all, app exposed directly:              none
#   Exactly one reverse proxy, header name unknown:     leave unset
#
# When set to a header name, ONLY that header is read; if it is missing on a
# request, the client counts as unidentified rather than getting a fresh
# identity. "none" trusts nothing and treats every client as unidentified.
#
# When unset, the LAST entry of X-Forwarded-For is used: each proxy appends the
# address it saw, so with a single proxy in front that entry is the real peer
# and a client cannot prepend its way past it. Behind a longer chain it
# resolves to the nearest hop instead of the client, which is unforgeable but
# lumps clients together - name the trusted header in that case. With NO proxy
# in front, the header is whatever the client chose to send, so a directly
# exposed deployment has to say "none".
# TRUSTED_PROXY_HEADER=


# ==============================================================================
# 8. STORAGE
# ==============================================================================

# Path to the SQLite file. Defaults to <cwd>/data/sqlite.db, which is what the
# Docker image expects (WORKDIR /app, volume mounted at /app/data) -- only set
# this to move the database somewhere else.
# DATABASE_URL=file:./data/sqlite.db


# ==============================================================================
# 9. GITHUB INTEGRATION
# ==============================================================================
# Drives the update check on the version endpoint. The defaults point at the
# upstream repository; change them only when running a fork.

# GITHUB_REPO_OWNER=panteLx
# GITHUB_REPO_NAME=BetterShift

# Raises the GitHub API rate limit from 60 to 5000 requests/hour.
# GITHUB_TOKEN=


# ==============================================================================
# 10. RATE LIMITING (all optional)
# ==============================================================================
# Every limit is a request count plus a window in seconds. The values shown are
# the built-in defaults.

# Authentication
# RATE_LIMIT_AUTH_REQUESTS=5 # Per IP
# RATE_LIMIT_AUTH_WINDOW=60  # 1 minute

# User directory search in the calendar-share dialog. Per authenticated user.
# RATE_LIMIT_USER_SEARCH_REQUESTS=30 # Per user
# RATE_LIMIT_USER_SEARCH_WINDOW=60   # 1 minute

# Ban details shown on the login page. Deliberately separate from the auth
# limit above: the login page requests this right after a banned sign-in, so a
# shared bucket would hide the ban reason after the second attempt.
# RATE_LIMIT_BAN_INFO_REQUESTS=10 # Per IP
# RATE_LIMIT_BAN_INFO_WINDOW=60   # 1 minute

# RATE_LIMIT_REGISTER_REQUESTS=3 # Per IP
# RATE_LIMIT_REGISTER_WINDOW=600  # 10 minutes

# RATE_LIMIT_PASSWORD_CHANGE_REQUESTS=3 # Per user
# RATE_LIMIT_PASSWORD_CHANGE_WINDOW=3600  # 1 hour

# Account Management
# RATE_LIMIT_ACCOUNT_DELETE_REQUESTS=1 # Per user
# RATE_LIMIT_ACCOUNT_DELETE_WINDOW=3600  # 1 hour

# RATE_LIMIT_UPLOAD_AVATAR_REQUESTS=5 # Per user
# RATE_LIMIT_UPLOAD_AVATAR_WINDOW=300  # 5 minutes

# Calendar Operations
# RATE_LIMIT_CALENDAR_CREATE_REQUESTS=10 # Per user
# RATE_LIMIT_CALENDAR_CREATE_WINDOW=3600  # 1 hour

# RATE_LIMIT_EXTERNAL_SYNC_REQUESTS=5  # Per calendar
# RATE_LIMIT_EXTERNAL_SYNC_WINDOW=300  # 5 minutes

# Export Features
# RATE_LIMIT_EXPORT_PDF_REQUESTS=10 # Per user
# RATE_LIMIT_EXPORT_PDF_WINDOW=600  # 10 minutes
# RATE_LIMIT_EXPORT_ICS_REQUESTS=20 # Per user
# RATE_LIMIT_EXPORT_ICS_WINDOW=600  # 10 minutes
# RATE_LIMIT_CALENDAR_FEED_REQUESTS=60 # Per feed owner (subscribed calendar apps poll this)
# RATE_LIMIT_CALENDAR_FEED_WINDOW=600  # 10 minutes

# Calendar Access Tokens (Share Links)
# RATE_LIMIT_TOKEN_VALIDATION_REQUESTS=10 # Per IP
# RATE_LIMIT_TOKEN_VALIDATION_WINDOW=60  # 1 minute
# RATE_LIMIT_TOKEN_CREATION_REQUESTS=10 # Per calendar
# RATE_LIMIT_TOKEN_CREATION_WINDOW=3600  # 1 hour

# Permission Bundles (per calendar)
# RATE_LIMIT_BUNDLE_MUTATIONS_REQUESTS=30 # Bundle create/update/delete/clone
# RATE_LIMIT_BUNDLE_MUTATIONS_WINDOW=3600  # 1 hour

# Custom Field Catalog (per calendar)
# RATE_LIMIT_CUSTOM_FIELD_MUTATIONS_REQUESTS=30 # Field create/update/delete/reorder
# RATE_LIMIT_CUSTOM_FIELD_MUTATIONS_WINDOW=3600  # 1 hour

# RATE_LIMIT_ANNOUNCEMENTS_REQUESTS=120 # Public announcement reads
# RATE_LIMIT_ANNOUNCEMENTS_WINDOW=60    # 1 minute
# RATE_LIMIT_ADMIN_ANNOUNCEMENT_MUTATIONS=20 # Announcement create/update/delete
# RATE_LIMIT_ADMIN_ANNOUNCEMENT_MUTATIONS_WINDOW=60 # 1 minute

# Admin Panel (per admin user)
# RATE_LIMIT_ADMIN_USER_MUTATIONS=10 # User ban/unban/delete/edit
# RATE_LIMIT_ADMIN_USER_MUTATIONS_WINDOW=60  # 1 minute
# RATE_LIMIT_ADMIN_PASSWORD_RESET=5 # Password reset for users
# RATE_LIMIT_ADMIN_PASSWORD_RESET_WINDOW=300  # 5 minutes
# RATE_LIMIT_ADMIN_USER_CREATE=5 # Creating new users
# RATE_LIMIT_ADMIN_USER_CREATE_WINDOW=300  # 5 minutes
# RATE_LIMIT_ADMIN_BULK_OPERATIONS=3 # Bulk delete/transfer calendars
# RATE_LIMIT_ADMIN_BULK_OPERATIONS_WINDOW=300  # 5 minutes
# RATE_LIMIT_ADMIN_CALENDAR_MUTATIONS=10 # Calendar delete/transfer/edit
# RATE_LIMIT_ADMIN_CALENDAR_MUTATIONS_WINDOW=60  # 1 minute


# ==============================================================================
# 11. LOCAL DEVELOPMENT (optional, ignored in production)
# ==============================================================================

# Extra hosts allowed to request Next.js dev-only resources (e.g. HMR),
# comma-separated. Needed when the dev server is reached through something
# other than localhost -- a remote/SSH dev session accessed via LAN IP, a
# port-forwarding tunnel, or a device on the network. Next.js logs the
# blocked origin in its warning; put that value here.
# DEV_ALLOWED_ORIGINS=192.168.1.1


# ==============================================================================
# 12. TELEMETRY (opt-in, anonymous)
# ==============================================================================

# Unset: the instance admin decides in the app.
# false: hard off, no dialog, no requests. true: hard on, no dialog.
# Only the literal "true" and "false" are recognised; anything else (1, yes,
# TRUE) fails closed, i.e. behaves like "false" and locks the admin toggle.
# See docs/TELEMETRY.md for every field that is sent.
# TELEMETRY_ENABLED=
# TELEMETRY_ENDPOINT=https://telemetry-bettershift.pantelx.com