bunker-admin 7895ce683e Tonne of debugging - getting ready for the production builds

2026-02-16 10:44:18 -07:00

7.4 KiB

Raw Blame History

Deployment Overview

This section covers deploying Changemaker Lite V2 to production, including Docker orchestration, environment configuration, SSL/TLS setup, monitoring, backups, and scaling strategies.

Deployment Guide

Docker Compose

Complete Docker orchestration for all services:

20+ containers
Service dependencies
Health checks
Restart policies
Network configuration
Volume management

Environment Variables

Comprehensive environment configuration:

100+ environment variables
Required vs optional
Security considerations
Service-specific config
Feature flags

Nginx Configuration

Reverse proxy and routing:

Subdomain routing (12+ subdomains)
SSL/TLS termination
Security headers
Proxy settings
Static file serving

SSL/TLS Setup

HTTPS configuration:

Let's Encrypt integration
Certificate management
Auto-renewal
Security best practices
HSTS configuration

Tunneling

Public access via tunneling:

Pangolin tunnel setup
Newt container deployment
Resource configuration
Alternative to Cloudflare
DNS-free setup

Backup & Restore

Data protection:

PostgreSQL backups
Listmonk backups
Media file backups
S3 upload (optional)
Restore procedures
Automated schedules

Monitoring Stack

Observability and alerting:

Prometheus metrics
Grafana dashboards
Alertmanager alerts
Service health checks
Log aggregation

Healthchecks

Container health monitoring:

Docker healthchecks
Service-specific checks
Restart on failure
Dependency management

Scaling

Horizontal and vertical scaling:

Multi-instance deployment
Load balancing
Database replication
Cache scaling
Performance optimization

Quick Start

Initial Deployment

Prepare Server

# Ubuntu/Debian server with Docker installed
apt update && apt install docker.io docker-compose git

Clone Repository

git clone <repo-url> changemaker.lite
cd changemaker.lite
git checkout v2

Configure Environment

cp .env.example .env
# Edit .env with your settings

Start Services

docker compose up -d v2-postgres redis
docker compose up -d api admin
docker compose exec api npx prisma migrate deploy
docker compose exec api npx prisma db seed

Access Application

http://server-ip:3000
Login: admin@example.com / Admin123!

Production Deployment

Configure Tunneling (for public access)
- Set up Pangolin account
- Configure tunnel in admin UI
- Deploy Newt container

Enable Monitoring

docker compose --profile monitoring up -d

Set Up Backups

# Configure backup.sh
./scripts/backup.sh

# Add to crontab
0 2 * * * /path/to/backup.sh

Secure Installation
- Change default passwords
- Enable Redis auth
- Configure firewall
- Review security audit

Architecture Overview

Service Topology

Internet
  ↓
Pangolin Tunnel / Cloudflare
  ↓
Newt Container / Tunnel Daemon
  ↓
Nginx (Reverse Proxy)
  ↓
  ├→ Admin GUI (React, port 3000)
  ├→ Express API (TypeScript, port 4000)
  ├→ Media API (Fastify, port 4100)
  ├→ MkDocs (Documentation, port 4003)
  ├→ Grafana (Monitoring, port 3001)
  └→ Other Services...
  ↓
  ├→ PostgreSQL 16 (Database, port 5433)
  ├→ Redis 7 (Cache/Queue, port 6379)
  └→ Supporting Services...

Port Reference

Port	Service	Access
3000	Admin GUI	Public
4000	Express API	Public
4100	Media API	Public
5433	PostgreSQL	Internal
6379	Redis	Internal
3001	Grafana	Public
9090	Prometheus	Internal
8091	NocoDB	Public
9001	Listmonk	Public

Subdomain Routing

Subdomain	Target	Purpose
app.cmlite.org	Admin:3000	Admin interface
api.cmlite.org	API:4000	Express API
media.cmlite.org	Media:4100	Media API
docs.cmlite.org	MkDocs:4003	Documentation
grafana.cmlite.org	Grafana:3001	Monitoring
db.cmlite.org	NocoDB:8091	Data browser
listmonk.cmlite.org	Listmonk:9001	Newsletters

Production Checklist

Security

Change default admin password
Set strong PostgreSQL password
Set strong Redis password
Generate unique JWT secrets
Generate unique encryption key
Enable Redis authentication
Configure firewall rules
Review security audit findings

Environment

Set production NODE_ENV
Configure SMTP settings
Set up geocoding API keys
Configure Listmonk (if enabled)
Set media storage paths
Configure backup destinations

Services

Start core services
Run database migrations
Seed initial data
Test admin login
Verify API connectivity
Check service health

Monitoring

Enable monitoring stack
Configure Grafana dashboards
Set up Alertmanager
Test alert notifications
Review metrics collection

Backups

Configure backup script
Test backup/restore
Set up automated schedule
Configure S3 (optional)
Document restore procedure

Public Access

Configure tunnel (Pangolin/Cloudflare)
Test public URLs
Verify SSL/TLS
Check subdomain routing
Test from external network

Maintenance

Regular Tasks

Daily:

Monitor service health
Review error logs
Check disk space

Weekly:

Review backup success
Check queue depths
Update dependencies (if needed)

Monthly:

Security updates
Database optimization
Log rotation
Certificate renewal check

Updates

Pull Latest Code
```
git pull origin v2
```

Rebuild Containers

docker compose build
docker compose up -d

Run Migrations

docker compose exec api npx prisma migrate deploy

Verify Services

docker compose ps
curl http://localhost:4000/health

Troubleshooting

Common deployment issues:

Container fails to start - Check logs, environment variables
Database connection error - Verify PostgreSQL password, port
Redis connection error - Check Redis password, authentication
Nginx routing issues - Review nginx config, test upstream services
Tunnel connection fails - Verify Pangolin credentials, Newt config
SSL certificate errors - Check Let's Encrypt rate limits, renewal

See Troubleshooting Guide for detailed solutions.

Resource Requirements

Minimum

CPU: 2 cores
RAM: 4 GB
Disk: 20 GB SSD
Network: 10 Mbps

High Load

CPU: 8+ cores
RAM: 16+ GB
Disk: 100+ GB SSD
Network: 1 Gbps

7.4 KiB Raw Blame History