josephradford · josephradford · Nov 18, 2025
diff --git a/.env-files-reference.md b/.env-files-reference.md
@@ -0,0 +1,182 @@
+# Environment Files Reference
+
+This document explains how environment files are used across the codebase.
+
+## Environment Files
+
+### `.env` (Production)
+- Used on the server for production deployments
+- Contains real credentials and API keys
+- **Never committed to git** (in `.gitignore`)
+- Required for: `make setup`, `make start`, all production operations
+
+### `.env.local` (Local Development)
+- Used on your Mac for local testing
+- Contains test/dummy values
+- **Never committed to git** (in `.gitignore`)
+- Required for: `make local-setup`, `make local-start`, all local operations
+- Created from `.env.local.example`
+
+### `.env.example` (Template for Production)
+- Template for production `.env`
+- Contains example values and documentation
+- **Committed to git**
+- Used to create production `.env`
+
+### `.env.local.example` (Template for Local)
+- Template for local `.env.local`
+- Contains safe default values for local testing
+- **Committed to git**
+- Used to create `.env.local`
+
+## Scripts Supporting Both Environments
+
+These scripts have been updated to support `ENV_FILE` variable:
+
+| Script | Usage | Environment Support |
+|--------|-------|-------------------|
+| `configure-homepage.sh` | Setup Homepage dashboard | ✅ Both (via ENV_FILE) |
+| `setup-homeassistant.sh` | Setup Home Assistant | ✅ Both (via ENV_FILE) |
+| `setup-traefik-password.sh` | Generate Traefik password | ✅ Both (via ENV_FILE) |
+
+**How it works:**
+- Default behavior: Uses `.env`
+- Override: Set `ENV_FILE=.env.local` before calling script
+- Example: `ENV_FILE=.env.local ./scripts/configure-homepage.sh`
+
+## Production-Only Scripts
+
+These scripts **only** use `.env` and should **not** be run locally:
+
+| Script | Purpose | Why Production-Only |
+|--------|---------|-------------------|
+| `setup-certbot-gandi.sh` | SSL certificate setup | Requires domain and Gandi API |
+| `copy-certs-to-traefik.sh` | Copy SSL certificates | No SSL in local mode |
+| `configure-traefik-file-provider.sh` | Configure Traefik SSL | No SSL in local mode |
+| `setup-cert-renewal.sh` | Setup auto-renewal | No SSL in local mode |
+| `setup-adguard-dns.sh` | Configure DNS rewrites | AdGuard disabled locally |
+| `setup-wireguard-routing.sh` | Setup VPN routing | WireGuard disabled locally |
+| `setup-firewall.sh` | Configure UFW firewall | Linux-only, server security |
+| `test-domain-access.sh` | Test domain routing | No domain routing locally |
+
+## Makefile Targets
+
+### Local Development (uses `.env.local`)
+```bash
+make local-setup      # ENV_FILE=.env.local
+make local-start      # Uses docker-compose.local.yml --env-file .env.local
+make local-stop
+make local-restart
+make local-logs
+make local-status
+make local-clean
+```
+
+### Production (uses `.env`)
+```bash
+make setup            # ENV_FILE=.env
+make start            # Uses default .env
+make stop
+make restart
+make logs
+make status
+```
+
+### Deployment
+```bash
+make deploy SERVER=user@host    # Deploys to server (server uses .env)
+```
+
+## Adding New Scripts
+
+When creating new scripts that load environment variables:
+
+### Option 1: Support Both Environments (Recommended for General Tools)
+
+```bash
+#!/bin/bash
+set -e
+
+# Load environment variables (support both .env and .env.local)
+ENV_FILE="${ENV_FILE:-.env}"
+
+if [ ! -f "$ENV_FILE" ]; then
+    echo "ERROR: $ENV_FILE file not found"
+    exit 1
+fi
+
+echo "Using environment file: $ENV_FILE"
+source "$ENV_FILE"
+
+# Your script logic here...
+```
+
+Then in Makefile:
+```makefile
+# Production target
+my-target:
+    @ENV_FILE=.env ./scripts/my-script.sh
+
+# Local target (if needed)
+local-my-target:
+    @ENV_FILE=.env.local ./scripts/my-script.sh
+```
+
+### Option 2: Production-Only (For SSL, DNS, VPN, etc.)
+
+```bash
+#!/bin/bash
+set -e
+
+# Load environment variables
+if [ ! -f .env ]; then
+    echo "ERROR: .env file not found"
+    exit 1
+fi
+
+source .env
+
+# Your production-only logic here...
+```
+
+## Verification
+
+Check which scripts support ENV_FILE:
+```bash
+grep -l "ENV_FILE=" scripts/*.sh
+```
+
+Check which scripts are production-only:
+```bash
+grep -l "source \.env" scripts/*.sh | while read f; do
+    if ! grep -q "ENV_FILE" "$f"; then
+        echo "$f (production-only)"
+    fi
+done
+```
+
+## Common Issues
+
+### Issue: Script can't find `.env`
+**Solution:** You're likely trying to run a production script locally.
+- Check if the script is in the "Production-Only" list above
+- Use the appropriate `make local-*` command instead
+
+### Issue: Variables not loading
+**Solution:** Ensure you're using the correct environment file
+- Local: `ENV_FILE=.env.local ./scripts/script.sh`
+- Production: `ENV_FILE=.env ./scripts/script.sh` (or just `./scripts/script.sh`)
+
+### Issue: Script modifying wrong .env file
+**Solution:** Check that script uses `$ENV_FILE` not hardcoded `.env`
+- Example: `echo "VAR=value" >> "$ENV_FILE"` ✅
+- Example: `echo "VAR=value" >> .env` ❌
+
+## Best Practices
+
+1. **Never commit `.env` or `.env.local`** - They contain secrets
+2. **Always update `.env.example` and `.env.local.example`** when adding variables
+3. **Test locally first** before deploying to production
+4. **Document production-only requirements** in script comments
+5. **Use ENV_FILE pattern** for scripts that could be useful in both environments
+6. **Keep production-only scripts simple** - Don't add ENV_FILE support if not needed
diff --git a/.env.local.example b/.env.local.example
@@ -0,0 +1,89 @@
+# Local Development Environment Configuration
+# Copy this to .env.local for local Mac development
+# Usage: make local-start (uses docker compose with this file)
+
+# Local Development - simplified configuration
+SERVER_IP=127.0.0.1
+TIMEZONE=UTC
+
+# Domain Configuration - not used locally but required for compose files
+DOMAIN=localhost
+
+# Let's Encrypt - not used locally
+ACME_EMAIL=test@localhost
+GANDIV5_PERSONAL_ACCESS_TOKEN=not-used-locally
+
+# AdGuard Home - disabled locally
+ADGUARD_USERNAME=admin
+ADGUARD_PASSWORD=test-password
+
+# n8n Configuration
+N8N_USER=admin
+N8N_PASSWORD=admin
+
+# n8n Performance Settings (safe defaults)
+DB_SQLITE_POOL_SIZE=5
+N8N_RUNNERS_ENABLED=true
+N8N_BLOCK_ENV_ACCESS_IN_NODE=false
+N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
+N8N_RUNNERS_TASK_TIMEOUT=1800
+EXECUTIONS_TIMEOUT=1800
+EXECUTIONS_TIMEOUT_MAX=3600
+
+# Traefik - dashboard password (use simple password for local)
+TRAEFIK_PASSWORD=admin
+# Traefik dashboard basic auth (not used in local mode with api.insecure=true)
+# This is just a dummy value to suppress warnings during docker compose config
+TRAEFIK_DASHBOARD_USERS=admin:$$2y$$05$$dummyhashforlocaltesting
+
+# Monitoring Configuration
+GRAFANA_PASSWORD=admin
+GRAFANA_USERNAME=admin
+
+# AlertManager - local webhook
+WEBHOOK_URL=http://127.0.0.1:5001/
+ALERT_EMAIL_FROM=alerts@localhost
+ALERT_EMAIL_USER=test@localhost
+ALERT_EMAIL_PASS=test
+ALERT_EMAIL_TO=test@localhost
+
+# WireGuard - disabled locally but env vars required
+WIREGUARD_SERVERURL=localhost
+WIREGUARD_PORT=51820
+WIREGUARD_PEERS=1
+WIREGUARD_SUBNET=10.13.13.0/24
+WIREGUARD_ALLOWEDIPS=192.168.1.0/24,10.13.13.0/24
+WIREGUARD_KEEPALIVE=25
+WIREGUARD_LOG_CONFS=false
+
+# Homepage Dashboard - macOS Docker Desktop values
+# On macOS, Docker runs in a VM so use defaults
+PUID=1000
+PGID=1000
+HOMEPAGE_ALLOWED_HOSTS=
+
+# Dashboard Services - minimal config for local testing
+BOM_LOCATION=sydney
+TRANSPORT_NSW_API_KEY=not-configured
+TRANSPORT_STOP_1_ID=10101323
+TRANSPORT_STOP_1_NAME="Test Stop"
+TRANSPORT_STOP_1_ICON=mdi-train
+TRANSPORT_STOP_2_ID=209300
+TRANSPORT_STOP_2_NAME="Test Bus"
+TRANSPORT_STOP_2_ICON=mdi-bus
+GOOGLE_CALENDAR_ICAL_URL=https://calendar.google.com/calendar/ical/test/basic.ics
+TOMTOM_API_KEY=not-configured
+TRAFFIC_ROUTE_1_NAME="Test Route"
+TRAFFIC_ROUTE_1_ORIGIN="Sydney NSW"
+TRAFFIC_ROUTE_1_DESTINATION="Parramatta NSW"
+TRAFFIC_ROUTE_1_SCHEDULE="Mon-Fri 07:00-09:00"
+TRAFFIC_ROUTE_2_NAME="Return"
+TRAFFIC_ROUTE_2_ORIGIN="Parramatta NSW"
+TRAFFIC_ROUTE_2_DESTINATION="Sydney NSW"
+TRAFFIC_ROUTE_2_SCHEDULE="Mon-Fri 17:00-19:00"
+
+# Home Assistant
+HOMEASSISTANT_URL=http://homeassistant:8123
+HOMEASSISTANT_TOKEN=
+
+# Actual Budget - no configuration needed
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
-# Environment variables
+# Environment variables (production and local)
 .env
+.env.local
 
 # Data directories
 data/