admin/changemaker.lite
1
0
Fork 0
Code Issues Packages Projects Releases 31 Wiki Activity
changemaker.lite/mkdocs/docs/v2/deployment/environment-variables.md

799 lines
24 KiB
Markdown
Raw Blame History

# Environment Variables Reference
## Overview
Changemaker Lite V2 uses over 100 environment variables to configure services, credentials, and feature flags. This document provides a complete reference organized by functional area.
**Configuration File**: `.env` (never committed to Git)
**Template**: `.env.example` (committed, safe to share)
**Validation**: `api/src/config/env.ts` (Zod schema validates all variables on startup)
---
## Quick Start
### Initial Setup
```bash
# Copy template
cp .env.example .env
# Generate secrets
openssl rand -hex 32 # For JWT_ACCESS_SECRET
openssl rand -hex 32 # For JWT_REFRESH_SECRET
openssl rand -hex 32 # For ENCRYPTION_KEY (must differ from JWT secrets!)
openssl rand -hex 16 # For LISTMONK_API_TOKEN
# Edit .env
nano .env
```
### Minimal Required Variables
**Must set before first start**:
```bash
V2_POSTGRES_PASSWORD=<strong-password>
REDIS_PASSWORD=<strong-password>
JWT_ACCESS_SECRET=<openssl-rand-hex-32>
JWT_REFRESH_SECRET=<openssl-rand-hex-32>
ENCRYPTION_KEY=<openssl-rand-hex-32> # Production only
```
**All other variables** have safe defaults for development.
---
## General Configuration
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `NODE_ENV` | `development` | No | Environment mode (`development` \| `production`) |
| `DOMAIN` | `cmlite.org` | No | Base domain for subdomain routing |
| `USER_ID` | `1000` | No | Host user ID for volume permissions |
| `GROUP_ID` | `1000` | No | Host group ID for volume permissions |
| `DOCKER_GROUP_ID` | `984` | No | Docker group ID (for homepage container) |
**Usage**:
```bash
NODE_ENV=production docker compose up -d
```
---
## V2 PostgreSQL
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `V2_POSTGRES_USER` | `changemaker` | No | PostgreSQL username |
| `V2_POSTGRES_PASSWORD` | `CHANGE_ME_STRONG_PASSWORD` | **Yes** | PostgreSQL password |
| `V2_POSTGRES_DB` | `changemaker_v2` | No | Database name |
| `V2_POSTGRES_PORT` | `5433` | No | Host port (container always 5432) |
**Connection String** (auto-generated in docker-compose.yml):
```
postgresql://changemaker:PASSWORD@changemaker-v2-postgres:5432/changemaker_v2
```
**Port Binding**: `127.0.0.1:5433:5432` (localhost only for security)
**Important**: Change `V2_POSTGRES_PASSWORD` before production deployment.
---
## JWT Authentication
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `JWT_ACCESS_SECRET` | `GENERATE_WITH_openssl_rand_hex_32` | **Yes** | Access token secret (15min lifespan) |
| `JWT_REFRESH_SECRET` | `GENERATE_WITH_openssl_rand_hex_32` | **Yes** | Refresh token secret (7 day lifespan) |
| `JWT_ACCESS_EXPIRY` | `15m` | No | Access token expiration (`15m`, `1h`, etc.) |
| `JWT_REFRESH_EXPIRY` | `7d` | No | Refresh token expiration (`7d`, `30d`, etc.) |
| `ENCRYPTION_KEY` | `GENERATE_WITH_openssl_rand_hex_32` | **Yes (prod)** | DB encryption key for SMTP passwords, etc. |
**Security Requirements** (enforced by Zod schema):
- `JWT_ACCESS_SECRET` must be 32+ characters
- `JWT_REFRESH_SECRET` must be 32+ characters
- `ENCRYPTION_KEY` must be 32+ characters **and differ from JWT secrets**
**Generation**:
```bash
export JWT_ACCESS_SECRET=$(openssl rand -hex 32)
export JWT_REFRESH_SECRET=$(openssl rand -hex 32)
export ENCRYPTION_KEY=$(openssl rand -hex 32)
echo "JWT_ACCESS_SECRET=${JWT_ACCESS_SECRET}" >> .env
echo "JWT_REFRESH_SECRET=${JWT_REFRESH_SECRET}" >> .env
echo "ENCRYPTION_KEY=${ENCRYPTION_KEY}" >> .env
```
**Production Note**: `ENCRYPTION_KEY` required in production (dev mode allows empty for testing).
---
## Redis
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `REDIS_PASSWORD` | `CHANGE_ME_REDIS_PASSWORD` | **Yes** | Redis authentication password |
| `REDIS_URL` | `redis://:PASSWORD@redis-changemaker:6379` | No | Full connection URL (auto-generated) |
**Format**: `redis://[:<password>@]<host>:<port>[/<db>]`
**Example**:
```bash
REDIS_PASSWORD=mySecurePassword123
REDIS_URL=redis://:mySecurePassword123@redis-changemaker:6379
```
**Security Note**: As of Security Audit 2025-02-11, Redis **requires authentication** in production.
**Docker Command** (in docker-compose.yml):
```yaml
command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy allkeys-lru --requirepass "${REDIS_PASSWORD}"
```
---
## API Configuration
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `API_PORT` | `4000` | No | Express API port (host) |
| `API_URL` | `http://localhost:4000` | No | Public API URL (for emails, OAuth redirects) |
| `CORS_ORIGINS` | `http://localhost:3000,http://localhost` | No | Allowed CORS origins (comma-separated) |
**Production Example**:
```bash
API_PORT=4000
API_URL=https://api.cmlite.org
CORS_ORIGINS=https://app.cmlite.org,https://cmlite.org
```
**CORS Note**: List all frontend origins (admin, public site, media gallery).
---
## Admin GUI
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `ADMIN_PORT` | `3000` | No | Admin GUI port (host) |
| `ADMIN_URL` | `http://localhost:3000` | No | Public admin URL |
| `VITE_API_URL` | `http://changemaker-v2-api:4000` | No | API URL for Vite proxy (Docker internal) |
| `VITE_MEDIA_API_URL` | `http://changemaker-media-api:4100` | No | Media API URL for Vite proxy |
| `VITE_MKDOCS_URL` | `http://mkdocs-changemaker:8000` | No | MkDocs URL for iframe embed |
**Development vs Production**:
**Development** (Docker):
```bash
VITE_API_URL=http://changemaker-v2-api:4000 # Container name
VITE_MEDIA_API_URL=http://changemaker-media-api:4100
```
**Development** (local):
```bash
VITE_API_URL=http://localhost:4000 # Localhost
VITE_MEDIA_API_URL=http://localhost:4100
```
**Production**: Vite build embeds these URLs at build time.
---
## Nginx
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `NGINX_HTTP_PORT` | `80` | No | HTTP port |
| `NGINX_HTTPS_PORT` | `443` | No | HTTPS port |
**Port Mapping** (docker-compose.yml):
```yaml
nginx:
ports:
- "80:80"
- "443:443"
- "8881:8881" # NocoDB embed proxy
- "8882:8882" # n8n embed proxy
- "8883:8883" # Gitea embed proxy
- "8884:8884" # MailHog embed proxy
- "8885:8885" # Mini QR embed proxy
```
**Custom Ports** (if 80/443 occupied):
```bash
NGINX_HTTP_PORT=8080
NGINX_HTTPS_PORT=8443
```
---
## SMTP / Email
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `SMTP_HOST` | `mailhog-changemaker` | No | SMTP server hostname |
| `SMTP_PORT` | `1025` | No | SMTP server port |
| `SMTP_USER` | `` | No | SMTP username (empty for MailHog) |
| `SMTP_PASS` | `` | No | SMTP password |
| `SMTP_FROM` | `noreply@cmlite.org` | No | Default sender email |
| `SMTP_FROM_NAME` | `Changemaker Lite` | No | Default sender name |
| `EMAIL_TEST_MODE` | `true` | No | Route all emails to MailHog (dev mode) |
| `TEST_EMAIL_RECIPIENT` | `admin@cmlite.org` | No | Override recipient in test mode |
**Development** (MailHog):
```bash
SMTP_HOST=mailhog-changemaker
SMTP_PORT=1025
SMTP_USER=
SMTP_PASS=
EMAIL_TEST_MODE=true
```
**Production** (e.g., ProtonMail):
```bash
SMTP_HOST=smtp.protonmail.ch
SMTP_PORT=587
SMTP_USER=your@email.com
SMTP_PASS=your-app-password
EMAIL_TEST_MODE=false
```
**Test Mode Behavior**:
- `true`: All emails sent to MailHog (visible at http://localhost:8025)
- `false`: Emails sent to real recipients via SMTP
**SiteSettings Override**: Admins can override SMTP config via `/app/settings` (stored encrypted in DB).
---
## Listmonk
### Database
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `LISTMONK_DB_PORT` | `5432` | No | Listmonk PostgreSQL port |
| `LISTMONK_DB_USER` | `listmonk` | No | Database username |
| `LISTMONK_DB_PASSWORD` | `CHANGE_ME_LISTMONK_PASSWORD` | **Yes** | Database password |
| `LISTMONK_DB_NAME` | `listmonk` | No | Database name |
### Web Admin
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `LISTMONK_PORT` | `9001` | No | Listmonk web UI port |
| `LISTMONK_WEB_ADMIN_USER` | `admin` | No | Web UI username |
| `LISTMONK_WEB_ADMIN_PASSWORD` | `CHANGE_ME_LISTMONK_ADMIN` | **Yes** | Web UI password |
### API Integration
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `LISTMONK_API_USER` | `v2-api` | No | API user (auto-created by listmonk-init) |
| `LISTMONK_API_TOKEN` | `GENERATE_WITH_openssl_rand_hex_16` | **Yes** | API token (plaintext, not bcrypt) |
| `LISTMONK_ADMIN_USER` | `v2-api` | No | Alias for API user (V2 uses this) |
| `LISTMONK_ADMIN_PASSWORD` | `SAME_AS_LISTMONK_API_TOKEN` | **Yes** | Alias for API token |
| `LISTMONK_SYNC_ENABLED` | `false` | No | Enable participant/location sync |
| `LISTMONK_PROXY_PORT` | `9002` | No | OAuth proxy port (for future integrations) |
**API User Setup**: The `listmonk-init` container auto-creates the API user by directly inserting into PostgreSQL.
**Token Generation**:
```bash
export LISTMONK_API_TOKEN=$(openssl rand -hex 16)
echo "LISTMONK_API_TOKEN=${LISTMONK_API_TOKEN}" >> .env
echo "LISTMONK_ADMIN_PASSWORD=${LISTMONK_API_TOKEN}" >> .env
```
**Sync Behavior**:
- `false`: Manual sync only (default)
- `true`: Auto-sync participants/locations to Listmonk lists on signup/create
### SMTP Configuration
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `LISTMONK_SMTP_HOST` | `mailhog-changemaker` | No | SMTP server for newsletters |
| `LISTMONK_SMTP_PORT` | `1025` | No | SMTP port |
| `LISTMONK_SMTP_USER` | `` | No | SMTP username |
| `LISTMONK_SMTP_PASSWORD` | `` | No | SMTP password |
| `LISTMONK_SMTP_TLS_TYPE` | `none` | No | TLS mode (`none` \| `STARTTLS` \| `TLS`) |
| `LISTMONK_SMTP_FROM` | `Changemaker Lite <noreply@cmlite.org>` | No | Newsletter sender |
**listmonk-init Behavior**: Configures **dual SMTP providers** (MailHog + production if credentials set).
---
## Represent API
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `REPRESENT_API_URL` | `https://represent.opennorth.ca` | No | Represent API endpoint (Canadian electoral data) |
**Free Public API**: No authentication required.
**Usage**: Postal code → representative lookup for Influence campaigns.
---
## NocoDB
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `NOCODB_V2_PORT` | `8091` | No | NocoDB web UI port |
| `NOCODB_URL` | `http://changemaker-v2-nocodb:8080` | No | Internal NocoDB URL |
| `NC_ADMIN_EMAIL` | `admin@cmlite.org` | No | Admin email |
| `NC_ADMIN_PASSWORD` | `CHANGE_ME_NOCODB_PASSWORD` | **Yes** | Admin password |
| `NC_PUBLIC_URL` | `http://localhost:8091` | No | Public NocoDB URL |
**Database Connection**: Uses separate `nocodb_meta` database (auto-created by `init-nocodb-db.sh`).
**Connection String**:
```
pg://changemaker-v2-postgres:5432?u=changemaker&p=PASSWORD&d=nocodb_meta
```
---
## Media Management
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `ENABLE_MEDIA_FEATURES` | `false` | No | Enable media manager features |
| `MEDIA_API_PORT` | `4100` | No | Fastify media API port |
| `MEDIA_API_PUBLIC_URL` | `http://media-api:4100` | No | Public media API URL |
| `MEDIA_ROOT` | `/media/library` | No | Media library root path |
| `MEDIA_UPLOADS` | `/media/uploads` | No | Upload staging directory |
| `MAX_UPLOAD_SIZE_GB` | `10` | No | Max video upload size (GB) |
| `PUBLIC_MEDIA_PORT` | `3100` | No | Public media gallery port |
| `VIDEO_PLAYER_DEBUG` | `false` | No | Enable video.js debug logging |
**Feature Flag**: Set `ENABLE_MEDIA_FEATURES=true` to activate media routes.
**Volume Mounts** (in docker-compose.yml):
```yaml
volumes:
- ${MEDIA_ROOT:-./media}:/media:ro # Library (read-only)
- ${MEDIA_ROOT:-./media}/local/inbox:/media/local/inbox:rw # Inbox (writable)
```
**Supported Formats**: MP4, MOV, AVI, MKV, WebM, M4V, FLV
---
## Gitea
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `GITEA_URL` | `http://gitea-changemaker:3000` | No | Internal Gitea URL |
| `GITEA_WEB_PORT` | `3030` | No | Gitea web UI port |
| `GITEA_SSH_PORT` | `2222` | No | Gitea SSH port (for git push/pull) |
| `GITEA_DB_TYPE` | `mysql` | No | Database type |
| `GITEA_DB_HOST` | `gitea-db:3306` | No | MySQL hostname |
| `GITEA_DB_NAME` | `gitea` | No | Database name |
| `GITEA_DB_USER` | `gitea` | No | Database username |
| `GITEA_DB_PASSWD` | `CHANGE_ME_GITEA_DB` | **Yes** | Database password |
| `GITEA_DB_ROOT_PASSWORD` | `CHANGE_ME_GITEA_ROOT` | **Yes** | MySQL root password |
| `GITEA_ROOT_URL` | `https://git.cmlite.org` | No | Public Gitea URL |
| `GITEA_DOMAIN` | `git.cmlite.org` | No | Gitea domain |
**First-Time Setup**: Visit http://localhost:3030 to create admin account.
**Git Commands**:
```bash
# Clone via HTTP
git clone http://localhost:3030/user/repo.git
# Clone via SSH
git clone ssh://git@localhost:2222/user/repo.git
```
---
## n8n
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `N8N_URL` | `http://n8n-changemaker:5678` | No | Internal n8n URL |
| `N8N_PORT` | `5678` | No | n8n port |
| `N8N_HOST` | `n8n.cmlite.org` | No | Public n8n hostname |
| `N8N_ENCRYPTION_KEY` | `CHANGE_ME_N8N_KEY` | **Yes** | Workflow encryption key |
| `N8N_USER_EMAIL` | `admin@example.com` | No | Default admin email |
| `N8N_USER_PASSWORD` | `CHANGE_ME_N8N_PASSWORD` | **Yes** | Default admin password |
| `GENERIC_TIMEZONE` | `UTC` | No | Workflow timezone |
**First Start**: n8n creates admin user with `N8N_USER_EMAIL`/`N8N_USER_PASSWORD` automatically.
**Encryption Key**: Used to encrypt credentials in workflows.
---
## MkDocs
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `MKDOCS_PORT` | `4003` | No | MkDocs live preview port |
| `MKDOCS_SITE_SERVER_PORT` | `4001` | No | MkDocs static site port |
| `BASE_DOMAIN` | `https://cmlite.org` | No | Site URL for sitemap/canonical |
| `MKDOCS_PREVIEW_URL` | `http://mkdocs:8000` | No | Internal preview URL |
| `MKDOCS_DOCS_PATH` | `/mkdocs/docs` | No | Documentation source path |
**Port Change**: Was 4000 in V1, changed to 4003 to avoid conflict with API.
**Live Reload**: http://localhost:4003 (updates on file save)
**Static Build**: http://localhost:4001 (Nginx-served production build)
---
## Code Server
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `CODE_SERVER_PORT` | `8888` | No | Code Server port |
| `CODE_SERVER_URL` | `http://code-server:8080` | No | Internal Code Server URL |
| `USER_NAME` | `coder` | No | Code Server username |
**Access**: http://localhost:8888
**Password**: Set in `configs/code-server/.config/code-server/config.yaml`
---
## Homepage
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `HOMEPAGE_PORT` | `3010` | No | Homepage dashboard port |
| `HOMEPAGE_VAR_BASE_URL` | `http://localhost` | No | Base URL for service links |
**Configuration**: Edit `configs/homepage/services.yaml` to customize dashboard.
---
## Mini QR
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `MINI_QR_PORT` | `8089` | No | Mini QR service port |
| `MINI_QR_URL` | `http://mini-qr:8080` | No | Internal Mini QR URL |
| `MINI_QR_EMBED_PORT` | `8885` | No | Nginx embed proxy port |
**Usage**: Walk sheets + cut exports embed QR codes via API or iframe.
---
## MailHog
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `MAILHOG_SMTP_PORT` | `1025` | No | SMTP port (internal only) |
| `MAILHOG_WEB_PORT` | `8025` | No | Web UI port |
**Web UI**: http://localhost:8025
**SMTP**: Only accessible from Docker network (not exposed to host).
---
## NAR Import
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `NAR_DATA_DIR` | `/data` | No | Path to NAR data directory (in container) |
**Host Mount** (in docker-compose.yml):
```yaml
volumes:
- ./data:/data:ro # Read-only NAR data
```
**Data Structure**:
```
./data/
└─ 202501/ (YYYYMM)
├─ Addresses/
│ ├─ Address_10.txt (PEI)
│ ├─ Address_24_part_1.txt (Quebec part 1)
│ └─ ...
└─ Locations/
├─ Location_10.txt
└─ ...
```
**Download**: https://www150.statcan.gc.ca/n1/pub/46-26-0002/462600022022001-eng.htm
---
## Geocoding
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `MAPBOX_API_KEY` | `` | No | Mapbox API key (optional, 100k free/month) |
| `GEOCODING_RATE_LIMIT_MS` | `1100` | No | Delay between provider requests (ms) |
| `GEOCODING_CACHE_ENABLED` | `true` | No | Enable Redis caching |
| `GEOCODING_CACHE_TTL_HOURS` | `24` | No | Cache TTL in hours |
| `GOOGLE_MAPS_API_KEY` | `` | No | Google Maps API key (optional, paid) |
| `GOOGLE_MAPS_ENABLED` | `false` | No | Enable Google geocoding provider |
| `GEOCODING_PARALLEL_ENABLED` | `true` | No | Parallel geocoding for bulk imports |
| `GEOCODING_BATCH_SIZE` | `10` | No | Batch size for parallel geocoding |
| `BULK_GEOCODE_ENABLED` | `true` | No | Enable bulk re-geocode feature |
| `BULK_GEOCODE_MAX_BATCH` | `5000` | No | Max locations per bulk geocode batch |
**Providers** (in fallback order):
1. **Nominatim** (OpenStreetMap, free)
2. **ArcGIS** (free tier)
3. **Photon** (free)
4. **Mapbox** (100k free/month, requires API key)
5. **LocationIQ** (free tier)
6. **Google** (paid, most accurate)
**Recommendation**: Add `MAPBOX_API_KEY` for better accuracy without cost.
---
## Pangolin Tunnel
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `PANGOLIN_API_URL` | `https://api.bnkserve.org/v1` | No | Pangolin API endpoint |
| `PANGOLIN_API_KEY` | `` | No | Pangolin API key |
| `PANGOLIN_ORG_ID` | `` | No | Organization ID (from setup wizard) |
| `PANGOLIN_SITE_ID` | `` | No | Site ID (from setup wizard) |
| `PANGOLIN_ENDPOINT` | `https://pangolin.bnkserve.org` | No | Tunnel endpoint URL |
| `PANGOLIN_NEWT_ID` | `` | No | Newt connector ID |
| `PANGOLIN_NEWT_SECRET` | `` | No | Newt connector secret |
**Setup Workflow**:
1. Visit `/app/pangolin` in admin GUI
2. Enter `PANGOLIN_API_KEY`
3. Create org → site → endpoint → resource
4. Copy `NEWT_ID`/`NEWT_SECRET` to `.env`
5. Restart Newt container
**Manual Setup**:
```bash
# Set API key
export PANGOLIN_API_KEY=your-api-key
# Create org (returns ORG_ID)
curl -H "Authorization: Bearer $PANGOLIN_API_KEY" \
https://api.bnkserve.org/v1/orgs \
-d '{"name":"My Organization"}'
# Create site (returns SITE_ID)
curl -H "Authorization: Bearer $PANGOLIN_API_KEY" \
https://api.bnkserve.org/v1/sites \
-d '{"org_id":"ORG_ID","name":"Production Site"}'
# Continue setup...
```
See [Tunneling](tunneling.md) for complete guide.
---
## Monitoring
### Prometheus
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `PROMETHEUS_PORT` | `9090` | No | Prometheus port |
**Scrape Targets** (configured in `configs/prometheus/prometheus.yml`):
- `changemaker-v2-api:4000/api/metrics` (10s interval)
- `redis-exporter:9121` (15s interval)
- `cadvisor:8080` (15s interval)
- `node-exporter:9100` (15s interval)
**Retention**: 30 days (configured in docker-compose.yml command).
### Grafana
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `GRAFANA_PORT` | `3001` | No | Grafana port |
| `GRAFANA_ADMIN_PASSWORD` | `admin` | No | Admin password |
| `GRAFANA_ROOT_URL` | `http://localhost:3001` | No | Public Grafana URL |
**Default Login**: admin / admin (change on first login)
**Dashboards**: 3 pre-configured dashboards auto-provisioned from `configs/grafana/`
### Exporters
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `CADVISOR_PORT` | `8080` | No | cAdvisor container metrics port |
| `NODE_EXPORTER_PORT` | `9100` | No | Node exporter system metrics port |
| `REDIS_EXPORTER_PORT` | `9121` | No | Redis exporter port |
### Alertmanager
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `ALERTMANAGER_PORT` | `9093` | No | Alertmanager port |
**Configuration**: Edit `configs/alertmanager/alertmanager.yml` for notification receivers.
### Gotify
| Variable | Default | Required | Description |
|----------|---------|----------|-------------|
| `GOTIFY_PORT` | `8889` | No | Gotify push notification server port |
| `GOTIFY_ADMIN_USER` | `admin` | No | Gotify admin username |
| `GOTIFY_ADMIN_PASSWORD` | `admin` | No | Gotify admin password |
**Usage**: Create apps in Gotify UI, add webhook URL to Alertmanager.
---
## Security Checklist
**Before production deployment**:
- [ ] Change all `CHANGE_ME_*` passwords
- [ ] Generate strong `JWT_ACCESS_SECRET` (32+ chars)
- [ ] Generate strong `JWT_REFRESH_SECRET` (32+ chars)
- [ ] Generate strong `ENCRYPTION_KEY` (32+ chars, **different from JWT secrets**)
- [ ] Set strong `REDIS_PASSWORD`
- [ ] Set strong `V2_POSTGRES_PASSWORD`
- [ ] Set strong `LISTMONK_DB_PASSWORD`
- [ ] Set strong `LISTMONK_API_TOKEN`
- [ ] Set strong `GITEA_DB_PASSWD` + `GITEA_DB_ROOT_PASSWORD`
- [ ] Set strong `N8N_ENCRYPTION_KEY` + `N8N_USER_PASSWORD`
- [ ] Set strong `NC_ADMIN_PASSWORD` (NocoDB)
- [ ] Set strong `GRAFANA_ADMIN_PASSWORD`
- [ ] Disable `EMAIL_TEST_MODE` (set to `false`)
- [ ] Configure real SMTP credentials
- [ ] Set `NODE_ENV=production`
- [ ] Review `CORS_ORIGINS` (whitelist only trusted domains)
**Validation**:
```bash
# Check for remaining placeholders
grep -r "CHANGE_ME" .env
# Verify secrets are different
echo "JWT_ACCESS_SECRET: $(grep JWT_ACCESS_SECRET .env)"
echo "JWT_REFRESH_SECRET: $(grep JWT_REFRESH_SECRET .env)"
echo "ENCRYPTION_KEY: $(grep ENCRYPTION_KEY .env)"
```
---
## Troubleshooting
### Missing .env File
**Symptoms**: Containers fail to start with "missing environment variable" errors
**Solution**:
```bash
# Create from template
cp .env.example .env
# Verify file exists
ls -la .env
```
---
### Invalid Environment Variables
**Symptoms**: API fails to start with Zod validation errors
**Diagnosis**:
```bash
# View API startup logs
docker compose logs api | grep -A10 "Environment validation"
```
**Common errors**:
- `JWT_ACCESS_SECRET` too short (must be 32+ chars)
- `ENCRYPTION_KEY` same as `JWT_ACCESS_SECRET` (must differ)
- Invalid URL format (`API_URL` must start with http:// or https://)
**Solution**:
```bash
# Regenerate secrets
export JWT_ACCESS_SECRET=$(openssl rand -hex 32)
export ENCRYPTION_KEY=$(openssl rand -hex 32)
# Update .env
sed -i "s/^JWT_ACCESS_SECRET=.*/JWT_ACCESS_SECRET=${JWT_ACCESS_SECRET}/" .env
sed -i "s/^ENCRYPTION_KEY=.*/ENCRYPTION_KEY=${ENCRYPTION_KEY}/" .env
# Restart API
docker compose restart api
```
---
### PostgreSQL Connection Failures
**Symptoms**: API logs show `ECONNREFUSED` or `authentication failed`
**Diagnosis**:
```bash
# Check PostgreSQL is running
docker compose ps v2-postgres
# Test connection
docker compose exec api npx prisma db pull
# Verify DATABASE_URL
docker compose exec api printenv | grep DATABASE_URL
```
**Solution**:
```bash
# Verify password matches in .env
grep V2_POSTGRES_PASSWORD .env
# Restart PostgreSQL
docker compose restart v2-postgres
# Wait for healthcheck
docker compose ps v2-postgres # Should show (healthy)
```
---
### Redis Connection Failures
**Symptoms**: API logs show `ECONNREFUSED` or `WRONGPASS invalid password`
**Diagnosis**:
```bash
# Check Redis is running
docker compose ps redis
# Test connection
docker compose exec redis redis-cli -a "${REDIS_PASSWORD}" ping
```
**Solution**:
```bash
# Verify password in .env
grep REDIS_PASSWORD .env
# Ensure REDIS_URL includes password
grep REDIS_URL .env # Should be redis://:PASSWORD@redis-changemaker:6379
# Restart Redis
docker compose restart redis
```
---
### Environment Variables Not Updating
**Symptoms**: Changed `.env` but service still uses old value
**Cause**: Docker Compose reads `.env` at startup, not runtime
**Solution**:
```bash
# Recreate container (picks up new env vars)
docker compose up -d --force-recreate api
# Or: stop and start
docker compose down
docker compose up -d
```
---
## Related Documentation
- **[Docker Compose](docker-compose.md)** — Service orchestration
- **[SSL/TLS](ssl-tls.md)** — Certificate management
- **[Tunneling](tunneling.md)** — Pangolin setup
- **[Backup & Restore](backup-restore.md)** — Data protection
- **[Security Audit](../../SECURITY_AUDIT_2025-02-11.md)** — Security requirements
Reference in New Issue View Git Blame Copy Permalink