Docker Deployment Guide

Docker provides an easy, reproducible way to deploy Chirp with all its dependencies. This guide covers everything from basic Docker setup to production deployment.

Why Use Docker?

Benefits

Consistent Environment: Same configuration everywhere
Easy Updates: Simple container replacement
Dependency Isolation: No system conflicts
Quick Deployment: One-command setup
Scalability: Easy horizontal scaling
Security: Isolated containers

Prerequisites

Docker 20.10+ and Docker Compose 2.0+
Domain name (for production)
Basic Docker knowledge

Quick Start with Docker Compose

1. Clone Repository

git clone https://git.eidenz.moe/Eidenz/chirp.git
cd chirp

2. Configure Environment

Edit docker-compose.yml to set your configuration:

nano docker-compose.yml

At minimum, update these values in the chirp service environment section:

# IMPORTANT: Change these for production!
- JWT_SECRET=your_super_secure_jwt_secret_64_chars_minimum
- BASE_URL=https://your-domain.com
- CORS_ORIGIN=https://your-domain.com

The database credentials must also match between the postgres service and the chirp service:

# In postgres service:
POSTGRES_DB: chirp_production
POSTGRES_USER: chirp_user
POSTGRES_PASSWORD: secure_password_change_this

# In chirp service (must match):
- DB_HOST=postgres
- DB_PORT=5432
- DB_NAME=chirp_production
- DB_USER=chirp_user
- DB_PASSWORD=secure_password_change_this

3. Configure TURN Server (for Voice Channels)

The Docker Compose includes a Coturn TURN server for WebRTC voice channels. Set your server's public IP:

# Create a .env file next to docker-compose.yml
echo "TURN_EXTERNAL_IP=your.public.ip.address" > .env

Also open the required ports on your firewall:

3478 (UDP + TCP) — TURN signaling
49152-49252 (UDP) — TURN media relay

4. Start Services

# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Check status
docker compose ps

5. Access Chirp

The default Docker setup exposes Chirp on port 8080:

Web App: http://localhost:8080
API: http://localhost:8080/api

The included services are:

chirp-app — The Chirp application (port 8080 → 3001 internal)
chirp-postgres — PostgreSQL database
chirp-redis — Redis cache
chirp-coturn — Coturn TURN server for voice

6. Create First Account

Open http://localhost:8080 in your browser
Click "Register"
Create your account

Note: If email is not configured, check server logs for the verification link: docker compose logs chirp

Nginx Reverse Proxy (Production)

For production, place Nginx in front of Chirp with SSL termination.

/etc/nginx/sites-available/chirp:

server {
    listen 80;
    server_name your-domain.com www.your-domain.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com www.your-domain.com;

    # SSL configuration (Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # File uploads
    client_max_body_size 250M;

    # Proxy to Chirp app
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    # WebSocket support
    location /socket.io/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Deployment Commands

# Start all services
docker compose up -d

# View logs for specific service
docker compose logs -f chirp
docker compose logs -f postgres
docker compose logs -f redis
docker compose logs -f coturn

# Stop services
docker compose down

# Rebuild and restart
docker compose up -d --build

# Restart a single service
docker compose restart chirp

Database Management

Backups

# Database backup
docker compose exec postgres pg_dump -U chirp_user chirp_production | gzip > backup.sql.gz

# Automated backup script
cat > backup.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="./backups"

mkdir -p $BACKUP_DIR

# Database backup
docker compose exec -T postgres pg_dump -U chirp_user chirp_production | gzip > $BACKUP_DIR/db_backup_$DATE.sql.gz

# Files backup
tar czf $BACKUP_DIR/files_backup_$DATE.tar.gz ./uploads

# Clean old backups (keep 30 days)
find $BACKUP_DIR -name "*.gz" -mtime +30 -delete
EOF

chmod +x backup.sh

# Add to crontab for daily backups
echo "0 2 * * * /path/to/chirp/backup.sh" | crontab -

Restore

# Restore database
gunzip -c backup.sql.gz | docker compose exec -T postgres psql -U chirp_user chirp_production

# Restore files
tar xzf backups/files_backup_DATE.tar.gz -C .

Monitoring and Maintenance

Health Checks

# Check service health
docker compose ps

# View resource usage
docker stats

# Check logs
docker compose logs chirp

Updates

# Pull latest code
git pull origin main

# Rebuild and restart
docker compose up -d --build

Volumes and Data Persistence

The Docker setup uses named volumes and bind mounts:

Volume/Mount	Purpose
`postgres-data`	PostgreSQL database files
`redis-data`	Redis persistence
`./uploads`	User-uploaded files (bind mount)
`./server-config`	Server config files like VAPID keys (bind mount)

Troubleshooting

Common Issues

Container won't start:

# Check logs
docker compose logs chirp

# Check configuration
docker compose config

# Rebuild container
docker compose build --no-cache chirp

Database connection issues:

# Check database container
docker compose ps postgres
docker compose logs postgres

# Test database connection
docker compose exec postgres pg_isready -U chirp_user

Voice channels not working:

Ensure TURN_EXTERNAL_IP is set to your server's public IP
Open ports 3478 (UDP+TCP) and 49152-49252 (UDP) on your firewall
Check coturn logs: docker compose logs coturn

Permission issues:

# Fix upload directory permissions
sudo chown -R 1000:1000 ./uploads

Performance issues:

# Check resource usage
docker stats

# Clean up unused images
docker system prune -a

Next Steps

Production Setup Guide — Manual (non-Docker) setup instructions
Configuration Guide — Detailed configuration options

Need help? Check our troubleshooting guide.

Why Use Docker?​

Benefits​

Prerequisites​

Quick Start with Docker Compose​

1. Clone Repository​

2. Configure Environment​

3. Configure TURN Server (for Voice Channels)​

4. Start Services​

5. Access Chirp​

6. Create First Account​

Nginx Reverse Proxy (Production)​

Deployment Commands​

Database Management​

Backups​

Restore​

Monitoring and Maintenance​

Health Checks​

Updates​

Volumes and Data Persistence​

Troubleshooting​

Common Issues​

Next Steps​