@deftai/directive-content 0.55.0

package/deployments/fly-io/via-dockerfile.md

@@ -0,0 +1,648 @@
+# Deploy via Dockerfile
+
+Deploy any containerized application to Fly.io using custom Dockerfiles. Full control over build process, dependencies, and runtime environment.
+
+## Overview
+
+Fly.io runs Docker containers, giving you complete flexibility:
+- **Custom Images**: Use any base image
+- **Multi-Stage Builds**: Optimize image size
+- **Build Arguments**: Dynamic build configuration
+- **Layer Caching**: Fast rebuilds
+- **Private Registries**: Pull from your own registry
+
+## Prerequisites
+
+- Application with a Dockerfile
+- flyctl CLI installed
+- Docker knowledge (optional for remote builds)
+
+## Quick Start
+
+### 1. Create a Dockerfile
+
+```dockerfile
+# Basic Node.js example
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --production
+
+# Copy application code
+COPY . .
+
+# Expose port
+EXPOSE 8080
+
+# Start application
+CMD ["node", "server.js"]
+```
+
+### 2. Deploy
+
+```bash
+# Deploy using Dockerfile
+fly deploy
+
+# Or specify Dockerfile explicitly
+fly deploy --dockerfile Dockerfile
+```
+
+## Dockerfile Best Practices
+
+### Multi-Stage Build
+
+```dockerfile
+# Build stage
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Copy only necessary files from builder
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY package.json ./
+
+EXPOSE 8080
+
+# Run as non-root user
+USER node
+
+CMD ["node", "dist/server.js"]
+```
+
+### Layer Caching Optimization
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies first (cached layer)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code last (changes frequently)
+COPY . .
+
+CMD ["python", "app.py"]
+```
+
+### Minimal Base Images
+
+```dockerfile
+# Use distroless for security
+FROM gcr.io/distroless/nodejs18-debian11
+
+WORKDIR /app
+
+COPY --chown=nonroot:nonroot package*.json ./
+COPY --chown=nonroot:nonroot dist ./dist
+COPY --chown=nonroot:nonroot node_modules ./node_modules
+
+EXPOSE 8080
+
+USER nonroot
+
+CMD ["dist/server.js"]
+```
+
+## Language-Specific Examples
+
+### Node.js / TypeScript
+
+```dockerfile
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+
+# Install dependencies
+COPY package*.json ./
+RUN npm ci
+
+# Build TypeScript
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+
+# Production image
+FROM node:18-alpine
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+COPY package*.json ./
+RUN npm ci --production
+
+COPY --from=builder /app/dist ./dist
+
+EXPOSE 8080
+
+USER node
+
+CMD ["node", "dist/index.js"]
+```
+
+### Python / Django
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    postgresql-client \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application
+COPY . .
+
+# Collect static files
+RUN python manage.py collectstatic --noinput
+
+EXPOSE 8000
+
+CMD ["gunicorn", "--bind", ":8000", "--workers", "2", "myproject.wsgi:application"]
+```
+
+### Go
+
+```dockerfile
+# Build stage
+FROM golang:1.21-alpine AS builder
+
+WORKDIR /app
+
+# Copy go mod files
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source
+COPY . .
+
+# Build binary
+RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main .
+
+# Production stage
+FROM alpine:latest
+
+RUN apk --no-cache add ca-certificates
+
+WORKDIR /root/
+
+COPY --from=builder /app/main .
+
+EXPOSE 8080
+
+CMD ["./main"]
+```
+
+### Ruby / Rails
+
+```dockerfile
+FROM ruby:3.2-slim
+
+WORKDIR /app
+
+# Install dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    libpq-dev \
+    nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install gems
+COPY Gemfile Gemfile.lock ./
+RUN bundle install --without development test
+
+# Copy application
+COPY . .
+
+# Precompile assets
+RUN RAILS_ENV=production bundle exec rails assets:precompile
+
+EXPOSE 3000
+
+CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]
+```
+
+### PHP / Laravel
+
+```dockerfile
+FROM php:8.2-fpm-alpine
+
+WORKDIR /var/www/html
+
+# Install dependencies
+RUN apk add --no-cache \
+    nginx \
+    postgresql-dev \
+    && docker-php-ext-install pdo pdo_pgsql
+
+# Install Composer
+COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
+
+# Install PHP dependencies
+COPY composer.json composer.lock ./
+RUN composer install --no-dev --optimize-autoloader
+
+# Copy application
+COPY . .
+
+# Set permissions
+RUN chown -R www-data:www-data /var/www/html
+
+EXPOSE 8080
+
+CMD ["php-fpm"]
+```
+
+## Advanced Dockerfile Techniques
+
+### Build Arguments
+
+```dockerfile
+ARG NODE_VERSION=18
+FROM node:${NODE_VERSION}-alpine
+
+ARG BUILD_ENV=production
+ARG API_URL
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --production=${BUILD_ENV}
+
+COPY . .
+
+# Use build arg in build
+RUN echo "API_URL=${API_URL}" > .env
+
+EXPOSE 8080
+
+CMD ["node", "server.js"]
+```
+
+Deploy with build args:
+```bash
+fly deploy --build-arg NODE_VERSION=20 --build-arg API_URL=https://api.example.com
+```
+
+### Health Check
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY . .
+
+RUN npm ci --production
+
+EXPOSE 8080
+
+# Add healthcheck
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node healthcheck.js
+
+CMD ["node", "server.js"]
+```
+
+### Multi-Platform Builds
+
+```dockerfile
+# Supports both amd64 and arm64
+FROM --platform=$BUILDPLATFORM node:18-alpine AS builder
+
+ARG TARGETPLATFORM
+ARG BUILDPLATFORM
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+
+EXPOSE 8080
+
+CMD ["node", "dist/server.js"]
+```
+
+### Caching Node Modules
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Copy package files first
+COPY package*.json ./
+
+# This layer will be cached unless package.json changes
+RUN npm ci --production
+
+# Copy rest of application
+COPY . .
+
+EXPOSE 8080
+
+CMD ["node", "server.js"]
+```
+
+## fly.toml Configuration
+
+### Specify Dockerfile
+
+```toml
+app = "my-app"
+primary_region = "iad"
+
+[build]
+  dockerfile = "Dockerfile"
+  ignorefile = ".dockerignore"
+  
+  # Build arguments
+  [build.args]
+    NODE_ENV = "production"
+    API_VERSION = "v2"
+
+[[services]]
+  internal_port = 8080
+  protocol = "tcp"
+  
+  [[services.ports]]
+    handlers = ["http"]
+    port = 80
+  
+  [[services.ports]]
+    handlers = ["tls", "http"]
+    port = 443
+```
+
+### Use Different Dockerfiles
+
+```toml
+# fly.production.toml
+[build]
+  dockerfile = "Dockerfile.production"
+
+# fly.staging.toml  
+[build]
+  dockerfile = "Dockerfile.staging"
+```
+
+Deploy:
+```bash
+fly deploy --config fly.production.toml
+fly deploy --config fly.staging.toml
+```
+
+## .dockerignore
+
+Create `.dockerignore` to exclude unnecessary files:
+
+```dockerignore
+# Version control
+.git
+.gitignore
+
+# Dependencies
+node_modules
+vendor
+
+# Build artifacts
+dist
+build
+*.log
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode
+.idea
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Documentation
+*.md
+docs/
+
+# Tests
+tests/
+*.test.js
+coverage/
+
+# CI/CD
+.github
+.gitlab-ci.yml
+```
+
+## Build Optimization
+
+### Remote Builds (Recommended)
+
+```bash
+# Build on Fly's infrastructure (no local Docker needed)
+fly deploy --remote-only
+
+# Faster, uses Fly's build cache
+```
+
+### Local Builds
+
+```bash
+# Build locally with Docker
+fly deploy --local-only
+
+# Useful for testing Dockerfile changes
+```
+
+### Build with Cache
+
+```bash
+# Use build cache
+fly deploy --remote-only
+
+# Clear cache and rebuild
+fly deploy --remote-only --no-cache
+```
+
+## Deploying Pre-Built Images
+
+### From Docker Hub
+
+```bash
+fly deploy --image nginx:latest
+```
+
+### From Private Registry
+
+```toml
+# fly.toml
+[build]
+  image = "registry.example.com/my-app:v1.2.3"
+```
+
+```bash
+# Deploy
+fly deploy
+```
+
+### With Registry Authentication
+
+```bash
+# Set registry credentials
+fly secrets set DOCKER_REGISTRY_TOKEN=your-token
+
+# Deploy from private registry
+fly deploy --image registry.example.com/my-app:latest
+```
+
+## Debugging Docker Builds
+
+### Build Locally for Testing
+
+```bash
+# Build Docker image locally
+docker build -t my-app .
+
+# Test locally
+docker run -p 8080:8080 my-app
+
+# Then deploy to Fly
+fly deploy --local-only
+```
+
+### View Build Logs
+
+```bash
+# Deploy with verbose output
+fly deploy --verbose
+
+# View build logs
+fly logs --timestamps
+```
+
+### SSH into Running Container
+
+```bash
+# Access running container
+fly ssh console
+
+# Check environment
+fly ssh console -C "env"
+
+# Inspect filesystem
+fly ssh console -C "ls -la"
+```
+
+## Common Issues & Solutions
+
+### Large Image Size
+
+```dockerfile
+# Before: 1GB+
+FROM node:18
+COPY . .
+RUN npm install
+
+# After: ~100MB
+FROM node:18-alpine AS builder
+COPY package*.json ./
+RUN npm ci --production
+COPY . .
+
+FROM node:18-alpine
+COPY --from=builder /app ./
+CMD ["node", "index.js"]
+```
+
+### Slow Builds
+
+```dockerfile
+# Order matters! Put stable layers first
+
+# ❌ Bad: Code changes rebuild dependencies
+FROM node:18-alpine
+COPY . .
+RUN npm install
+
+# ✅ Good: Dependencies cached
+FROM node:18-alpine
+COPY package*.json ./
+RUN npm ci
+COPY . .
+```
+
+### Permission Errors
+
+```dockerfile
+# Run as non-root user
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Change ownership
+COPY --chown=node:node . .
+
+# Switch to node user
+USER node
+
+CMD ["node", "server.js"]
+```
+
+## Best Practices Summary
+
+1. **Use Multi-Stage Builds**: Reduce final image size
+2. **Order Layers Wisely**: Put changing content last
+3. **Use Alpine Images**: Smaller, faster deployments
+4. **Run as Non-Root**: Better security
+5. **Include .dockerignore**: Faster builds, smaller context
+6. **Use Build Cache**: Leverage layer caching
+7. **Health Checks**: Add HEALTHCHECK instruction
+8. **Environment Variables**: Use fly secrets, not hardcoded in Dockerfile
+9. **Remote Builds**: Use `--remote-only` for Fly's build cache
+10. **Pin Versions**: Specify exact versions for reproducibility
+
+## References
+
+- [Fly.io Docker Deployment](https://fly.io/docs/languages-and-frameworks/dockerfile/)
+- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)
+- [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/)
+- [Dockerfile Reference](https://docs.docker.com/engine/reference/builder/)