360 lines
7.4 KiB
Markdown
360 lines
7.4 KiB
Markdown
# 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)
|