Production Deployment

This guide covers deploying TimeTiles to production using Docker and Docker Compose.

Overview

TimeTiles provides a production-ready Docker deployment with:

Nginx reverse proxy with SSL/TLS termination
Next.js application server (standalone build)
PostgreSQL 17 with PostGIS 3.5+
Certbot for automatic SSL certificate renewal

Quick Start


# 1. Clone the repository
git clone https://github.com/jfilter/timetiles.git
cd timetiles
 
# 2. Run setup script
./deploy.sh setup
 
# 3. Configure environment
nano deployment/.env.production
# Set your domain, passwords, and email
 
# 4. Build and deploy
./deploy.sh build
./deploy.sh up
# Migrations run automatically on container startup
 
# 5. Initialize SSL (after DNS is configured)
./deploy.sh ssl

Prerequisites

See Installation Guide for complete system requirements and prerequisites.

File Structure


deployment/
├── Dockerfile.prod              # Multi-stage production build
├── docker-compose.prod.yml      # Service orchestration
├── deploy.sh                    # Deployment helper script
├── .env.production.example      # Environment template
├── .env.production             # Your configuration (create from .example)
└── nginx/                       # Nginx configuration
    ├── nginx.conf              # Main configuration
    └── sites-enabled/          # Site-specific configs

Configuration

Create your environment file:


cp deployment/.env.production.example deployment/.env.production
nano deployment/.env.production

See Configuration Guide for all environment variables. At minimum, configure:

DOMAIN_NAME - Your production domain
DB_PASSWORD - Strong database password
PAYLOAD_SECRET - Random 32+ character secret (generate with: openssl rand -base64 32)
LETSENCRYPT_EMAIL - Email for SSL certificate notifications

SSL/TLS Setup

Let’s Encrypt (Recommended)

Automatic SSL certificates:


# After DNS is configured and services are running
./deploy.sh ssl

Certificates auto-renew every 12 hours via Certbot.

Custom Certificates

Place certificates in deployment/nginx/ssl/:
- fullchain.pem (certificate + chain)
- privkey.pem (private key)
Update nginx config to reference your certificates
Restart: docker-compose -f deployment/docker-compose.prod.yml restart nginx

Deployment Commands

Using deploy.sh Script


# Service Management
./deploy.sh up        # Start all services
./deploy.sh down      # Stop all services
./deploy.sh restart   # Restart services
./deploy.sh status    # Check service health
 
# Maintenance
./deploy.sh logs      # View logs
./deploy.sh update    # Pull updates and redeploy
 
# Note: Database migrations run automatically on container startup

Direct Docker Compose

For advanced usage:


# Define alias for convenience
alias dc-prod="docker-compose -f deployment/docker-compose.prod.yml --env-file deployment/.env.production"
 
# Examples
dc-prod ps            # List containers
dc-prod logs web      # View web logs
dc-prod exec web sh   # Shell into web container

Security

Network Security

Only ports 80 (HTTP) and 443 (HTTPS) are exposed
Internal services communicate on private Docker network
PostgreSQL is not exposed externally

Application Security

Next.js runs as non-root user
Environment secrets isolated
HTTPS enforced with security headers
Rate limiting on API endpoints

Security Checklist

Strong database password (20+ characters)
Random Payload secret (32+ characters)
HTTPS enabled with valid certificate
Firewall configured (allow only 80, 443, SSH)
Regular security updates enabled
Backup strategy in place

Health Checks

Verify deployment:


# Check all services
./deploy.sh status
 
# Check application health
curl https://your-domain.com/api/health
 
# Should return: {"status":"ok","timestamp":"..."}

Common Issues

Build Fails with Out of Memory

Add swap space:


sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Or build locally and push image to registry.

SSL Certificate Fails

Verify DNS and Let’s Encrypt challenge:


# Check DNS resolves to your server
nslookup your-domain.com
 
# Test HTTP challenge path
curl http://your-domain.com/.well-known/acme-challenge/test

For more troubleshooting, see Maintenance Guide.

Next Steps

After successful deployment:

Set up monitoring: See Monitoring Guide
Configure backups: See Backup Guide
Performance tuning: See Maintenance Guide
Review security: See Configuration Guide

Updating Production

To deploy updates:


# Pull latest changes
git pull
 
# Rebuild and redeploy
./deploy.sh update
 
# Or manually:
./deploy.sh down
./deploy.sh build
./deploy.sh up
# Migrations run automatically on container startup

See Maintenance Guide for routine operations.