# 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](docker-compose.md)

Complete Docker orchestration for all services:

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

### [Environment Variables](environment-variables.md)

Comprehensive environment configuration:

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

### [Nginx Configuration](nginx.md)

Reverse proxy and routing:

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

### [SSL/TLS Setup](ssl-tls.md)

HTTPS configuration:

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

### [Tunneling](tunneling.md)

Public access via tunneling:

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

### [Backup & Restore](backup-restore.md)

Data protection:

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

### [Monitoring Stack](monitoring-stack.md)

Observability and alerting:

- Prometheus metrics
- Grafana dashboards
- Alertmanager alerts
- Service health checks
- Log aggregation

### [Healthchecks](healthchecks.md)

Container health monitoring:

- Docker healthchecks
- Service-specific checks
- Restart on failure
- Dependency management

### [Scaling](scaling.md)

Horizontal and vertical scaling:

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

## Quick Start

### Initial Deployment

1. **Prepare Server**
   ```bash
   # Ubuntu/Debian server with Docker installed
   apt update && apt install docker.io docker-compose git
   ```

2. **Clone Repository**
   ```bash
   git clone <repo-url> changemaker.lite
   cd changemaker.lite
   git checkout v2
   ```

3. **Configure Environment**
   ```bash
   cp .env.example .env
   # Edit .env with your settings
   ```

4. **Start Services**
   ```bash
   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)
   - Set up Pangolin account
   - Configure tunnel in admin UI
   - Deploy Newt container

2. **Enable Monitoring**
   ```bash
   docker compose --profile monitoring up -d
   ```

3. **Set Up Backups**
   ```bash
   # Configure backup.sh
   ./scripts/backup.sh

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

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

1. **Pull Latest Code**
   ```bash
   git pull origin v2
   ```

2. **Rebuild Containers**
   ```bash
   docker compose build
   docker compose up -d
   ```

3. **Run Migrations**
   ```bash
   docker compose exec api npx prisma migrate deploy
   ```

4. **Verify Services**
   ```bash
   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](../troubleshooting/index.md) for detailed solutions.

## Resource Requirements

### Minimum

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

### Recommended

- **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

## Related Documentation

- [Docker Compose](docker-compose.md)
- [Environment Variables](environment-variables.md)
- [Nginx Configuration](nginx.md)
- [SSL/TLS Setup](ssl-tls.md)
- [Tunneling](tunneling.md)
- [Backup & Restore](backup-restore.md)
- [Monitoring Stack](monitoring-stack.md)
- [Healthchecks](healthchecks.md)
- [Scaling](scaling.md)
- [Troubleshooting](../troubleshooting/index.md)