# Heroku Procfile: web: bundle exec puma -C config/puma.rb
# Docker equivalent:

FROM ruby:3.2-slim AS base
WORKDIR /app

# Install dependencies
RUN apt-get update && apt-get install -y \
  build-essential libpq-dev nodejs npm && \
  rm -rf /var/lib/apt/lists/*

COPY Gemfile Gemfile.lock ./
RUN bundle install --deployment --without development test

COPY . .
RUN bundle exec rake assets:precompile

# Production stage
FROM ruby:3.2-slim
WORKDIR /app

RUN apt-get update && apt-get install -y libpq-dev && \
  rm -rf /var/lib/apt/lists/*

COPY --from=base /app /app

USER 1000:1000
EXPOSE 3000
CMD ["bundle", "exec", "puma", "-C", "config/puma.rb"]

services:
  app:
    build: .
    user: "1000:1000"
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      - DATABASE_URL=postgres://app:${DB_PASS}@postgres:5432/app_prod
      - REDIS_URL=redis://redis:6379

/0 - RAILS_ENV=production - SECRET_KEY_BASE=${SECRET_KEY} depends_on: - postgres - redis deploy: resources: limits: memory: 1G cpus: '2.0' networks: - backend

postgres: image: postgres:16-alpine user: "999:999" volumes: - pgdata:/var/lib/postgresql/data environment: - POSTGRES_PASSWORD=${DB_PASS} - POSTGRES_DB=app_prod deploy: resources: limits: memory: 1G networks: - backend

redis: image: redis:7-alpine volumes: - redisdata:/data deploy: resources: limits: memory: 256M networks: - backend

traefik: image: traefik:v3 ports: - "443:443" - "80:80" volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./traefik:/etc/traefik networks: - backend

volumes: pgdata: redisdata:

networks: backend:

**Step 3: Test locally**
Validate container orchestration and application health before provisioning.

docker compose up --build

Hit localhost:3000, verify everything works

Run your test suite against Docker

### Day 2: Provision and Migrate Data (8 hours)
**Step 1: Provision the server**
Deploy a lightweight, high-IOPS VPS optimized for container workloads.

Hetzner CLI (or use their web UI)

hcloud server create
--name prod-01
--type cx41
--image ubuntu-24.04
--ssh-key my-key
--location nbg1

**Step 2: Bootstrap the server**
Harden the OS, install container runtime, and configure least-privilege networking.

SSH in and run

apt update && apt upgrade -y apt install -y docker.io docker-compose-v2 systemctl enable docker

Create deploy user

useradd -m -s /bin/bash deploy usermod -aG docker deploy

Set up firewall

ufw allow 22/tcp ufw allow 80/tcp ufw allow 443/tcp ufw enable

**Step 3: Migrate the database**
Perform a zero-downtime logical dump/restore using native PostgreSQL tooling.

Export from Heroku

heroku pg:backups:capture --app your-app heroku pg:backups:download --app your-app

Import to new Postgres

docker compose up -d postgres docker compose exec -T postgres pg_restore
-U postgres -d app_prod < latest.dump

**Step 4: Migrate files/assets**
Ephemeral filesystems require external object storage. Update environment variables to point to S3-compatible endpoints (Backblaze B2, Cloudflare R2, or AWS S3).

### Day 3: Go Live (4 hours)
**Step 1: Deploy and verify**
Launch the stack and monitor startup telemetry.

On the server

docker compose up -d docker compose logs -f app # Watch for startup errors

Health check

curl -s https://your-domain.com/health | jq .

**Step 2: Set up CI/CD**
Replicate `git push` deployment velocity using lightweight self-hosted runners.

.gitea/workflows/deploy.yml (or .github/workflows)

name: Deploy on: push: branches: [main]

jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Deploy run: | ssh deploy@your-server "cd /app && git pull && docker compose up -d --build"

**Step 3: Flip DNS**
Execute a controlled cutover with aggressive TTL management.

Update your domain's A record to the new server IP

TTL: start at 60 seconds, increase after verification

**Step 4: Monitor for 48 hours**
Maintain parallel PaaS infrastructure for instant rollback. Track response latency, error budgets, connection pooling, and memory pressure.

## Pitfall Guide
1. **Ignoring Ephemeral Filesystem Reality:** Heroku's filesystem resets on every deploy. If assets were stored locally, they are already lost. Always migrate to S3-compatible object storage before cutover, or accept data loss.
2. **Skipping the 48-Hour Parallel Run:** Cutting DNS immediately removes your rollback path. Keep Heroku running in read-only or shadow mode for 48 hours to validate error rates, background job queues, and cache warming.
3. **Misconfiguring Docker Resource Limits:** Omitting `deploy.resources.limits` or setting them too low triggers OOMKiller events under load. Always benchmark peak memory/CPU usage and add 20% headroom in `docker-compose.yml`.
4. **Hardcoding Secrets in Compose Files:** Embedding credentials directly in `docker-compose.yml` or Dockerfiles violates security best practices and leaks into version control. Use `.env` files, Docker secrets, or a vault solution, and ensure they are excluded from Git.
5. **Neglecting Database Connection Pooling:** Self-hosted Postgres defaults to `max_connections=100`. Application pools (e.g., Puma, Sidekiq) must be configured to respect this limit, or connection exhaustion will crash the app during traffic spikes.
6. **DNS TTL Mismanagement:** Leaving TTL at 24h/48h causes prolonged cache propagation, making rollbacks slow and painful. Set TTL to 60s 24 hours before migration, then increase to 3600s after stabilization.
7. **Underestimating Observability Replacement:** PaaS add-ons (Papertrail, Scout) provide structured logging and APM out-of-the-box. Self-hosting requires explicit setup of Loki/Prometheus/Grafana. Deploy these before cutover, or you'll be flying blind during the critical first 48 hours.

## Deliverables
- **72-Hour Migration Blueprint:** Step-by-step architectural runbook covering containerization, infrastructure provisioning, data migration, and DNS cutover strategies.
- **Pre-Flight & Execution Checklist:** Validation matrix for environment parity, secret rotation, database integrity checks, CI/CD pipeline testing, and post-migration observability verification.
- **Configuration Templates:** Production-ready `Dockerfile` (multi-stage), `docker-compose.yml` (resource-limited, Traefik-integrated), `.env` template, UFW hardening script, and Gitea/GitHub Actions CI/CD workflow.