Complete PaaS Exit Playbook: Heroku to Self-Hosted in 72 Hours

illisecond auto-scaling or strict enterprise compliance certifications.

Core Solution

The 72-hour migration follows a strict containerization-first architecture, ensuring parity with PaaS deployment velocity while reclaiming infrastructure control.

Day 1: Containerize (8 hours)

Step 1: Create a Dockerfile Translate Heroku Procfile logic into a multi-stage Docker build to minimize image size and enforce production parity.

# 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"]

Step 2: Create docker-compose.yml Orchestrate app, database, cache, and reverse proxy with explicit resource limits and isolated networking.

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.