Skip to content

Your favorite shift management application!

fix: align client AUTH_ENABLED default with server, restructure env docs (#161)

panteL281af805458a
diff --git a/.env.example b/.env.example
index 7aad1f8..b390c1b 100644
--- a/.env.example
+++ b/.env.example
@@ -1,65 +1,83 @@
# ==============================================================================
# BetterShift Environment Configuration
# ==============================================================================
-# Copy this file to .env and configure according to your needs
-# Some values are pre-filled with defaults, others require your input
+# 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. OAuth providers -- optional social login
+# 5. Custom OIDC provider -- optional enterprise SSO
+# 6. Reverse proxy -- required for correct client IPs behind a proxy
+# 7. Storage -- database location
+# 8. GitHub integration -- version and release check
+# 9. Rate limiting -- all optional, defaults are sensible
# ==============================================================================
-# DATABASE
+# 1. REQUIRED
# ==============================================================================
-DATABASE_URL=file:./data/sqlite.db
+# 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
# ==============================================================================
-# APPLICATION SETTINGS
+# 2. LOCALIZATION
# ==============================================================================
-# Node.js environment (NOT supported in Docker)
-NODE_ENV=production
-HOSTNAME=0.0.0.0
+# 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
-# Internationalization
+# 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
-TZ=Europe/Berlin # Application timezone
# ==============================================================================
-# AUTHENTICATION SYSTEM
+# 3. ACCESS CONTROL
# ==============================================================================
-# Note: Auth is enabled by default for better security
-
-# Core Auth Configuration
-AUTH_ENABLED=true # Set to false to disable authentication
-
-# 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
-BETTER_AUTH_URL=http://localhost:3000 # Your application URL
-# Security
-# BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:3000,https://yourdomain.com # Comma-separated list of allowed origins for CORS
+ALLOW_USER_REGISTRATION=true # Enable/disable new user signups
+ALLOW_GUEST_ACCESS=false # Allow viewing calendars without login
-# Access Control
-ALLOW_USER_REGISTRATION=true # Enable/disable new user signups
-ALLOW_GUEST_ACCESS=false # Allow viewing calendars without login
+# 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 Management (server-side only)
-# SESSION_MAX_AGE=604800 # Session lifetime: 7 days (seconds)
-# SESSION_UPDATE_AGE=86400 # Session refresh interval: 1 day (seconds)
+# Session lifetime and refresh interval, in seconds.
+# SESSION_MAX_AGE=604800 # 7 days
+# SESSION_UPDATE_AGE=86400 # 1 day
# ==============================================================================
-# OAUTH PROVIDERS
+# 4. OAUTH PROVIDERS (optional)
# ==============================================================================
-# Note: CLIENT_IDs are exposed to client for UI detection
+# 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}
@@ -77,9 +95,11 @@ ALLOW_GUEST_ACCESS=false # Allow viewing calendars without login
# ==============================================================================
-# CUSTOM OIDC PROVIDER
+# 5. CUSTOM OIDC PROVIDER (optional)
# ==============================================================================
-# Note: Client IDs are exposed to client for UI detection
+# 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
@@ -92,22 +112,8 @@ ALLOW_GUEST_ACCESS=false # Allow viewing calendars without login
# ==============================================================================
-# GITHUB INTEGRATION
+# 6. REVERSE PROXY
# ==============================================================================
-# Used for version information endpoint
-
-GITHUB_REPO_OWNER=panteLx
-GITHUB_REPO_NAME=BetterShift
-
-# Optional: Increases API rate limit from 60 to 5000 requests/hour
-# GITHUB_TOKEN=
-
-
-# ==============================================================================
-# RATE LIMITING
-# ==============================================================================
-
-# All settings are optional - defaults shown in comments
# 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
@@ -131,6 +137,36 @@ GITHUB_REPO_NAME=BetterShift
# exposed deployment has to say "none".
# TRUSTED_PROXY_HEADER=
+
+# ==============================================================================
+# 7. 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
+
+
+# ==============================================================================
+# 8. 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=
+
+
+# ==============================================================================
+# 9. 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
diff --git a/README.md b/README.md
index 71a78f6..598f184 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,7 @@ docker run -d \
-v ./data:/app/data \
-e BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
-e BETTER_AUTH_URL=http://localhost:3000 \
+ -e TZ=Europe/Berlin \
--name bettershift \
ghcr.io/pantelx/bettershift:latest
```
@@ -59,7 +60,7 @@ git clone https://github.com/pantelx/bettershift.git
cd bettershift
cp .env.example .env
# Edit .env and set BETTER_AUTH_SECRET
-docker-compose up -d
+docker compose up -d
```
### From Source
@@ -91,11 +92,23 @@ npm run dev
### Required
```bash
-AUTH_ENABLED=true
BETTER_AUTH_SECRET= # npx @better-auth/cli secret
-BETTER_AUTH_URL=http://localhost:3000
+BETTER_AUTH_URL=https://shifts.example.com # public URL, no trailing slash
```
+### Recommended
+
+```bash
+TZ=Europe/Berlin # without it the container runs on UTC
+DEFAULT_LOCALE=en # cs, de, en, es, fr, it
+AUTH_ENABLED=true # false serves everything publicly, without accounts
+TRUSTED_PROXY_HEADER= # CF-Connecting-IP behind Cloudflare, X-Real-IP behind Caddy/nginx
+```
+
+Behind a reverse proxy `TRUSTED_PROXY_HEADER` decides which header the real
+client IP is read from. Rate limits and audit-log entries are keyed off it, so
+leaving it wrong lumps every visitor into one bucket.
+
### Optional: OAuth Providers
```bash
diff --git a/lib/public-config.ts b/lib/public-config.ts
index b90ea63..6e7c98c 100644
--- a/lib/public-config.ts
+++ b/lib/public-config.ts
@@ -28,10 +28,13 @@ export function getPublicConfig() {
// =============================================================================
auth: {
/**
- * Whether the authentication system is enabled
- * @default false
+ * Whether the authentication system is enabled.
+ * Must match AUTH_ENABLED in lib/auth/env.ts -- if the browser disagrees
+ * with the server here, the UI drops into single-user mode while the API
+ * keeps rejecting every request.
+ * @default true
*/
- enabled: process.env.AUTH_ENABLED === "true",
+ enabled: process.env.AUTH_ENABLED !== "false",
/**
* Better Auth base URL for callbacks and API endpoints