Epic Stack: Deployment

When to use this skill

Use this skill when you need to:

Configure deployment on Fly.io
Setup multi-region deployment
Configure CI/CD with GitHub Actions
Manage secrets in production
Configure healthchecks
Work with LiteFS and volumes
Local deployment with Docker

Patterns and conventions

Fly.io Configuration

Epic Stack uses Fly.io for hosting with configuration in fly.toml.

Basic configuration:

# fly.toml
app = "your-app-name"
primary_region = "sjc"
kill_signal = "SIGINT"
kill_timeout = 5

[build]
dockerfile = "/other/Dockerfile"
ignorefile = "/other/Dockerfile.dockerignore"

[mounts]
source = "data"
destination = "/data"

Primary Region

Configure primary region:

primary_region = "sjc" # Change according to your location

Important: The primary region must be the same for:

primary_region en fly.toml
Region del volume data
PRIMARY_REGION en variables de entorno

LiteFS Configuration

Configuration in other/litefs.yml:

fuse:
  dir: '${LITEFS_DIR}'

data:
  dir: '/data/litefs'

proxy:
  addr: ':${INTERNAL_PORT}'
  target: 'localhost:${PORT}'
  db: '${DATABASE_FILENAME}'

lease:
  type: 'consul'
  candidate: ${FLY_REGION == PRIMARY_REGION}
  promote: true
  advertise-url: 'http://${HOSTNAME}.vm.${FLY_APP_NAME}.internal:20202'
  consul:
    url: '${FLY_CONSUL_URL}'
    key: 'epic-stack-litefs_20250222/${FLY_APP_NAME}'

exec:
  - cmd: npx prisma migrate deploy
    if-candidate: true
  - cmd: sqlite3 $DATABASE_PATH "PRAGMA journal_mode = WAL;"
    if-candidate: true
  - cmd: sqlite3 $CACHE_DATABASE_PATH "PRAGMA journal_mode = WAL;"
    if-candidate: true
  - cmd: npx prisma generate --sql
  - cmd: npm start

Healthchecks

Configuration in fly.toml:

[[services.http_checks]]
interval = "10s"
grace_period = "5s"
method = "get"
path = "/resources/healthcheck"
protocol = "http"
timeout = "2s"
tls_skip_verify = false

Healthcheck implementation:

// app/routes/resources/healthcheck.tsx
export async function loader({ request }: Route.LoaderArgs) {
	const host =
		request.headers.get('X-Forwarded-Host') ?? request.headers.get('host')

	try {
		await Promise.all([
			prisma.user.count(), // Verify DB
			fetch(`${new URL(request.url).protocol}${host}`, {
				method: 'HEAD',
				headers: { 'X-Healthcheck': 'true' },
			}),
		])
		return new Response('OK')
	} catch (error) {
		console.log('healthcheck ❌', { error })
		return new Response('ERROR', { status: 500 })
	}
}

Environment Variables

Secrets in Fly.io:

# Generate secrets
fly secrets set SESSION_SECRET=$(openssl rand -hex 32) --app [YOUR_APP_NAME]
fly secrets set HONEYPOT_SECRET=$(openssl rand -hex 32) --app [YOUR_APP_NAME]

# List secrets
fly secrets list --app [YOUR_APP_NAME]

# Delete secret
fly secrets unset SECRET_NAME --app [YOUR_APP_NAME]

Common secrets:

SESSION_SECRET - Secret for signing session cookies
HONEYPOT_SECRET - Secret for honeypot fields
DATABASE_URL - Automatically configured by LiteFS
CACHE_DATABASE_PATH - Automatically configured
RESEND_API_KEY - For sending emails (optional)
TIGRIS_* - For image storage (automatic)
SENTRY_DSN - For error monitoring (optional)

Volumes

Create volume:

fly volumes create data --region sjc --size 1 --app [YOUR_APP_NAME]

List volumes:

fly volumes list --app [YOUR_APP_NAME]

Expand volume:

fly volumes extend <volume-id> --size 10 --app [YOUR_APP_NAME]

Multi-Region Deployment

Deploy to multiple regions:

# Deploy in primary region (more instances)
fly scale count 2 --region sjc --app [YOUR_APP_NAME]

# Deploy in secondary regions (read-only)
fly scale count 1 --region ams --app [YOUR_APP_NAME]
fly scale count 1 --region syd --app [YOUR_APP_NAME]

Verify instances:

fly status --app [YOUR_APP_NAME]
# The ROLE column will show "primary" or "replica"

Consul Setup

Attach Consul:

fly consul attach --app [YOUR_APP_NAME]

Consul manages:

Which instance is primary
Automatic failover
Data replication

GitHub Actions CI/CD

Basic workflow:

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main, dev]

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

Complete configuration:

Deploy to production from main branch
Deploy to staging from dev branch
Tests before deploy (optional)

Deployable Commits

Following Epic Web principles:

Deployable commits - Every commit to the main branch should be deployable. This means:

The code should be in a working state
Tests should pass
The application should build successfully
No "WIP" or "TODO" commits that break the build

Example - Deployable commit workflow:

# ✅ Good - Each commit is deployable
git commit -m "Add user profile page"
# This commit is complete, tested, and deployable

git commit -m "Fix login redirect bug"
# This commit fixes a bug and is deployable

# ❌ Avoid - Non-deployable commits
git commit -m "WIP: working on feature"
# This commit might not work, not deployable

git commit -m "Add feature (tests failing)"
# This commit breaks the build, not deployable

Benefits:

Easy rollback - any commit can be deployed
Continuous deployment - deploy any time
Clear history - each commit represents a working state
Faster recovery - can deploy any previous commit

Small and Short Lived Merge Requests

Following Epic Web principles:

Small and short lived merge requests - Keep PRs small and merge them quickly. Large PRs are hard to review, risky to merge, and slow down the team.

Guidelines:

Small PRs - Focus on one feature or fix per PR
Short-lived - Merge within a day or two, not weeks
Reviewable - PRs should be reviewable in 30 minutes or less
Independent - Each PR should be independently deployable

Example - Small, focused PR:

# ✅ Good - Small, focused PR
# PR: "Add email validation to signup form"
# - Only changes signup validation
# - Includes tests
# - Can be reviewed quickly
# - Can be merged and deployed independently

# ❌ Avoid - Large, complex PR
# PR: "Refactor authentication system and add 2FA and OAuth"
# - Too many changes at once
# - Hard to review
# - Risky to merge
# - Takes days to review

Benefits:

Faster reviews - easier to understand and review
Lower risk - smaller changes are less risky
Faster feedback - get feedback sooner
Easier rollback - smaller changes are easier to revert
Better collaboration - team can work in parallel on different small PRs

When PRs get too large:

Split into multiple smaller PRs
Use feature flags to merge incrementally
Break down into logical pieces

Tigris Object Storage

Create storage:

fly storage create --app [YOUR_APP_NAME]

This creates:

Tigris bucket
Automatic environment variables:
- TIGRIS_ENDPOINT
- TIGRIS_ACCESS_KEY_ID
- TIGRIS_SECRET_ACCESS_KEY
- TIGRIS_BUCKET_NAME

Database Migrations

Automatic migrations: Migrations are automatically applied on deploy via litefs.yml:

exec:
  - cmd: npx prisma migrate deploy
    if-candidate: true

Note: Only the primary instance runs migrations (if-candidate: true).

Database Backups

Create backup:

# SSH to instance
fly ssh console --app [YOUR_APP_NAME]

# Create backup
mkdir /backups
litefs export -name sqlite.db /backups/backup-$(date +%Y-%m-%d).db
exit

# Download backup
fly ssh sftp get /backups/backup-2024-01-01.db --app [YOUR_APP_NAME]

Restore backup:

# Upload backup
fly ssh sftp shell --app [YOUR_APP_NAME]
put backup-2024-01-01.db
# Ctrl+C to exit

# SSH and restore
fly ssh console --app [YOUR_APP_NAME]
litefs import -name sqlite.db /backup-2024-01-01.db
exit

Deployment Local

Deploy con Fly CLI:

fly deploy

Deploy con Docker:

# Build
docker build -t epic-stack . -f other/Dockerfile \
  --build-arg COMMIT_SHA=$(git rev-parse --short HEAD)

# Run
docker run -d \
  -p 8081:8081 \
  -e SESSION_SECRET='secret' \
  -e HONEYPOT_SECRET='secret' \
  -e FLY='false' \
  -v ~/litefs:/litefs \
  epic-stack

Zero-Downtime Deploys

Strategy:

Deploy to multiple instances
Automatic blue-green deployment
Healthchecks verify app is ready
Auto-rollback if healthcheck fails

Configuration:

[experimental]
auto_rollback = true

Monitoring

View logs:

fly logs --app [YOUR_APP_NAME]

View metrics:

fly dashboard --app [YOUR_APP_NAME]
# Or visit: https://fly.io/apps/[YOUR_APP_NAME]/monitoring

Sentry (opcional):

fly secrets set SENTRY_DSN=your-sentry-dsn --app [YOUR_APP_NAME]

Common examples

Example 1: Complete initial setup

# 1. Create apps
fly apps create my-app
fly apps create my-app-staging

# 2. Configure secrets
fly secrets set \
  SESSION_SECRET=$(openssl rand -hex 32) \
  HONEYPOT_SECRET=$(openssl rand -hex 32) \
  --app my-app

fly secrets set \
  SESSION_SECRET=$(openssl rand -hex 32) \
  HONEYPOT_SECRET=$(openssl rand -hex 32) \
  ALLOW_INDEXING=false \
  --app my-app-staging

# 3. Create volumes
fly volumes create data --region sjc --size 1 --app my-app
fly volumes create data --region sjc --size 1 --app my-app-staging

# 4. Attach Consul
fly consul attach --app my-app
fly consul attach --app my-app-staging

# 5. Create storage
fly storage create --app my-app
fly storage create --app my-app-staging

# 6. Deploy
fly deploy --app my-app

Example 2: Multi-region setup

# First region (primary) - 2 instances
fly scale count 2 --region sjc --app my-app

# Secondary regions - 1 instance each
fly scale count 1 --region ams --app my-app
fly scale count 1 --region syd --app my-app

# Verify
fly status --app my-app

Example 3: GitHub Actions workflow

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main, dev]

jobs:
  deploy-production:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only --app my-app
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

  deploy-staging:
    if: github.ref == 'refs/heads/dev'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only --app my-app-staging
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

Example 4: Deploy with migrations

# Create migration
npx prisma migrate dev --name add_field

# Commit and push
git add .
git commit -m "Add field"
git push origin main

# GitHub Actions automatically runs:
# 1. Build
# 2. Deploy
# 3. litefs.yml runs: npx prisma migrate deploy (only on primary)

Common mistakes to avoid

❌ Non-deployable commits: Every commit to main should be deployable - no WIP or broken commits
❌ Large, long-lived PRs: Keep PRs small and merge quickly - large PRs are hard to review and risky
❌ Inconsistent primary region: Make sure primary_region in fly.toml matches the volume region
❌ Secrets not configured: Configure all secrets before first deploy
❌ Volume not created: Create the data volume before deploy
❌ Consul not attached: Attach Consul before first deploy
❌ Migrations on replicas: Only the primary instance should run migrations
❌ Not using healthchecks: Healthchecks are critical for zero-downtime deploys
❌ Deploy breaking changes without strategy: Use "widen then narrow" for migrations
❌ Secrets in code: Never commit secrets, use fly secrets
❌ Not making backups: Make regular database backups
❌ FLY_API_TOKEN exposed: Never commit the token, only in GitHub Secrets

References

Epic Stack Deployment Docs
Epic Web Principles
Fly.io Documentation
LiteFS Documentation
Fly.io CLI Reference
fly.toml - Fly.io configuration
other/litefs.yml - LiteFS configuration
other/Dockerfile - Deployment Dockerfile
.github/workflows/deploy.yml - CI/CD workflow

Preview Deployments (Inspired by Vercel Deploy Claimable)

Epic Stack can implement preview deployments similar to Vercel's deploy claimable pattern.

✅ Good - Preview deployments for pull requests:

# .github/workflows/preview-deploy.yml
name: Preview Deploy

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - name: Deploy preview
        run: |
          # Create or reuse preview app
          PREVIEW_APP="my-app-pr-${{ github.event.pull_request.number }}"
          flyctl apps list | grep "$PREVIEW_APP" || flyctl apps create "$PREVIEW_APP"

          # Deploy to preview app
          flyctl deploy --app "$PREVIEW_APP" --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
      - name: Comment preview URL
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `🚀 Preview deployment: https://$PREVIEW_APP.fly.dev`
            })

✅ Good - Auto-cleanup preview deployments:

# .github/workflows/cleanup-preview.yml
name: Cleanup Preview

on:
  pull_request:
    types: [closed]

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - name: Destroy preview app
        run: |
          PREVIEW_APP="my-app-pr-${{ github.event.pull_request.number }}"
          flyctl apps destroy "$PREVIEW_APP" --yes
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

Environment Detection

✅ Good - Detect deployment environment:

// app/utils/env.server.ts
export function getDeploymentEnv():
	| 'production'
	| 'staging'
	| 'preview'
	| 'development' {
	if (process.env.NODE_ENV === 'development') {
		return 'development'
	}

	// Preview deployments
	if (process.env.FLY_APP_NAME?.includes('pr-')) {
		return 'preview'
	}

	// Staging environment
	if (process.env.FLY_APP_NAME?.includes('staging')) {
		return 'staging'
	}

	// Production
	return 'production'
}

✅ Good - Environment-specific configuration:

const env = getDeploymentEnv()

export const config = {
	production: env === 'production',
	staging: env === 'staging',
	preview: env === 'preview',
	development: env === 'development',

	// Preview deployments might have limited features
	features: {
		analytics: env === 'production',
		sentry: env !== 'development',
		indexing: env === 'production',
	},
}

Build Artifact Exclusion

✅ Good - Optimize Docker builds:

# other/Dockerfile
# Multi-stage build for smaller image size
FROM node:20-alpine AS base
WORKDIR /app

# Install dependencies
FROM base AS deps
COPY package*.json ./
RUN npm ci --only=production

# Build application
FROM base AS builder
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production image
FROM base AS runner
ENV NODE_ENV=production

# Copy only what's needed
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/build ./build
COPY --from=builder /app/public ./public
COPY --from=builder /app/server ./server
COPY --from=builder /app/other ./other
COPY --from=builder /app/prisma ./prisma
COPY --from=builder /app/package.json ./

# Exclude unnecessary files
# node_modules/.cache, .git, etc. are already excluded via .dockerignore

CMD ["npm", "start"]

✅ Good - Docker ignore file:

# .dockerignore (in other/)
node_modules
.git
.env
.env.*
!.env.example
*.log
.DS_Store
coverage
.vscode
.idea
*.swp
*.swo
*~
.cache
dist
build

Deployment Status and Monitoring

✅ Good - Deployment status tracking:

// app/routes/admin/deployment-status.tsx
export async function loader({ request }: Route.LoaderArgs) {
	const deploymentInfo = {
		appName: process.env.FLY_APP_NAME,
		region: process.env.FLY_REGION,
		environment: getDeploymentEnv(),
		commitSha: process.env.COMMIT_SHA,
		deployedAt: process.env.DEPLOYED_AT,
	}

	return { deploymentInfo }
}

Rollback Strategies

✅ Good - Quick rollback with Fly.io:

# List recent releases
fly releases list --app my-app

# Rollback to previous release
fly releases rollback --app my-app

✅ Good - Automated rollback on failure:

# fly.toml
[experimental]
  auto_rollback = true
  min_machines_running = 1

epic-deployment

プレビュー