devops-kit

Unified DevOps toolkit — Docker (optimization, multi-stage, compose, security), Kubernetes (manifests, Helm, scaling, service mesh), container orchestration beyond k8s (Swarm, Nomad, ECS), Terraform IaC, nginx (reverse proxy, load balancing, SSL/TLS, caching), Linux admin (systemd, networking, hardening), DNS configuration, multi-environment management (staging/preview/prod), CI/CD pipeline patterns (matrix builds, caching, deployment gates, rollback), GitHub Actions (reusable workflows, composite actions), general CI/CD with GitLab, shell scripting. Keeps cloud-specific skills (aws/cloudflare/vercel) separate.

Jump to install

Repository: InugamiDev/ultrathink-oss
Last source activity: April 13, 2026 at 15:28
Detected SKILL.md language: English
Stars: 43
Forks: 10

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/InugamiDev/ultrathink-oss --skill devops-kit

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

SKILL.md

Source instructions · Read-only preview

name	devops-kit
description	Unified DevOps toolkit — Docker (optimization, multi-stage, compose, security), Kubernetes (manifests, Helm, scaling, service mesh), container orchestration beyond k8s (Swarm, Nomad, ECS), Terraform IaC, nginx (reverse proxy, load balancing, SSL/TLS, caching), Linux admin (systemd, networking, hardening), DNS configuration, multi-environment management (staging/preview/prod), CI/CD pipeline patterns (matrix builds, caching, deployment gates, rollback), GitHub Actions (reusable workflows, composite actions), general CI/CD with GitLab, shell scripting. Keeps cloud-specific skills (aws/cloudflare/vercel) separate.
layer	domain
category	devops
triggers	["Makefile","actions yaml","automate this","bash script","cd pipeline","centos","ci caching","ci pipeline","ci workflow","ci/cd","cicd","cluster","cname","container","container image","container networking","container orchestration","continuous deployment","continuous integration","cron job","debian","debug this script","deployment gate","deployment manifest","dns","dns propagation","dns record","docker","docker build","docker compose","docker swarm","dockerfile","domain setup","ecs","env management","environment promotion","firewall","gh action","github actions","github actions workflow","github workflow","gitlab ci","hcl","helm","iac","infrastructure as code","ingress","iptables","k8s","kubectl","kubernetes","linux","load balancer","matrix build","multi environment","multi-stage build","nginx","nginx config","nomad","pipeline","pipeline optimization","pod","preview environment","proxy pass","reverse proxy","server admin","server setup","service discovery","shell script","ssh","ssl certificate","ssl termination","staging environment","systemd","terraform","terraform module","terraform plan","tf state","ubuntu","workflow","write a script","zsh script"]

devops-kit

Absorbs

docker
kubernetes
container-orchestration
terraform
nginx
linux-admin
dns
environment-management
ci-cd-patterns
github-actions
cicd
shell-scripting

From `docker`

Dockerfile optimization, multi-stage builds, Docker Compose orchestration, image security, and container best practices

Docker Specialist

Purpose

Produce optimized, secure, and production-ready Docker configurations. This skill covers Dockerfile authoring, multi-stage build strategies, Docker Compose orchestration, image security hardening, and container runtime best practices.

Key Patterns

Multi-Stage Build Template

# Stage 1: Dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

# Stage 2: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN pnpm build

# Stage 3: Production
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser

COPY --from=builder --chown=appuser:appgroup /app/.next/standalone ./
COPY --from=builder --chown=appuser:appgroup /app/.next/static ./.next/static
COPY --from=builder --chown=appuser:appgroup /app/public ./public

USER appuser
EXPOSE 3000
CMD ["node", "server.js"]

Docker Compose Production Pattern

services:
  app:
    
       
       
       
     
     
    
       
    
      
         
    
       [, , , , , ]
       
       
       
       
    
      
        
           
           

  
     
     
    
       
    
       
       
       
    
       [, ]

This SKILL.md is very large, so SkillsMP previews the first section here. View on GitHub

name	devops-kit
description	Unified DevOps toolkit — Docker (optimization, multi-stage, compose, security), Kubernetes (manifests, Helm, scaling, service mesh), container orchestration beyond k8s (Swarm, Nomad, ECS), Terraform IaC, nginx (reverse proxy, load balancing, SSL/TLS, caching), Linux admin (systemd, networking, hardening), DNS configuration, multi-environment management (staging/preview/prod), CI/CD pipeline patterns (matrix builds, caching, deployment gates, rollback), GitHub Actions (reusable workflows, composite actions), general CI/CD with GitLab, shell scripting. Keeps cloud-specific skills (aws/cloudflare/vercel) separate.
layer	domain
category	devops
triggers	["Makefile","actions yaml","automate this","bash script","cd pipeline","centos","ci caching","ci pipeline","ci workflow","ci/cd","cicd","cluster","cname","container","container image","container networking","container orchestration","continuous deployment","continuous integration","cron job","debian","debug this script","deployment gate","deployment manifest","dns","dns propagation","dns record","docker","docker build","docker compose","docker swarm","dockerfile","domain setup","ecs","env management","environment promotion","firewall","gh action","github actions","github actions workflow","github workflow","gitlab ci","hcl","helm","iac","infrastructure as code","ingress","iptables","k8s","kubectl","kubernetes","linux","load balancer","matrix build","multi environment","multi-stage build","nginx","nginx config","nomad","pipeline","pipeline optimization","pod","preview environment","proxy pass","reverse proxy","server admin","server setup","service discovery","shell script","ssh","ssl certificate","ssl termination","staging environment","systemd","terraform","terraform module","terraform plan","tf state","ubuntu","workflow","write a script","zsh script"]

devops-kit

Absorbs

docker
kubernetes
container-orchestration
terraform
nginx
linux-admin
dns
environment-management
ci-cd-patterns
github-actions
cicd
shell-scripting

From `docker`

Dockerfile optimization, multi-stage builds, Docker Compose orchestration, image security, and container best practices

Docker Specialist

Purpose

Key Patterns

Multi-Stage Build Template

# Stage 1: Dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

# Stage 2: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN pnpm build

# Stage 3: Production
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser

COPY --from=builder --chown=appuser:appgroup /app/.next/standalone ./
COPY --from=builder --chown=appuser:appgroup /app/.next/static ./.next/static
COPY --from=builder --chown=appuser:appgroup /app/public ./public

USER appuser
EXPOSE 3000
CMD ["node", "server.js"]

Docker Compose Production Pattern

services:
  app:
    
       
       
       
     
     
    
       
    
      
         
    
       [, , , , , ]
       
       
       
       
    
      
        
           
           

  
     
     
    
       
    
       
       
       
    
       [, ]

This SKILL.md is very large, so SkillsMP previews the first section here. View on GitHub

Pitfall	Fix
`npm install` invalidated on every code change	Copy `package.json` + lockfile first, install, then copy source
Image bloat from dev dependencies	Use `--omit=dev` or `--production` flag in final stage
Running as root	Add `USER` instruction with a non-root user
Secrets baked into layers	Use `--secret` mount in BuildKit or runtime env vars
No `.dockerignore`	Create one excluding `node_modules`, `.git`, `.env`, `dist`
Using `latest` tag	Pin versions: `node:20.11-alpine`
Single-stage builds	Use multi-stage to separate build from runtime

node_modules
.git
.gitignore
.env*
*.md
dist
.next
coverage
.turbo

# syntax=docker/dockerfile:1
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) \
    npm install --registry https://registry.npmjs.org/

docker build --secret id=npm_token,src=.npm_token .

services:
  app:
    build:
      context: .
      target: deps
    volumes:
      - .:/app
      - /app/node_modules
    command: pnpm dev
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development

# Follow logs with timestamps
docker compose logs -f --timestamps app

# View last 100 lines
docker compose logs --tail=100 app

# Resource usage
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
  namespace: production
  labels:
    app.kubernetes.io/name: app
    app.kubernetes.io/version: "1.0.0"
    app.kubernetes.io/managed-by: helm
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app.kubernetes.io/name: app
  template:
    metadata:
      labels:
        app.kubernetes.io/name: app
    spec:
      serviceAccountName: app-sa
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        fsGroup: 1001
      containers:
        - name: app
          image: registry.example.com/app:1.0.0
          ports:
            - containerPort: 3000
              protocol: TCP
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"
          livenessProbe:
            httpGet:
              path: /api/health
              port: 3000
            initialDelaySeconds: 30
            periodSeconds: 10
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /api/ready
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 5
          env:
            - name: NODE_ENV
              value: "production"
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: app-secrets
                  key: database-url
          volumeMounts:
            - name: tmp
              mountPath: /tmp
      volumes:
        - name: tmp
          emptyDir: {}
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              app.kubernetes.io/name: app

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: app-hpa
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: app
  minReplicas: 3
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 60
      policies:
        - type: Pods
          value: 2
          periodSeconds: 60
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 10
          periodSeconds: 60

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  namespace: production
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/rate-limit: "100"
    nginx.ingress.kubernetes.io/rate-limit-window: "1m"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - app.example.com
      secretName: app-tls
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: app-service
                port:
                  number: 80

chart/
  Chart.yaml
  values.yaml
  values-staging.yaml
  values-production.yaml
  templates/
    _helpers.tpl
    deployment.yaml
    service.yaml
    ingress.yaml
    hpa.yaml
    configmap.yaml
    secret.yaml
    serviceaccount.yaml
    pdb.yaml

Pitfall	Fix
No resource limits	Always set requests and limits
Liveness probe on app startup path	Use `startupProbe` for slow-starting apps
Same endpoint for liveness and readiness	Liveness: "am I alive?"; readiness: "can I serve traffic?"
No PDB	Add PDB to prevent full unavailability during upgrades
Hardcoded image tags	Use SHA digests or versioned tags, never `latest`
Secrets in ConfigMap	Use Secrets resource or External Secrets
Single-zone deployment	Use topology spread constraints

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: app-pdb
spec:
  minAvailable: "50%"
  selector:
    matchLabels:
      app.kubernetes.io/name: app

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: app-netpol
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: app
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              name: ingress-nginx
      ports:
        - protocol: TCP
          port: 3000

# Rolling restart
kubectl rollout restart deployment/app -n production

# Check rollout status
kubectl rollout status deployment/app -n production

# View pod resource usage
kubectl top pods -n production --sort-by=memory

# Debug failing pod
kubectl describe pod <pod-name> -n production
kubectl logs <pod-name> -n production --previous

# Port forward for debugging
kubectl port-forward svc/app-service 3000:80 -n production

Feature	Docker Swarm	Nomad	ECS/Fargate	Kubernetes
Complexity	Low	Medium	Medium	High
Learning curve	Shallow	Moderate	Moderate (AWS-specific)	Steep
Multi-cloud	Yes	Yes	No (AWS only)	Yes
Non-container workloads	No	Yes (VMs, Java, batch)	No	Via CRDs
Built-in service mesh	No	Consul Connect	App Mesh	Istio/Linkerd
Auto-scaling	Limited	Autoscaler plugin	Native	HPA/VPA/KEDA
Best for	Small teams, simple apps	Mixed workloads, HashiStack	AWS-native teams	Large-scale, multi-tenant

# docker-compose.yml (Swarm mode)
version: '3.8'

services:
  api:
    image: myapp/api:latest
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
        order: start-first    # Blue-green within rolling update
        failure_action: rollback
      rollback_config:
        parallelism: 0        # Rollback all at once
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 30s
    networks:
      - app-network

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    deploy:
      mode: global           # One per node
      placement:
        constraints:
          - node.role == manager
    networks:
      - app-network

networks:
  app-network:
    driver: overlay
    attachable: true

# Deploy the stack
docker stack deploy -c docker-compose.yml myapp

# Scale a service
docker service scale myapp_api=5

# Rolling update
docker service update --image myapp/api:v2.0 myapp_api

# View service status
docker service ps myapp_api

# api.nomad.hcl
job "api" {
  datacenters = ["dc1"]
  type        = "service"

  update {
    max_parallel     = 1
    min_healthy_time = "10s"
    healthy_deadline = "3m"
    auto_revert      = true
    canary           = 1        # Canary deployment
  }

  group "api" {
    count = 3

    network {
      port "http" {
        to = 3000
      }
    }

    service {
      name = "api"
      port = "http"
      tags = ["urlprefix-/api"]  # For Fabio load balancer

      check {
        type     = "http"
        path     = "/health"
        interval = "10s"
        timeout  = "3s"
      }

      # Consul Connect sidecar proxy
      connect {
        sidecar_service {
          proxy {
            upstreams {
              destination_name = "postgres"
              local_bind_port  = 5432
            }
          }
        }
      }
    }

    task "api" {
      driver = "docker"

      config {
        image = "myapp/api:${NOMAD_META_version}"
        ports = ["http"]
      }

      env {
        NODE_ENV     = "production"
        DATABASE_URL = "postgresql://localhost:5432/mydb"
      }

      resources {
        cpu    = 500   # MHz
        memory = 512   # MB
      }

      # Pull secrets from Vault
      vault {
        policies = ["api-policy"]
      }

      template {
        data = <<EOF
{{ with secret "secret/data/api" }}
DATABASE_PASSWORD={{ .Data.data.password }}
{{ end }}
EOF
        destination = "secrets/env"
        env         = true
      }
    }
  }
}

# Submit the job
nomad job run api.nomad.hcl

# Promote canary
nomad deployment promote <deployment-id>

# Scale
nomad job scale api 5

# Check allocations
nomad job status api

# ecs.tf
resource "aws_ecs_cluster" "main" {
  name = "production"

  setting {
    name  = "containerInsights"
    value = "enabled"
  }
}

resource "aws_ecs_task_definition" "api" {
  family                   = "api"
  requires_compatibilities = ["FARGATE"]
  network_mode             = "awsvpc"
  cpu                      = 512
  memory                   = 1024
  execution_role_arn       = aws_iam_role.ecs_execution.arn
  task_role_arn            = aws_iam_role.ecs_task.arn

  container_definitions = jsonencode([
    {
      name  = "api"
      image = "${aws_ecr_repository.api.repository_url}:latest"
      portMappings = [
        {
          containerPort = 3000
          protocol      = "tcp"
        }
      ]
      healthCheck = {
        command     = ["CMD-SHELL", "curl -f http://localhost:3000/health || exit 1"]
        interval    = 15
        timeout     = 5
        retries     = 3
        startPeriod = 30
      }
      logConfiguration = {
        logDriver = "awslogs"
        options = {
          "awslogs-group"         = "/ecs/api"
          "awslogs-region"        = "us-east-1"
          "awslogs-stream-prefix" = "ecs"
        }
      }
      secrets = [
        {
          name      = "DATABASE_URL"
          valueFrom = aws_secretsmanager_secret.db_url.arn
        }
      ]
    }
  ])
}

resource "aws_ecs_service" "api" {
  name            = "api"
  cluster         = aws_ecs_cluster.main.id
  task_definition = aws_ecs_task_definition.api.arn
  desired_count   = 3
  launch_type     = "FARGATE"

  deployment_circuit_breaker {
    enable   = true
    rollback = true
  }

  deployment_configuration {
    maximum_percent         = 200
    minimum_healthy_percent = 100
  }

  network_configuration {
    subnets         = var.private_subnets
    security_groups = [aws_security_group.api.id]
  }

  load_balancer {
    target_group_arn = aws_lb_target_group.api.arn
    container_name   = "api"
    container_port   = 3000
  }

  service_registries {
    registry_arn = aws_service_discovery_service.api.arn
  }
}

# Auto-scaling
resource "aws_appautoscaling_target" "api" {
  max_capacity       = 10
  min_capacity       = 3
  resource_id        = "service/${aws_ecs_cluster.main.name}/${aws_ecs_service.api.name}"
  scalable_dimension = "ecs:service:DesiredCount"
  service_namespace  = "ecs"
}

resource "aws_appautoscaling_policy" "api_cpu" {
  name               = "api-cpu-scaling"
  policy_type        = "TargetTrackingScaling"
  resource_id        = aws_appautoscaling_target.api.resource_id
  scalable_dimension = aws_appautoscaling_target.api.scalable_dimension
  service_namespace  = aws_appautoscaling_target.api.service_namespace

  target_tracking_scaling_policy_configuration {
    target_value       = 70.0
    predefined_metric_specification {
      predefined_metric_type = "ECSServiceAverageCPUUtilization"
    }
    scale_in_cooldown  = 300
    scale_out_cooldown = 60
  }
}

# Docker Swarm: Built-in DNS resolution
# Services resolve each other by name within overlay network
services:
  api:
    environment:
      - REDIS_HOST=redis    # Resolves via Docker DNS
      - DB_HOST=postgres
  redis:
    image: redis:7-alpine
  postgres:
    image: postgres:16-alpine

# Nomad + Consul: Service mesh with transparent proxy
service {
  name = "api"
  connect {
    sidecar_service {
      proxy {
        upstreams {
          destination_name = "redis"
          local_bind_port  = 6379
        }
        upstreams {
          destination_name = "postgres"
          local_bind_port  = 5432
        }
      }
    }
  }
}

// Health check endpoint — return dependency status
import { Router } from 'express';

const health = Router();

health.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok' });
});

health.get('/health/ready', async (req, res) => {
  const checks = {
    database: await checkDatabase(),
    redis: await checkRedis(),
    external_api: await checkExternalApi(),
  };

  const allHealthy = Object.values(checks).every((c) => c.healthy);
  res.status(allHealthy ? 200 : 503).json({
    status: allHealthy ? 'ready' : 'degraded',
    checks,
    uptime: process.uptime(),
  });
});

async function checkDatabase(): Promise<{ healthy: boolean; latencyMs: number }> {
  const start = Date.now();
  try {
    await db.query('SELECT 1');
    return { healthy: true, latencyMs: Date.now() - start };
  } catch {
    return { healthy: false, latencyMs: Date.now() - start };
  }
}

Pitfall	Problem	Fix
No health checks	Orchestrator routes traffic to broken containers	Define HTTP health checks with appropriate intervals
No resource limits	One service starves others	Set CPU and memory limits on every container
Hardcoded service addresses	Breaks when containers move	Use DNS-based service discovery
Missing rollback config	Bad deploys require manual intervention	Configure `auto_revert` (Nomad) or `deployment_circuit_breaker` (ECS)
Single replica in production	Zero availability during deploys	Run at least 2 replicas with rolling updates
No graceful shutdown	Requests dropped during redeploy	Handle SIGTERM, drain connections, use `stop_grace_period`

infrastructure/
  environments/
    production/
      main.tf
      variables.tf
      terraform.tfvars
      backend.tf
    staging/
      main.tf
      variables.tf
      terraform.tfvars
      backend.tf
  modules/
    networking/
      main.tf
      variables.tf
      outputs.tf
    compute/
      main.tf
      variables.tf
      outputs.tf
    database/
      main.tf
      variables.tf
      outputs.tf
  global/
    iam/
    dns/

# backend.tf
terraform {
  required_version = ">= 1.7"

  backend "s3" {
    bucket         = "company-terraform-state"
    key            = "production/app/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

# modules/ecs-service/main.tf
resource "aws_ecs_service" "this" {
  name            = var.service_name
  cluster         = var.cluster_id
  task_definition = aws_ecs_task_definition.this.arn
  desired_count   = var.desired_count
  launch_type     = "FARGATE"

  network_configuration {
    subnets          = var.subnet_ids
    security_groups  = [aws_security_group.this.id]
    assign_public_ip = false
  }

  load_balancer {
    target_group_arn = var.target_group_arn
    container_name   = var.container_name
    container_port   = var.container_port
  }

  deployment_circuit_breaker {
    enable   = true
    rollback = true
  }

  lifecycle {
    ignore_changes = [desired_count]
  }

  tags = var.tags
}

# modules/ecs-service/variables.tf
variable "service_name" {
  description = "Name of the ECS service"
  type        = string
}

variable "cluster_id" {
  description = "ECS cluster ID"
  type        = string
}

variable "desired_count" {
  description = "Desired task count"
  type        = number
  default     = 2
}

variable "subnet_ids" {
  description = "Subnet IDs for the service"
  type        = list(string)
}

variable "tags" {
  description = "Resource tags"
  type        = map(string)
  default     = {}
}

# modules/ecs-service/outputs.tf
output "service_id" {
  description = "ECS service ID"
  value       = aws_ecs_service.this.id
}

output "service_name" {
  description = "ECS service name"
  value       = aws_ecs_service.this.name
}

data "terraform_remote_state" "networking" {
  backend = "s3"
  config = {
    bucket = "company-terraform-state"
    key    = "production/networking/terraform.tfstate"
    region = "us-east-1"
  }
}

resource "aws_instance" "app" {
  subnet_id = data.terraform_remote_state.networking.outputs.private_subnet_ids[0]
}

Pitfall	Fix
State drift from manual changes	Use `terraform refresh` or import, enforce IaC-only changes
Circular dependencies	Use `data` sources or refactor module boundaries
Large blast radius	Split into smaller state files per component
Unversioned modules	Tag modules in Git, reference with `?ref=v1.0.0`
Missing locks	Always configure DynamoDB or equivalent lock table
Hardcoded values	Use variables with defaults and `terraform.tfvars` per env
No plan review	Always run `plan` in CI PR check before `apply`

variable "environment" {
  description = "Deployment environment"
  type        = string
  validation {
    condition     = contains(["staging", "production"], var.environment)
    error_message = "Environment must be staging or production."
  }
}

variable "instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t3.medium"
  validation {
    condition     = can(regex("^t3\\.", var.instance_type))
    error_message = "Only t3 instance types are allowed."
  }
}

# .github/workflows/terraform.yml
jobs:
  plan:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/terraform
          aws-region: us-east-1

      - run: terraform init
      - run: terraform validate
      - run: terraform plan -out=tfplan
      - run: terraform show -no-color tfplan > plan.txt

      - uses: actions/github-script@v7
        with:
          script: |
            const plan = require('fs').readFileSync('plan.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## Terraform Plan\n\`\`\`\n${plan.slice(0, 60000)}\n\`\`\``
            });

provider "aws" {
  region = var.aws_region

  default_tags {
    tags = {
      Environment = var.environment
      Project     = var.project_name
      ManagedBy   = "terraform"
      Repository  = "github.com/org/infra"
    }
  }
}

# /etc/nginx/nginx.conf
user nginx;
worker_processes auto;
worker_rlimit_nofile 65535;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 4096;
    multi_accept on;
    use epoll;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # Logging
    log_format json escape=json '{'
        '"time":"$time_iso8601",'
        '"remote_addr":"$remote_addr",'
        '"method":"$request_method",'
        '"uri":"$request_uri",'
        '"status":$status,'
        '"body_bytes_sent":$body_bytes_sent,'
        '"request_time":$request_time,'
        '"upstream_response_time":"$upstream_response_time",'
        '"user_agent":"$http_user_agent"'
    '}';
    access_log /var/log/nginx/access.log json;

    # Performance
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    keepalive_requests 1000;
    types_hash_max_size 2048;

    # Gzip
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_proxied any;
    gzip_comp_level 5;
    gzip_types
        text/plain
        text/css
        application/json
        application/javascript
        text/xml
        application/xml
        image/svg+xml;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Hide Nginx version
    server_tokens off;

    # Rate limiting zones
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;
    limit_conn_zone $binary_remote_addr zone=conn_per_ip:10m;

    include /etc/nginx/conf.d/*.conf;
}

# /etc/nginx/conf.d/app.conf
upstream app_backend {
    least_conn;
    server app1:3000 weight=3;
    server app2:3000 weight=3;
    server app3:3000 weight=3 backup;
    keepalive 32;
}

server {
    listen 80;
    server_name app.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name app.example.com;

    # SSL
    ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    # HSTS
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;

    # Body size
    client_max_body_size 10m;

    # Static assets with long cache
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2|woff|ttf)$ {
        proxy_pass http://app_backend;
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # API with rate limiting
    location /api/ {
        limit_req zone=api burst=20 nodelay;
        limit_conn conn_per_ip 50;

        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";

        proxy_connect_timeout 5s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
    }

    # Login with strict rate limiting
    location /api/auth/login {
        limit_req zone=login burst=3 nodelay;
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Default proxy
    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # Health check endpoint (no logging)
    location /health {
        access_log off;
        proxy_pass http://app_backend;
    }

    # Deny hidden files
    location ~ /\. {
        deny all;
        access_log off;
        log_not_found off;
    }
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    location /ws/ {
        proxy_pass http://websocket_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=app_cache:10m
    max_size=1g inactive=60m use_temp_path=off;

server {
    location /api/public/ {
        proxy_cache app_cache;
        proxy_cache_valid 200 10m;
        proxy_cache_valid 404 1m;
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503;
        proxy_cache_lock on;
        proxy_cache_background_update on;
        add_header X-Cache-Status $upstream_cache_status;

        proxy_pass http://app_backend;
    }
}

Pitfall	Fix
Missing `X-Forwarded-For` header	Always set `proxy_set_header X-Forwarded-For`
WebSocket connections dropping	Add `Upgrade` and `Connection` headers
502 Bad Gateway	Check upstream health, increase timeouts
Large uploads failing	Increase `client_max_body_size`
SSL not working	Check certificate chain completeness (fullchain)
Rate limiting too aggressive	Tune `burst` parameter, use `nodelay`
Cache serving stale data	Set appropriate `proxy_cache_valid` durations

# Test config syntax
nginx -t

# Reload without downtime
nginx -s reload

# Check active connections
nginx -V 2>&1 | grep --color=auto -o "with-http_stub_status_module"

FROM nginx:1.27-alpine
COPY nginx.conf /etc/nginx/nginx.conf
COPY conf.d/ /etc/nginx/conf.d/
EXPOSE 80 443
HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget --no-verbose --tries=1 --spider http://localhost/health || exit 1

# Initial certificate
certbot --nginx -d app.example.com

# Auto-renewal cron
0 0 1 * * certbot renew --quiet && nginx -s reload

#!/bin/bash
# server-setup.sh — Run as root on a fresh server

set -euo pipefail

# 1. Update system
apt update && apt upgrade -y

# 2. Create admin user
USERNAME="deploy"
adduser --disabled-password --gecos "" "$USERNAME"
usermod -aG sudo "$USERNAME"
mkdir -p /home/$USERNAME/.ssh
cp /root/.ssh/authorized_keys /home/$USERNAME/.ssh/
chown -R $USERNAME:$USERNAME /home/$USERNAME/.ssh
chmod 700 /home/$USERNAME/.ssh
chmod 600 /home/$USERNAME/.ssh/authorized_keys

# 3. Harden SSH
cat > /etc/ssh/sshd_config.d/hardening.conf <<'SSHEOF'
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
MaxAuthTries 3
ClientAliveInterval 300
ClientAliveCountMax 2
AllowUsers deploy
SSHEOF
systemctl restart sshd

# 4. Firewall (UFW)
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp comment "SSH"
ufw allow 80/tcp comment "HTTP"
ufw allow 443/tcp comment "HTTPS"
ufw --force enable

# 5. Fail2ban
apt install -y fail2ban
cat > /etc/fail2ban/jail.local <<'F2BEOF'
[sshd]
enabled = true
port = 22
filter = sshd
logpath = /var/log/auth.log
maxretry = 3
bantime = 3600
findtime = 600
F2BEOF
systemctl enable --now fail2ban

# 6. Automatic security updates
apt install -y unattended-upgrades
dpkg-reconfigure -plow unattended-upgrades

# 7. Kernel hardening
cat > /etc/sysctl.d/99-security.conf <<'SYSEOF'
net.ipv4.conf.all.rp_filter = 1
net.ipv4.conf.default.rp_filter = 1
net.ipv4.icmp_echo_ignore_broadcasts = 1
net.ipv4.conf.all.accept_redirects = 0
net.ipv4.conf.default.accept_redirects = 0
net.ipv6.conf.all.accept_redirects = 0
net.ipv4.conf.all.send_redirects = 0
net.ipv4.conf.all.accept_source_route = 0
net.ipv4.tcp_syncookies = 1
kernel.randomize_va_space = 2
SYSEOF
sysctl --system

echo "Server hardening complete."

# /etc/systemd/system/myapp.service
[Unit]
Description=My Application
Documentation=https://docs.example.com
After=network.target postgresql.service
Requires=postgresql.service

[Service]
Type=simple
User=appuser
Group=appgroup
WorkingDirectory=/opt/myapp
ExecStart=/usr/bin/node /opt/myapp/server.js
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5
StartLimitBurst=3
StartLimitIntervalSec=60

# Security hardening
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/opt/myapp/data /var/log/myapp
PrivateTmp=yes
PrivateDevices=yes

# Environment
EnvironmentFile=/opt/myapp/.env
Environment=NODE_ENV=production

# Resource limits
LimitNOFILE=65535
MemoryMax=512M
CPUQuota=50%

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=myapp

[Install]
WantedBy=multi-user.target

# Enable and start service
systemctl enable --now myapp

# View status
systemctl status myapp

# View logs
journalctl -u myapp -f --since "1 hour ago"

# Reload configuration
systemctl daemon-reload
systemctl reload myapp

# Restart
systemctl restart myapp

# /etc/sysctl.d/99-performance.conf

# Network performance
net.core.somaxconn = 65535
net.core.netdev_max_backlog = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.tcp_fin_timeout = 15
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_keepalive_time = 300
net.ipv4.tcp_keepalive_intvl = 30
net.ipv4.tcp_keepalive_probes = 5

# Memory
vm.swappiness = 10
vm.dirty_ratio = 15
vm.dirty_background_ratio = 5
vm.overcommit_memory = 1

# File handles
fs.file-max = 2097152
fs.nr_open = 2097152

Pitfall	Fix
Running services as root	Create dedicated service users
No firewall configured	Enable UFW/nftables on setup
SSH password auth enabled	Disable in sshd_config, use keys only
Full disk from logs	Set up logrotate with size limits
No swap on low-memory servers	Create a small swap file as a safety net
Forgetting `daemon-reload`	Always run after editing unit files
Time drift	Install and enable `chrony` or `systemd-timesyncd`

# Check system resources
free -h                          # Memory
df -h                            # Disk
top -bn1 | head -20              # CPU/processes
uptime                           # Load average

# Check network
ss -tlnp                         # Listening ports
ip addr show                     # Network interfaces
curl -I http://localhost:3000    # Test local service
dig +short example.com           # DNS resolution

# Check services
systemctl --failed               # Failed services
journalctl -p err --since today  # Today's errors
dmesg | tail -20                 # Kernel messages

# Check security
last -10                         # Recent logins
who                              # Current sessions
fail2ban-client status sshd      # Ban status

# /etc/logrotate.d/myapp
/var/log/myapp/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    create 0640 appuser appgroup
    postrotate
        systemctl reload myapp > /dev/null 2>&1 || true
    endscript
}

fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab
sysctl vm.swappiness=10
echo 'vm.swappiness=10' >> /etc/sysctl.d/99-performance.conf

#!/bin/bash
set -euo pipefail

BACKUP_DIR="/backups/$(date +%Y-%m-%d)"
mkdir -p "$BACKUP_DIR"

# Database backup
pg_dump -h localhost -U app mydb | gzip > "$BACKUP_DIR/db.sql.gz"

# Application data
tar czf "$BACKUP_DIR/app-data.tar.gz" /opt/myapp/data/

# Retention: keep 30 days
find /backups -maxdepth 1 -type d -mtime +30 -exec rm -rf {} +

echo "Backup complete: $BACKUP_DIR"

Type	Purpose	Example Value	When to Use
A	Maps domain to IPv4	`93.184.216.34`	Pointing to a server with a static IP
AAAA	Maps domain to IPv6	`2606:2800:220:1:...`	IPv6-enabled servers
CNAME	Alias to another domain	`app.vercel.app`	Pointing subdomains to hosting providers
MX	Mail server routing	`10 mx1.emailprovider.com`	Email delivery configuration
TXT	Arbitrary text data	`v=spf1 include:...`	Domain verification, SPF, DKIM, DMARC
NS	Nameserver delegation	`ns1.cloudflare.com`	Delegating DNS to a provider
CAA	Certificate authority authorization	`0 issue "letsencrypt.org"`	Restricting which CAs can issue certs
SRV	Service location	`10 5 5060 sip.example.com`	Service discovery (rare in web apps)

# Root domain (@ or example.com)
Type: A
Name: @
Value: 76.76.21.21
TTL: Auto (or 300)

# www subdomain
Type: CNAME
Name: www
Value: cname.vercel-dns.com
TTL: Auto

# API subdomain (if separate)
Type: CNAME
Name: api
Value: cname.vercel-dns.com
TTL: Auto

# Root domain — Cloudflare proxied (orange cloud)
Type: A
Name: @
Value: <origin server IP>
Proxy: Proxied (orange cloud)
TTL: Auto

# www — CNAME to root, proxied
Type: CNAME
Name: www
Value: example.com
Proxy: Proxied

# API — DNS only (gray cloud) if origin handles TLS
Type: A
Name: api
Value: <api server IP>
Proxy: DNS only (gray cloud)

# Create a DNS record via Cloudflare API
curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "CNAME",
    "name": "app",
    "content": "cname.vercel-dns.com",
    "ttl": 1,
    "proxied": false
  }'

# Terraform — Cloudflare DNS
resource "cloudflare_record" "app" {
  zone_id = var.cloudflare_zone_id
  name    = "app"
  content = "cname.vercel-dns.com"
  type    = "CNAME"
  ttl     = 1      # Auto when proxied
  proxied = false
}

resource "cloudflare_record" "root" {
  zone_id = var.cloudflare_zone_id
  name    = "@"
  content = "76.76.21.21"
  type    = "A"
  proxied = true
}

Off             → No encryption (NEVER use this)
Flexible        → HTTPS client↔Cloudflare, HTTP Cloudflare↔origin (insecure!)
Full            → HTTPS everywhere, but origin cert not validated
Full (Strict)   → HTTPS everywhere, origin cert must be valid ← USE THIS

# Generate an origin certificate via Cloudflare dashboard or API
# Valid for up to 15 years, free, trusted ONLY by Cloudflare

# On origin server (nginx):
ssl_certificate     /etc/ssl/cloudflare-origin.pem;
ssl_certificate_key /etc/ssl/cloudflare-origin-key.pem;

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate (nginx plugin auto-configures)
sudo certbot --nginx -d example.com -d www.example.com

# Auto-renewal (certbot installs a systemd timer by default)
sudo certbot renew --dry-run

# Manual DNS challenge (for wildcard certs)
sudo certbot certonly --manual --preferred-challenges dns \
  -d "*.example.com" -d "example.com"
# Requires adding a TXT record: _acme-challenge.example.com

# Only allow Let's Encrypt and Cloudflare to issue certificates
Type: CAA
Name: @
Value: 0 issue "letsencrypt.org"

Type: CAA
Name: @
Value: 0 issue "comodoca.com"    # Used by Cloudflare Universal SSL

Type: CAA
Name: @
Value: 0 issuewild "letsencrypt.org"

# Report unauthorized issuance attempts
Type: CAA
Name: @
Value: 0 iodef "mailto:security@example.com"

# Allow Google Workspace and Resend to send email on your behalf
Type: TXT
Name: @
Value: v=spf1 include:_spf.google.com include:amazonses.com ~all

# Breakdown:
#   v=spf1           — SPF version
#   include:...      — Authorize these senders
#   ~all             — Soft fail others (use -all for hard fail after testing)

# Provider gives you a CNAME or TXT record
# Example for Resend:
Type: CNAME
Name: resend._domainkey
Value: resend._domainkey.resend.dev

# Example for Google Workspace:
Type: TXT
Name: google._domainkey
Value: v=DKIM1; k=rsa; p=MIIBIjANBgkq... (public key from admin console)

# Start with monitoring mode (p=none), then tighten
Type: TXT
Name: _dmarc
Value: v=DMARC1; p=none; rua=mailto:dmarc@example.com; ruf=mailto:dmarc@example.com; pct=100

# After confirming legitimate mail passes:
Value: v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com; pct=100

# After full confidence:
Value: v=DMARC1; p=reject; rua=mailto:dmarc@example.com; pct=100

Migration Timeline:

Day -7: Lower TTL on ALL records being changed
  Old TTL: 86400 (24h) → New TTL: 300 (5 min)

Day -1: Verify low TTL has propagated
  $ dig example.com +short | head -1
  # Confirm TTL is 300 in responses

Day 0: Update DNS records to new values
  - Change A/CNAME records to new hosting provider
  - Monitor for errors in both old and new infrastructure

Day 0 + 1h: Verify propagation across regions
  $ dig @8.8.8.8 example.com         # Google DNS
  $ dig @1.1.1.1 example.com         # Cloudflare DNS
  $ dig @208.67.222.222 example.com  # OpenDNS

Day +3: Old infrastructure can be decommissioned

Day +7: Raise TTL back to production values
  New TTL: 3600 (1h) or 86400 (24h)

# Check current DNS resolution
dig example.com A +short
dig example.com AAAA +short
dig example.com MX +short
dig example.com TXT +short
dig _dmarc.example.com TXT +short

# Check specific nameserver
dig @ns1.cloudflare.com example.com A

# Full trace (follow delegation chain)
dig example.com +trace

# Check all record types
dig example.com ANY +noall +answer

# Check TTL remaining
dig example.com A | grep -E "^example" | awk '{print $2}'

# Verify CNAME chain
dig www.example.com CNAME +short
# Should return: cname.vercel-dns.com (or similar)

# Check SSL certificate
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null | \
  openssl x509 -noout -dates -subject -issuer

# Check certificate chain
curl -vI https://example.com 2>&1 | grep -E "subject:|issuer:|expire"

# Online propagation checker
# https://www.whatsmydns.net/#A/example.com

# "DNS_PROBE_FINISHED_NXDOMAIN" → Domain does not resolve at all
dig example.com NS +short
# If empty: nameservers not delegated. Check registrar NS records.

# "ERR_SSL_VERSION_OR_CIPHER_MISMATCH" → SSL mode conflict
# Cloudflare Flexible SSL + origin expecting HTTPS = redirect loop
# Fix: Set Cloudflare SSL to "Full (Strict)" and install origin cert

# "Too many redirects" → HTTP↔HTTPS redirect loop
# Cloudflare "Always Use HTTPS" + origin 301 to HTTPS = infinite loop
# Fix: Set Cloudflare SSL to "Full (Strict)", remove origin HTTP→HTTPS redirect

Pitfall	Symptom	Fix
CNAME at zone apex	Registrar rejects the record or resolution fails	Use A record pointing to IP, or use Cloudflare/Route53 ALIAS/ANAME flattening
Cloudflare Flexible SSL	Infinite redirect loop or mixed content	Switch to Full (Strict) and install an origin certificate
High TTL during migration	Users stuck on old IP for hours/days	Lower TTL to 300s at least 48 hours before migration
Missing SPF record	Emails land in spam or get rejected	Add `v=spf1 include:<provider> ~all` TXT record
SPF too many lookups	SPF validation fails (max 10 DNS lookups)	Consolidate includes; use `ip4:`/`ip6:` for known IPs instead of `include:`
Proxying non-HTTP through Cloudflare	SSH, database connections fail	Set DNS-only (gray cloud) for non-HTTP services
Wildcard cert without DNS challenge	Certbot HTTP challenge fails for `*.example.com`	Use `--preferred-challenges dns` with certbot for wildcard certificates
Forgot to update nameservers at registrar	All DNS changes at new provider are ignored	Update NS records at the registrar to point to the new DNS provider's nameservers

local -> preview (per-PR) -> staging -> production

Environment	Purpose	Data	Lifetime	Access
Local	Developer workstation	Seed/mock data	Permanent	Developer only
Preview	Per-PR verification	Seed or staging snapshot	Ephemeral (PR lifecycle)	Team
Staging	Pre-production validation	Sanitized production copy	Permanent	Team + QA
Production	Live users	Real data	Permanent	Public

// env.ts — validated environment config
import { z } from "zod";

const envSchema = z.object({
  NODE_ENV: z.enum(["development", "staging", "production"]),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional(),
  API_BASE_URL: z.string().url(),
  FEATURE_FLAGS_ENDPOINT: z.string().url().optional(),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
  SENTRY_DSN: z.string().optional(),
  // Staging/prod only
  CDN_URL: z.string().url().optional(),
});

export const env = envSchema.parse(process.env);

// Type-safe environment checks
export const isProd = env.NODE_ENV === "production";
export const isStaging = env.NODE_ENV === "staging";
export const isDev = env.NODE_ENV === "development";

.env                  # Shared defaults (committed, no secrets)
.env.local            # Local overrides (gitignored)
.env.staging          # Staging values (committed, no secrets)
.env.production       # Production values (committed, no secrets)

# .env (shared defaults)
NEXT_PUBLIC_APP_NAME="MyApp"
LOG_LEVEL="info"

# .env.staging
NEXT_PUBLIC_API_URL="https://api.staging.myapp.com"
NEXT_PUBLIC_APP_ENV="staging"

# .env.production
NEXT_PUBLIC_API_URL="https://api.myapp.com"
NEXT_PUBLIC_APP_ENV="production"

# Use platform-specific secret stores
# Vercel: vercel env pull
# AWS: AWS Secrets Manager / SSM Parameter Store
# GitHub Actions: repository secrets

# GitHub Actions example
env:
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
  STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}

# Set environment variables per environment
vercel env add DATABASE_URL production
vercel env add DATABASE_URL preview
vercel env add DATABASE_URL development

# Pull env vars for local development
vercel env pull .env.local

# Link to specific environments
vercel --prod          # Deploy to production
vercel                 # Deploy to preview

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Robots-Tag",
          "value": "noindex"
        }
      ],
      "has": [
        {
          "type": "host",
          "value": ".*staging.*"
        }
      ]
    }
  ]
}

name: Promote to Production

on:
  workflow_dispatch:
    inputs:
      staging_sha:
        description: "Staging commit SHA to promote"
        required: true

jobs:
  verify-staging:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ inputs.staging_sha }}

      - name: Verify staging deployment health
        run: |
          STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://staging.myapp.com/api/health)
          if [ "$STATUS" != "200" ]; then
            echo "Staging health check failed with status $STATUS"
            exit 1
          fi

      - name: Run smoke tests against staging
        run: npx playwright test --config=playwright.staging.config.ts

  promote:
    needs: verify-staging
    runs-on: ubuntu-latest
    environment: production  # Requires approval
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ inputs.staging_sha }}

      - name: Deploy to production
        run: vercel --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Post-deploy smoke test
        run: |
          sleep 10
          curl -sf https://myapp.com/api/health || exit 1

# .github/workflows/preview.yml
name: Preview Environment

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  setup-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create Neon branch for PR
        id: neon
        uses: neondatabase/create-branch-action@v5
        with:
          project_id: ${{ secrets.NEON_PROJECT_ID }}
          branch_name: pr-${{ github.event.number }}
          api_key: ${{ secrets.NEON_API_KEY }}

      - name: Set preview DATABASE_URL
        run: |
          vercel env add DATABASE_URL preview \
            --token=${{ secrets.VERCEL_TOKEN }} \
            < <(echo "${{ steps.neon.outputs.db_url }}")

      - name: Deploy preview
        run: vercel --token=${{ secrets.VERCEL_TOKEN }}

# Multi-stage build with environment targets
FROM node:20-alpine AS base
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

FROM base AS build
COPY . .
ARG APP_ENV=production
ENV NEXT_PUBLIC_APP_ENV=$APP_ENV
RUN pnpm build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

# docker-compose.staging.yml
services:
  app:
    build:
      context: .
      args:
        APP_ENV: staging
    env_file: .env.staging
    ports:
      - "3000:3000"

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp_staging
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - staging_db:/var/lib/postgresql/data

volumes:
  staging_db:

// Feature flags for environment-specific behavior (NOT code branches)
const featureFlags = {
  development: {
    enableDebugToolbar: true,
    enableMockPayments: true,
    enableSeedData: true,
  },
  staging: {
    enableDebugToolbar: true,
    enableMockPayments: true,  // Stripe test mode
    enableSeedData: false,
  },
  production: {
    enableDebugToolbar: false,
    enableMockPayments: false,
    enableSeedData: false,
  },
} as const;

export const flags = featureFlags[env.NODE_ENV];

Pitfall	Problem	Fix
Hardcoded URLs in code	Different base URLs per environment break	Use environment variables for all external URLs
Secrets in `.env` committed to git	Credential exposure	Use `.env.local` (gitignored) + platform secret stores
Staging with tiny dataset	Queries fast on staging, slow in production	Use sanitized production data snapshots for staging
No health check endpoint	Cannot verify deployment success	Add `/api/health` that checks DB, Redis, external deps
Preview envs sharing database	Data corruption across PRs	Use database branching (Neon) or isolated test databases
Missing cleanup on PR close	Orphaned preview databases and deployments	Add `pull_request: closed` workflow to tear down resources

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # Fast checks first — fail early
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm type-check

  test:
    runs-on: ubuntu-latest
    needs: lint  # Only test if lint passes
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm test --shard=${{ matrix.shard }}/4
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: test-results-${{ matrix.shard }}
          path: test-results/
          retention-days: 7

  build:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile

      # Cache Next.js build
      - uses: actions/cache@v4
        with:
          path: .next/cache
          key: nextjs-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
          restore-keys: |
            nextjs-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
            nextjs-${{ runner.os }}-

      - run: pnpm build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: .next/
          retention-days: 1

# Test across multiple Node versions and OS
jobs:
  test-matrix:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
        node: [18, 20, 22]
        exclude:
          - os: macos-latest
            node: 18  # Skip older Node on macOS
        include:
          - os: ubuntu-latest
            node: 20
            coverage: true  # Only collect coverage once
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm test ${{ matrix.coverage && '--coverage' || '' }}
      - if: matrix.coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

# pnpm caching (built into setup-node)
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'pnpm'

# Docker layer caching
- uses: docker/build-push-action@v5
  with:
    context: .
    cache-from: type=gha
    cache-to: type=gha,mode=max

# Turbo remote caching
- run: pnpm turbo build --cache-dir=.turbo
- uses: actions/cache@v4
  with:
    path: .turbo
    key: turbo-${{ runner.os }}-${{ github.sha }}
    restore-keys: turbo-${{ runner.os }}-

# Playwright browser caching
- name: Cache Playwright browsers
  uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
- run: pnpm exec playwright install --with-deps chromium

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  build-and-test:
    # ... build and test steps ...

  deploy-staging:
    needs: build-and-test
    runs-on: ubuntu-latest
    environment:
      name: staging
      url: https://staging.example.com
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: build-output
      - run: ./deploy.sh staging

  # Smoke tests on staging
  smoke-test:
    needs: deploy-staging
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm exec playwright test --config=e2e/smoke.config.ts
        env:
          BASE_URL: https://staging.example.com

  # Manual approval gate before production
  deploy-production:
    needs: smoke-test
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: build-output
      - run: ./deploy.sh production
      - name: Notify deployment
        run: |
          curl -X POST "$SLACK_WEBHOOK_URL" \
            -H 'Content-Type: application/json' \
            -d '{"text": "Deployed ${{ github.sha }} to production"}'

# Manual rollback workflow
name: Rollback
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to rollback'
        required: true
        type: choice
        options: [staging, production]
      commit_sha:
        description: 'Commit SHA to rollback to'
        required: true
        type: string

jobs:
  rollback:
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.inputs.commit_sha }}

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: ./deploy.sh ${{ github.event.inputs.environment }}

      - name: Notify rollback
        run: |
          curl -X POST "$SLACK_WEBHOOK_URL" \
            -H 'Content-Type: application/json' \
            -d '{"text": "Rolled back ${{ github.event.inputs.environment }} to ${{ github.event.inputs.commit_sha }}"}'

# Progressive rollout with health checks
jobs:
  canary:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Deploy canary (10% traffic)
        run: ./deploy.sh production --canary --weight=10

      - name: Monitor canary (5 minutes)
        run: |
          for i in {1..10}; do
            ERROR_RATE=$(curl -s "$MONITORING_API/error-rate?deployment=canary")
            if (( $(echo "$ERROR_RATE > 1.0" | bc -l) )); then
              echo "Error rate exceeds threshold. Rolling back."
              ./deploy.sh production --rollback-canary
              exit 1
            fi
            echo "Canary healthy: error rate check $i/10"
            sleep 30
          done

      - name: Promote canary to full
        run: ./deploy.sh production --promote-canary

# Only build/test/deploy what changed
jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      web: ${{ steps.filter.outputs.web }}
      api: ${{ steps.filter.outputs.api }}
      shared: ${{ steps.filter.outputs.shared }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            web:
              - 'apps/web/**'
              - 'packages/ui/**'
              - 'packages/shared/**'
            api:
              - 'apps/api/**'
              - 'packages/shared/**'
            shared:
              - 'packages/shared/**'

  test-web:
    needs: changes
    if: needs.changes.outputs.web == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm turbo test --filter=web...

  test-api:
    needs: changes
    if: needs.changes.outputs.api == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm turbo test --filter=api...

  deploy-web:
    needs: [changes, test-web]
    if: needs.changes.outputs.web == 'true' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: pnpm turbo deploy --filter=web

# Use GitHub environments for secret scoping
jobs:
  deploy:
    environment: production
    env:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
      API_KEY: ${{ secrets.API_KEY }}
    steps:
      # Use OIDC for cloud provider auth (no long-lived secrets)
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/deploy
          aws-region: us-east-1

      # Mask sensitive values in logs
      - run: |
          echo "::add-mask::${{ secrets.API_KEY }}"
          ./deploy.sh

Pitfall	Problem	Fix
No concurrency control	Multiple CI runs for same PR waste resources	Use `concurrency` with `cancel-in-progress: true`
Caching `node_modules`	Cache invalidation issues, platform mismatches	Cache pnpm store, not `node_modules`. Use `setup-node` cache
Secrets in logs	Credentials exposed in CI output	Use `::add-mask::` and never echo secrets
No artifact retention policy	Storage costs grow unbounded	Set `retention-days: 7` on artifacts
Sequential test execution	CI takes 20+ minutes	Shard tests across matrix runners
No smoke tests after deploy	Broken deploys not caught until users report	Run Playwright smoke suite against staging URL
Force-merging past failed checks	Broken code reaches production	Require status checks in branch protection rules
Long-lived feature branches	Merge conflicts and integration pain	Merge main into feature branches daily; use trunk-based development

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm format:check

  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm typecheck

  test:
    runs-on: ubuntu-latest
    needs: [lint, typecheck]
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: testdb
        ports: ['5432:5432']
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm test -- --coverage
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/testdb
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage
          path: coverage/
          retention-days: 7

  build:
    runs-on: ubuntu-latest
    needs: [test]
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - uses: actions/upload-artifact@v4
        with:
          name: build
          path: dist/
          retention-days: 1

jobs:
  test:
    strategy:

devops-kit

Source facts

Install options

Review the source files

More from this repository

devops-kit

Absorbs

From docker

Docker Specialist

Purpose

Key Patterns

Multi-Stage Build Template

Docker Compose Production Pattern

devops-kit

Absorbs

From docker

Docker Specialist

Purpose

Key Patterns

Multi-Stage Build Template

Docker Compose Production Pattern

More from this repository

Layer Caching Optimization

Best Practices

Image Size Reduction

Security Hardening

Health Checks

Networking

Common Pitfalls

Examples

.dockerignore

BuildKit Secret Mount

Development Compose with Hot Reload

Monitoring Container Logs

From kubernetes

Kubernetes Specialist

Purpose

Key Patterns

Production Deployment Manifest

Horizontal Pod Autoscaler

Ingress with TLS

Helm Chart Structure

Best Practices

Resource Management

Reliability

Security

Secrets

Common Pitfalls

Examples

PodDisruptionBudget

NetworkPolicy (Allow Only Ingress)

Useful kubectl Commands

From container-orchestration

Container Orchestration

Purpose

Platform Comparison

Key Patterns

Docker Swarm

HashiCorp Nomad

AWS ECS with Fargate

Container Networking Patterns

Health Check Patterns

Best Practices

Common Pitfalls

From terraform

Terraform Specialist

Purpose

Key Patterns

Project Structure

Remote State Backend

Reusable Module Pattern

Data Sources for Cross-Module References

Best Practices

Module Design

State Management

Safety

Naming and Tagging

Common Pitfalls

Examples

Variable Validation

From `docker`

From `docker`

From `kubernetes`

From `container-orchestration`

From `terraform`

From `nginx`

From `linux-admin`

From `dns`

From `environment-management`