malpercio.dev
WIP! A BB-style forum, on the ATmosphere!
We're still working... we'll be back soon when we have something to show off!
node
typescript
hono
htmx
atproto
1# ============================================================================
2# atBB Production Environment Configuration
3# ============================================================================
4# Copy this file to .env.production and fill in your actual values.
5# NEVER commit .env.production with real secrets to version control!
6#
7# After copying:
8# 1. Generate SESSION_SECRET: openssl rand -hex 32
9# 2. Fill in your AT Protocol credentials (FORUM_DID, PDS_URL, etc.)
10# 3. Set strong passwords for FORUM_PASSWORD and database
11# 4. Update URLs to match your deployment domain
12# 5. Restrict file permissions: chmod 600 .env.production
13#
14# Security note: This file contains sensitive credentials. Protect it like
15# you would protect SSH keys or API tokens.
16# ============================================================================
17
18# ============================================================================
19# Database Configuration
20# ============================================================================
21# PostgreSQL connection string
22# Format: postgresql://username:password@hostname:port/database
23#
24# Production example (managed PostgreSQL):
25# DATABASE_URL=postgresql://atbb_prod:S3cureP@ssw0rd@db.example.com:5432/atbb_prod
26#
27# Docker Compose example (container name as hostname):
28# DATABASE_URL=postgresql://atbb:changeme@postgres:5432/atbb
29#
30# Notes:
31# - Use strong passwords (minimum 16 characters, alphanumeric + symbols)
32# - Enable SSL/TLS in production: ?sslmode=require
33# - Consider connection pooling for high traffic
34DATABASE_URL=postgresql://atbb_user:CHANGE_ME_STRONG_PASSWORD@db.example.com:5432/atbb_production
35
36# ============================================================================
37# AT Protocol Configuration
38# ============================================================================
39# These settings connect your forum to the AT Protocol network (Bluesky/atproto).
40
41# Forum's Decentralized Identifier (DID)
42# This is your forum's unique identity on the AT Protocol network.
43# Get this after creating your forum account on a PDS.
44#
45# Example: did:plc:abcdef1234567890
46# Production: Use your actual forum DID from your PDS
47FORUM_DID=did:plc:CHANGE_ME_YOUR_FORUM_DID
48
49# Personal Data Server URL
50# The PDS where your forum's records are stored.
51# This can be your own PDS instance or a hosted service.
52#
53# Examples:
54# - Self-hosted: https://pds.yourdomain.com
55# - Bluesky PDS: https://bsky.social
56PDS_URL=https://pds.example.com
57
58# Forum Service Account credentials
59# Required for the AppView to write forum-level records (categories, roles, mod actions)
60# to the PDS on behalf of the forum identity.
61#
62# Use the handle and password for the AT Protocol account created for your forum.
63FORUM_HANDLE=forum.example.com
64FORUM_PASSWORD=CHANGE_ME_STRONG_PASSWORD
65
66# ============================================================================
67# Application URLs
68# ============================================================================
69# These URLs determine how services communicate and handle OAuth.
70
71# Public URL where your forum is accessible to users
72# Used for OAuth redirect URIs and client_id generation.
73# MUST be HTTPS in production (HTTP only for local development).
74#
75# Examples:
76# - Production: https://forum.example.com
77# - Staging: https://staging.forum.example.com
78OAUTH_PUBLIC_URL=https://forum.example.com
79
80# Internal URL for web service to reach appview API
81# In single-container deployments: http://localhost:3000
82# In multi-container deployments: http://appview:3000 (Docker service name)
83# In Kubernetes: http://appview-service:3000
84#
85# Notes:
86# - Use container/service names, not external domains
87# - HTTP is fine for internal communication (encrypted at network layer)
88# - Must be reachable from web service container
89APPVIEW_URL=http://localhost:3000
90
91# ============================================================================
92# Session Management
93# ============================================================================
94# Session security is critical for protecting user accounts.
95
96# Secret key for encrypting and signing session cookies
97# CRITICAL: Generate a strong random value, never use the default!
98#
99# Generate with: openssl rand -hex 32
100#
101# Security requirements:
102# - Minimum 32 bytes (64 hex characters)
103# - Use cryptographically secure random generation
104# - Unique per environment (dev, staging, production)
105# - Never commit to version control
106# - Rotate periodically (invalidates all active sessions)
107#
108# Example output from openssl:
109# a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
110SESSION_SECRET=
111
112# ============================================================================
113# Service Ports (Optional)
114# ============================================================================
115# Override default ports if needed for your deployment environment.
116# Most deployments can use the defaults.
117
118# AppView API server port (default: 3000)
119# This is the internal port the appview service listens on.
120# PORT=3000
121# WEB_PORT=3001
122
123# Note: In the Docker container, nginx listens on port 80 and proxies to both services.
124
125# ============================================================================
126# AT Protocol Features (Optional)
127# ============================================================================
128# Advanced AT Protocol configuration.
129
130# Jetstream firehose URL for real-time updates
131# Receives live events from the AT Protocol network to keep your forum
132# synchronized with user posts and profile changes.
133#
134# Default: wss://jetstream2.us-east.bsky.network/subscribe
135#
136# Notes:
137# - Uses WebSocket (wss://) for real-time streaming
138# - Alternative endpoints available for different regions
139# - Required for live post indexing
140# JETSTREAM_URL=wss://jetstream2.us-east.bsky.network/subscribe
141
142# ============================================================================
143# Session Configuration (Optional)
144# ============================================================================
145# Fine-tune session behavior for your deployment.
146
147# Session cookie TTL (Time To Live) in days
148# How long users stay logged in before requiring re-authentication.
149#
150# Default: 7 days
151# Recommended ranges:
152# - High security: 1-7 days (default)
153# - Balanced: 14-30 days
154# - Convenience: 90 days
155#
156# Notes:
157# - Shorter TTL = more secure, more logins required
158# - Longer TTL = less secure, better user experience
159# - Consider your forum's security requirements
160# SESSION_TTL_DAYS=7
161
162# Redis session storage (optional, for multi-instance deployments)
163# If set, sessions are stored in Redis instead of memory.
164# Required for horizontal scaling (multiple appview instances).
165#
166# Format: redis://[username]:[password]@hostname:port/database
167#
168# Examples:
169# - Local Redis: redis://localhost:6379
170# - Docker Compose: redis://redis:6379
171# - Managed Redis: redis://default:password@redis.example.com:6379/0
172#
173# Notes:
174# - Leave blank/commented for single-instance deployments (uses in-memory)
175# - Required for multi-instance deployments (shared session state)
176# - Supports Redis Cluster and Sentinel configurations
177# REDIS_URL=redis://redis:6379
178
179# ============================================================================
180# Security Checklist
181# ============================================================================
182# Before deploying to production, verify:
183#
184# [ ] Generated SESSION_SECRET with: openssl rand -hex 32
185# [ ] Used strong, unique passwords (minimum 16 characters)
186# [ ] Never committed .env.production to version control
187# [ ] Set file permissions: chmod 600 .env.production
188# [ ] All URLs use HTTPS (except APPVIEW_URL for internal communication)
189# [ ] Database connection uses SSL/TLS (?sslmode=require)
190# [ ] Forum account password is unique (not reused)
191# [ ] SESSION_SECRET is different from dev/staging environments
192# [ ] Documented secret rotation schedule (every 90 days recommended)
193# [ ] Tested OAuth flow with OAUTH_PUBLIC_URL
194# [ ] Verified APPVIEW_URL is reachable from web service
195# [ ] Reviewed firewall rules (only expose necessary ports)
196#
197# ============================================================================
198# Deployment Notes
199# ============================================================================
200#
201# Single Container Deployment (appview + web in same container):
202# - Use APPVIEW_URL=http://localhost:3000
203# - No Redis required (in-memory sessions OK)
204# - Simpler setup, suitable for small forums
205#
206# Multi Container Deployment (separate appview and web containers):
207# - Use APPVIEW_URL=http://appview:3000 (Docker service name)
208# - Consider Redis for session storage
209# - Better scalability, suitable for larger forums
210#
211# Kubernetes Deployment:
212# - Use APPVIEW_URL=http://appview-service:3000
213# - Redis highly recommended for multi-replica deployments
214# - Use Secrets for sensitive values (not ConfigMaps)
215#
216# Environment Variable Loading:
217# - Docker: Use --env-file flag or docker-compose env_file
218# - Kubernetes: Mount as Secret or use external-secrets
219# - Systemd: Use EnvironmentFile=/path/to/.env.production
220# - Node.js: Use --env-file flag (Node 20.6+)
221#
222# ============================================================================
223# Troubleshooting
224# ============================================================================
225#
226# "Database connection failed":
227# - Verify DATABASE_URL is correct and accessible
228# - Check network connectivity to database host
229# - Ensure database exists and user has permissions
230# - Enable SSL if required by your database provider
231#
232# "OAuth redirect URI mismatch":
233# - Verify OAUTH_PUBLIC_URL matches your actual domain
234# - Must use HTTPS in production (not HTTP)
235# - Check for trailing slashes (should not have one)
236#
237# "Session errors / users logged out randomly":
238# - Verify SESSION_SECRET is set (not blank)
239# - For multi-instance: must use Redis (set REDIS_URL)
240# - Check SESSION_TTL_DAYS is reasonable (default 7)
241#
242# "Cannot reach appview API":
243# - Verify APPVIEW_URL uses correct hostname
244# - In Docker: use service name, not localhost
245# - Check container/service networking configuration
246#
247# ============================================================================