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 enterprise-grade container orchestration.

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

Use Cases

Quick Start: Get running in minutes
Development: Consistent dev environments
Testing: Isolated test environments
Production: Reliable deployments
Multi-tenant: Run multiple instances

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 configuration
nano docker-compose.yml

Basic configuration:

NODE_ENV=production
PORT=3001
BASE_URL=https://your-domain.com

# Database (will use PostgreSQL container)
DB_HOST=postgres
DB_PORT=5432
DB_USER=chirp
DB_PASSWORD=secure_password_here
DB_NAME=chirp
DB_SSL=false

# Security
JWT_SECRET=your_super_secure_jwt_secret_64_chars_minimum
ADMIN_KEY=your_secure_admin_key

# Redis (will use Redis container)
REDIS_HOST=redis
REDIS_PORT=6379

3. Start Services

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Check status
docker-compose ps

Access Chirp at http://localhost:5173 (development) or configure reverse proxy for production.

Nginx Configuration

nginx/nginx.conf:

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # Logging
    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    # Performance settings
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

    # Security headers
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";

    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;

    # Include site configurations
    include /etc/nginx/conf.d/*.conf;
}

nginx/sites/default.conf:

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
    ssl_certificate /etc/ssl/certs/your-domain.crt;
    ssl_certificate_key /etc/ssl/certs/your-domain.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # File uploads
    client_max_body_size 100M;

    # Serve static files
    location /uploads/ {
        alias /var/www/uploads/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Proxy to Chirp app
    location / {
        proxy_pass http://chirp-server:3001;
        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://chirp-server:3001;
        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 development environment
docker-compose up -d

# View logs
docker-compose logs -f chirp-server
docker-compose logs -f chirp-web

# Stop services
docker-compose down

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

Database Management

Backups

# Database backup
docker-compose exec postgres pg_dump -U chirp chirp | 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 chirp | gzip > $BACKUP_DIR/db_backup_$DATE.sql.gz

# Files backup
docker run --rm -v chirp_chirp_uploads:/data -v $PWD/backups:/backup alpine tar czf /backup/files_backup_$DATE.tar.gz -C /data .

# 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 chirp

# Restore files
docker run --rm -v chirp_chirp_uploads:/data -v $PWD/backups:/backup alpine tar xzf /backup/files_backup_DATE.tar.gz -C /data

Monitoring and Maintenance

Health Checks

# Check service health
docker-compose ps

# View resource usage
docker stats

# Check logs
docker-compose logs chirp-server

Log Management

# Rotate logs
docker-compose exec chirp-server logrotate /etc/logrotate.d/chirp

# View real-time logs
docker-compose logs -f --tail=100

# Export logs
docker-compose logs --no-color > chirp-logs.txt

Updates

# Update containers
docker-compose pull
docker-compose build
docker-compose up -d

Production Best Practices

Security

Run as non-root user (configured in Dockerfile)
Limit container resources (deploy section in compose)
Use secrets for sensitive data

Backup Strategy

Regular database backups (daily)
File backups (weekly)
Off-site storage for critical backups
Test restores periodically

Monitoring

Container health checks (configured in Dockerfile)
Resource monitoring (docker stats)
Log aggregation (ELK stack or similar)
Alerting for critical failures

Troubleshooting

Common Issues

Container won't start:

# Check logs
docker-compose logs chirp-server

# Check configuration
docker-compose config

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

Database connection issues:

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

# Test connection
docker-compose exec chirp-server ping postgres

Permission issues:

# Fix file permissions
docker-compose exec chirp-server chown -R chirp:chirp /app/uploads

# Check user permissions
docker-compose exec chirp-server id

Performance issues:

# Check resource usage
docker stats

# Optimize Docker image
docker history chirp:latest

# Clean up unused images
docker system prune -a

Next Steps

Production Setup Guide - Manual setup instructions
Configuration Guide - Detailed configuration options

Need help? Check our troubleshooting guide.

Why Use Docker?​

Benefits​

Use Cases​

Prerequisites​

Quick Start with Docker Compose​

1. Clone Repository​

2. Configure Environment​

3. Start Services​

Nginx Configuration​

Deployment Commands​

Database Management​

Backups​

Restore​

Monitoring and Maintenance​

Health Checks​

Log Management​

Updates​

Production Best Practices​

Security​

Backup Strategy​

Monitoring​

Troubleshooting​

Common Issues​

Next Steps​