Skip to content

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

  1. Prepare Server 

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

  2. Clone Repository 

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

  3. Configure Environment 

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

  4. 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

  5. Access Application 

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

Production Deployment

  1. Configure Tunneling (for public access)
  2. Set up Pangolin account
  3. Configure tunnel in admin UI

  4. Deploy Newt container

  5. Enable Monitoring 

    docker compose --profile monitoring up -d

  6. Set Up Backups 

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

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

  7. Secure Installation

  8. Change default passwords
  9. Enable Redis auth
  10. Configure firewall
  11. 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

  1. Pull Latest Code 

    git pull origin v2

  2. Rebuild Containers 

    docker compose build
docker compose up -d

  3. Run Migrations 

    docker compose exec api npx prisma migrate deploy

  4. 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
  • CPU: 4 cores
  • RAM: 8 GB
  • Disk: 50 GB SSD
  • Network: 100 Mbps

High Load

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