Deployment

Three ways to deploy TimeTiles to production. All include PostgreSQL, Nginx with SSL, and background workers.

Deployment Options

Docker Compose (Recommended)

# 1. Clone the deployment files
git clone https://github.com/jfilter/timetiles.git
cd timetiles
 
# 2. Configure
cp deployment/.env.production.example deployment/.env.production
nano deployment/.env.production
# Set at minimum: DOMAIN_NAME, DB_PASSWORD, PAYLOAD_SECRET, LETSENCRYPT_EMAIL
 
# 3. Pull images and start
timetiles pull
timetiles up
 
# 4. Set up SSL (after DNS is pointing to your server)
timetiles ssl

                    ┌──────────┐
                    │  Nginx   │ :80, :443
                    │ (SSL/TLS)│
                    └────┬─────┘
                         │
                    ┌────▼─────┐     ┌───────────┐
                    │  Next.js │────▶│ PostgreSQL │
                    │   Web    │     │ + PostGIS  │
                    └──────────┘     └───────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
  ┌─────▼──────┐  ┌─────▼──────┐  ┌──────▼─────┐
  │  Worker:   │  │  Worker:   │  │  Worker:    │
  │  Ingest    │  │  Default   │  │ Maintenance │
  └────────────┘  └────────────┘  └─────────────┘

Horizontal Web Scaling

If you run more than one web container or otherwise serve overlapping traffic from multiple Node.js processes, set:

RATE_LIMIT_BACKEND=pg

The default memory backend is only correct for single-web-instance deployments. In a multi-worker setup, leaving rate limits in memory would multiply the effective limit across workers.

All-in-One Container

Everything in a single container — PostgreSQL, Nginx, and the app — managed by supervisord. Good for quick demos or personal use.

docker run -d \
  -p 80:80 -p 443:443 \
  -v timetiles-data:/data \
  -e PAYLOAD_SECRET=$(openssl rand -base64 32) \
  -e DB_PASSWORD=$(openssl rand -base64 16) \
  ghcr.io/jfilter/timetiles:latest-allinone

Bootstrap Script (Ubuntu 24.04)

Fully automated setup on a fresh Ubuntu server. Installs Docker, configures firewall, deploys TimeTiles, sets up SSL, and enables security hardening (fail2ban, SSH hardening).

curl -sSL https://raw.githubusercontent.com/jfilter/timetiles/main/deployment/bootstrap/install.sh | sudo bash

The script prompts for your domain, email, and other settings interactively.

Configuration

Create your environment file from the template:

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

Required settings:

Shared-rate-limit setting for multi-web deployments:

See Configuration for the full environment variable reference.

SSL/TLS

Let’s Encrypt (Recommended)

After DNS is pointing to your server and services are running:

timetiles ssl

Certificates auto-renew every 12 hours via the certbot container.

Custom Certificates

Place your certificate files in deployment/nginx/ssl/:

• fullchain.pem — certificate + chain
• privkey.pem — private key

Then restart nginx: timetiles restart nginx

CLI Reference

The timetiles CLI wraps Docker Compose for common operations:

Direct Docker Compose

For advanced usage:

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

File Structure

A bootstrapped host keeps the deployment files in a real git working tree at /opt/timetiles-src/ and exposes them as /opt/timetiles/ via a symlink. timetiles update runs git pull against that tree, so tracked files (compose, nginx, the CLI itself) stay in sync with the upstream branch. Operator state is .gitignored inside deployment/ and survives every pull.

/opt/timetiles-src/
├── .git/                              # sparse-checkout: deployment/
└── deployment/
    ├── timetiles                      # CLI script (tracked)
    ├── docker-compose.prod.yml        # Service orchestration (tracked)
    ├── nginx/                         # Nginx config (tracked)
    │   ├── nginx.conf
    │   └── sites-enabled/
    ├── .env.production                # Your configuration (.gitignored)
    ├── docker-compose.override.yml    # Optional override (.gitignored)
    └── backups/                       # Backup files (.gitignored)

/opt/timetiles -> /opt/timetiles-src/deployment    # compat symlink

A manual install just keeps the deployment/ directory in your repo checkout and there is no symlink.

Security

• Only ports 80 and 443 are exposed externally
• PostgreSQL is on an internal Docker network — not accessible from outside
• The Next.js app runs as a non-root user in a read-only container
• Containers have dropped capabilities and tmpfs /tmp
• Nginx enforces HTTPS and sets security headers
• Auth endpoints are rate-limited at the Nginx level (5 req/min per IP)

Health Checks

# CLI status check
timetiles status
 
# HTTP health endpoint
curl https://your-domain.com/api/health
# Returns: {"status":"ok","timestamp":"..."}

Updating

# 1. Back up first
timetiles backup
 
# 2. Pull and redeploy
timetiles update
 
# 3. Verify
curl https://your-domain.com/api/health

Database migrations run automatically on container startup.

Troubleshooting

Optional: Scraper Runner

If you need scrapers (custom Python/Node.js scripts for data extraction), deploy the TimeScrape runner alongside TimeTiles. The runner is a separate stateless service that executes scripts in hardened Podman containers.

See Scraper Deployment for full setup instructions. In short:

1. Install Podman (rootless mode)
2. Build the base container images
3. Start the runner service
4. Set SCRAPER_RUNNER_URL and SCRAPER_API_KEY in your .env.production
5. Enable the enableScrapers feature flag in the admin dashboard

Next Steps

• Configure environment variables, geocoding, and feature flags
• Set up backups and monitoring
• Customize the UI with themes and branding