Gleam Deployment Skill

This skill guides Claude Code through deploying Gleam applications to production.

Primary Sources

1. •Deploying to Fly.io - Official Fly.io deployment guide
2. •Gleam Export Command - Building releases
3. •Docker Best Practices - Container optimization
4. •Envoy Documentation - Environment configuration
5. •Gleam FAQ - Production - Production readiness

Deployment Targets

Fly.io (Official Guide)

Complete step-by-step guide: Gleam on Fly.io

Key points:

• •Listen on 0.0.0.0 (use mist.bind("0.0.0.0"))
• •Use multi-stage Docker builds
• •Configure fly.toml
• •Deploy with flyctl deploy

Other Platforms

Gleam apps can deploy to any platform supporting:

• •Docker containers: AWS ECS, Google Cloud Run, Azure Container Instances
• •Erlang releases: Any server with Erlang/OTP installed
• •JavaScript: Node.js hosting (Vercel, Netlify, etc.)

Building for Production

Erlang Target

Build optimized Erlang release:

gleam export erlang-shipment

This creates a standalone release in build/erlang-shipment/.

See: gleam.run/writing-gleam

JavaScript Target

Build JavaScript bundle:

gleam build --target javascript

Output in build/dev/javascript/.

Docker Configuration

Multi-Stage Build Pattern

Example from Fly.io guide:

# Stage 1: Build
FROM ghcr.io/gleam-lang/gleam:v1.10.0-erlang-alpine AS builder
WORKDIR /app
COPY . .
RUN gleam export erlang-shipment

# Stage 2: Runtime
FROM erlang:27.1.1.0-alpine
WORKDIR /app
COPY --from=builder /app/build/erlang-shipment /app
RUN adduser -D webapp
USER webapp
ENTRYPOINT ["/app/entrypoint.sh"]
CMD ["run"]

See complete example: Fly.io Deployment Guide

Docker Optimization

Best practices:

• •Use multi-stage builds (smaller images)
• •Run as non-root user (security)
• •Use .dockerignore (faster builds)
• •Layer caching (faster rebuilds)

Configuration Management

Environment Variables

Use Envoy for environment configuration:

import envoy

pub fn main() {
  let assert Ok(port) = envoy.get("PORT")
    |> result.then(int.parse)

  let assert Ok(db_url) = envoy.get("DATABASE_URL")

  start_server(port, db_url)
}

See: Envoy Documentation

Configuration Files

For complex configuration, consider:

• •TOML: Tom parser
• •JSON: gleam_json
• •Environment-specific configs

Security Considerations

Secrets Management

• •Never commit secrets to version control
• •Use platform secret managers (Fly.io Secrets, AWS Secrets Manager, etc.)
• •Inject secrets as environment variables
• •Rotate secrets regularly

Network Security

• •Use HTTPS in production (platforms usually provide this)
• •Configure CORS appropriately
• •Validate all inputs
• •Rate limit API endpoints

See: Wisp Security

Database Deployment

Connection Pooling

Use connection pools for databases:

• •Pog has built-in pooling
• •Configure pool size based on load

Migrations

Patterns for database migrations:

1. •Run migrations in startup script
2. •Use dedicated migration tool (e.g., cigogne for Postgres)
3. •Manual migration management

See: Cigogne - Postgres migrations in Gleam

Monitoring and Logging

Logging

Production logging strategies:

• •Use structured logging: Palabres
• •Log to stdout/stderr (captured by platforms)
• •Use appropriate log levels
• •Include request IDs for tracing

Monitoring

BEAM/OTP monitoring:

• •Built-in Erlang tools (:observer, :recon)
• •Platform monitoring (Fly.io metrics, CloudWatch, etc.)
• •Custom telemetry
• •Health check endpoints

Health Checks

Implement health check endpoints:

fn handle_request(req: Request) -> Response {
  case wisp.path_segments(req) {
    ["health"] -> wisp.response(200)
      |> wisp.set_body(wisp.Text("OK"))
    // other routes...
  }
}

Performance Optimization

Erlang Release Optimization

• •Use gleam export erlang-shipment for optimized builds
• •Configure BEAM flags in entrypoint
• •Tune garbage collection settings

Caching Strategies

• •ETS tables (Erlang)
• •External caching (Redis, Memcached)
• •CDN for static assets
• •HTTP caching headers

Load Balancing

• •Platform load balancing (Fly.io, AWS ALB)
• •Multiple instances for scaling
• •Health checks for routing

CI/CD Pipelines

GitHub Actions Example

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Gleam
        uses: erlef/setup-beam@v1
        with:
          gleam-version: "1.10.0"
      - name: Run tests
        run: gleam test
      - name: Deploy to Fly.io
        uses: superfly/flyctl-actions@master
        with:
          args: "deploy"
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

Platform-Specific Guides

Fly.io

Official Guide

AWS

• •ECS with Docker
• •Lambda (JavaScript target)
• •Elastic Beanstalk (Docker)

Google Cloud

• •Cloud Run (Docker)
• •GKE (Kubernetes)
• •App Engine (JavaScript)

Azure

• •Container Instances (Docker)
• •AKS (Kubernetes)
• •App Service (Docker)

Vercel/Netlify (JavaScript Target)

• •Build JavaScript target
• •Configure build commands
• •Deploy via CLI or Git integration

Troubleshooting

Common Issues

Port binding: Ensure listening on 0.0.0.0, not localhost

Environment variables: Verify all required vars are set in platform

File permissions: Run as non-root user, check file ownership

Build failures: Check Dockerfile layer caching, dependencies

Debugging Production

• •Check platform logs
• •Use remote Erlang console (if available)
• •Enable debug logging temporarily
• •Monitor resource usage

Rollback Strategies

• •Keep previous release artifacts
• •Use platform rollback features (Fly.io, AWS, etc.)
• •Database migration rollback plan
• •Feature flags for gradual rollout

Scaling Considerations

Vertical Scaling

• •Increase instance size
• •Adjust BEAM settings
• •Optimize resource usage

Horizontal Scaling

• •Add more instances
• •Configure load balancing
• •Ensure stateless design or shared state storage

Database Scaling

• •Read replicas
• •Connection pooling
• •Query optimization
• •Caching layer

Zero-Downtime Deployment

Strategies:

• •Blue-green deployment
• •Rolling updates
• •Feature flags
• •Health check integration

Remember: Gleam compiles to mature, battle-tested runtimes (BEAM, JavaScript). Focus on platform-specific deployment concerns.

See: Gleam FAQ - Production