selfhostly/env.example at main · SamsonNegedu/selfhostly · GitHub

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
# =============================================================================
# Selfhostly Configuration
# Copy this file to .env and fill in your values
# =============================================================================

# =============================================================================
# Application Environment
# =============================================================================

# Environment: development, staging, production (default: production)
# Controls debug mode, logging verbosity, and availability of debug endpoints
APP_ENV=production

# Server configuration
# SERVER_ADDRESS=:8080
# DATABASE_PATH=./data/selfhostly.db
# APPS_DIR=./apps

# =============================================================================
# Authentication
# =============================================================================

# RECOMMENDED: Deploy behind Cloudflare Zero Trust and set AUTH_ENABLED=false
# Cloudflare handles authentication at the edge - simpler and more secure!
# See: https://developers.cloudflare.com/cloudflare-one/applications/configure-apps/
AUTH_ENABLED=false

# Alternative: Enable GitHub OAuth with username whitelist
# If you can't use Cloudflare Zero Trust, uncomment and configure below:
# AUTH_ENABLED=true
# JWT_SECRET=your-strong-random-secret-at-least-32-characters-long
# GITHUB_CLIENT_ID=your_github_client_id
# GITHUB_CLIENT_SECRET=your_github_client_secret
# GITHUB_ALLOWED_USERS=your-github-username,other-allowed-username
# NODE_API_ENDPOINT=https://your-domain.com  # REQUIRED for multi-node: This node's reachable URL
# AUTH_SECURE_COOKIE=true

# =============================================================================
# Multi-Node Configuration (optional - for distributed deployments)
# =============================================================================

# Node Identity (auto-generated if not set)
# NODE_ID=auto
# NODE_NAME=primary  # Defaults to hostname if not set

# Primary vs Secondary Node
# Set to false ONLY on secondary nodes
NODE_IS_PRIMARY=true

# Node API Endpoint (for inter-node communication)
# Set this to the reachable URL for this node so other nodes can communicate
# Examples: http://192.168.1.10:8080 or https://node1.example.com
# NODE_API_ENDPOINT=http://192.168.1.10:8080

# -----------------------------------------------------------------------------
# Cluster Registration Token (for auto-registration)
# -----------------------------------------------------------------------------

# REGISTRATION_TOKEN: Shared secret for auto-registering secondary nodes
# - Primary node: Generate with `openssl rand -base64 32` and set in .env
# - Secondary nodes: Copy the SAME token from primary to enable auto-registration
# - If not set on secondary, manual registration through UI is required
# - Auto-generated on primary if not provided (check startup logs)
#
# REGISTRATION_TOKEN=your-secure-registration-token-here
#
# Example workflow:
#   1. Set REGISTRATION_TOKEN on primary and start it
#   2. Copy the same token to secondary nodes
#   3. Start secondary - it auto-registers! ✅

# -----------------------------------------------------------------------------
# API Key Authentication
# -----------------------------------------------------------------------------

# NODE_API_KEY: This node's own API key
# - Used by OTHER nodes to authenticate when calling THIS node
# - Used by THIS node when sending heartbeats to the primary
# - MUST match the API key entered when registering this node on the primary
#
# IMPORTANT: Set this explicitly to avoid generating a new key on each restart
# Generate a secure key: openssl rand -base64 32
# NODE_API_KEY=your-generated-secure-api-key-here
#
# Example Setup:
#   1. Generate key: openssl rand -base64 32  → "abc123xyz..."
#   2. Set NODE_API_KEY=abc123xyz... on secondary node's .env
#   3. Register node on primary UI with the SAME API key: abc123xyz...
#   4. Secondary sends heartbeat with this key for authentication ✅

# For Secondary Nodes ONLY:
# URL of the primary node (leave empty for primary node)
# PRIMARY_NODE_URL=http://192.168.1.10:8080

# NOTE: PRIMARY_NODE_API_KEY is currently unused - reserved for future features
# For now, secondary nodes use their own NODE_API_KEY to authenticate to primary
# PRIMARY_NODE_API_KEY=<reserved-for-future-use>

# NOTE: Secondary nodes sync Cloudflare credentials from primary automatically
# Do NOT set CLOUDFLARE_* variables on secondary nodes

# -----------------------------------------------------------------------------
# API Gateway (optional - for scalable multi-node routing)
# -----------------------------------------------------------------------------
#
# When using the API gateway (cmd/gateway), set the SAME GATEWAY_API_KEY on:
# - The gateway binary (required)
# - Every backend node (primary and secondaries) so they accept gateway-forwarded requests
#
# Gateway env (run gateway with):
#   GATEWAY_API_KEY=your-gateway-secret  # Required; same value on all backends
#   PRIMARY_BACKEND_URL=http://primary:8082  # Primary backend URL for node registry
#   GATEWAY_LISTEN_ADDRESS=:8080
#   GATEWAY_REGISTRY_TTL_SEC=60  # How often to refresh node list (default 60)
#   AUTH_ENABLED=true  # If gateway should validate JWT
#   JWT_SECRET=...     # Same as primary (for JWT validation)
#
# Backend env (primary and secondaries when gateway is in front):
#   GATEWAY_API_KEY=your-gateway-secret  # Must match gateway's GATEWAY_API_KEY

# =============================================================================
# Cloudflare (optional - for tunnel management)
# =============================================================================

# Cloudflare API Token (needs Zone:DNS:Edit and Account:Cloudflare Tunnel:Edit)
# PRIMARY NODE ONLY - Secondary nodes sync this automatically
CLOUDFLARE_API_TOKEN=your_cloudflare_api_token

# Cloudflare Account ID (find in Cloudflare dashboard)
# PRIMARY NODE ONLY - Secondary nodes sync this automatically
CLOUDFLARE_ACCOUNT_ID=your_cloudflare_account_id

# Cloudflare Tunnel Token (for the selfhostly tunnel itself)
TUNNEL_TOKEN=your_tunnel_token