argparser/docs/container.md

Docker Deployment Guide

Quick Start

# Build and run
docker build -t argparse-builder .
docker run -d -p 8080:8080 --name argparse-builder argparse-builder

# Or use docker-compose
docker-compose up -d

# Access at http://localhost:8080

Dockerfile Options

1. Dockerfile (scratch-based) - RECOMMENDED

Size: ~7-8 MB

• Minimal attack surface
• No shell, no package manager
• Best for production

docker build -t argparse-builder:scratch .

2. Dockerfile.alpine (Alpine-based)

Size: ~15 MB

• Has shell for debugging
• Includes wget for healthchecks
• Better for development

docker build -f Dockerfile.alpine -t argparse-builder:alpine .

Build Commands

Standard Build

docker build -t argparse-builder:latest .

Multi-platform Build

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t argparse-builder:multi \
  --push .

Build with Cache

docker build \
  --cache-from argparse-builder:latest \
  -t argparse-builder:latest .

Optimized Build Args

docker build \
  --build-arg GO_VERSION=1.23 \
  --build-arg CGO_ENABLED=0 \
  -t argparse-builder:optimized .

Run Options

Basic Run

docker run -d -p 8080:8080 argparse-builder

With Custom Port

docker run -d -p 3000:8080 argparse-builder

With Environment Variables

docker run -d \
  -p 8080:8080 \
  -e PORT=8080 \
  -e LOG_LEVEL=debug \
  argparse-builder

With Resource Limits

docker run -d \
  -p 8080:8080 \
  --memory="128m" \
  --cpus="0.5" \
  argparse-builder

With Read-only Root Filesystem

docker run -d \
  -p 8080:8080 \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  argparse-builder

Docker Compose

Start Services

docker-compose up -d

View Logs

docker-compose logs -f

Stop Services

docker-compose down

Rebuild and Restart

docker-compose up -d --build

Scale (if needed)

docker-compose up -d --scale argparse-builder=3

Health Checks

Check Container Health

docker ps --filter "name=argparse-builder"

Manual Health Check

# For Alpine image
docker exec argparse-builder wget -qO- http://localhost:8080/

# For scratch image (no shell)
curl http://localhost:8080/

View Health Status

docker inspect --format='{{json .State.Health}}' argparse-builder | jq

Image Management

List Images

docker images | grep argparse-builder

Tag Image

docker tag argparse-builder:latest registry.example.com/argparse-builder:v1.0

Push to Registry

docker push registry.example.com/argparse-builder:v1.0

Clean Up

# Remove stopped containers
docker container prune

# Remove unused images
docker image prune -a

# Remove everything
docker system prune -a

Kubernetes Deployment

Basic Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: argparse-builder
spec:
  replicas: 2
  selector:
    matchLabels:
      app: argparse-builder
  template:
    metadata:
      labels:
        app: argparse-builder
    spec:
      containers:
        - name: argparse-builder
          image: argparse-builder:latest
          ports:
            - containerPort: 8080
          resources:
            limits:
              memory: "128Mi"
              cpu: "500m"
            requests:
              memory: "32Mi"
              cpu: "100m"
          livenessProbe:
            httpGet:
              path: /
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /
              port: 8080
            initialDelaySeconds: 3
            periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: argparse-builder
spec:
  type: LoadBalancer
  ports:
    - port: 80
      targetPort: 8080
  selector:
    app: argparse-builder

Deploy to Kubernetes

kubectl apply -f k8s-deployment.yaml
kubectl get pods -l app=argparse-builder
kubectl get svc argparse-builder

Security Best Practices

1. Use Specific Version Tags

FROM golang:1.23-alpine AS builder

2. Run as Non-root User

USER 65534:65534

3. Drop All Capabilities

docker run --cap-drop=ALL argparse-builder

4. Use Read-only Root Filesystem

docker run --read-only argparse-builder

5. Scan for Vulnerabilities

docker scan argparse-builder:latest

Performance Tuning

Build-time Optimizations

# Static linking
-ldflags='-w -s -extldflags "-static"'

# No CGO
CGO_ENABLED=0

# Strip debug info
-w -s

Runtime Optimizations

# Set GOMAXPROCS (if multi-core)
docker run -e GOMAXPROCS=2 argparse-builder

# Adjust memory limits
docker run --memory="64m" --memory-swap="128m" argparse-builder

Monitoring

Container Stats

docker stats argparse-builder

Logs

docker logs -f --tail 100 argparse-builder

Resource Usage

docker container inspect argparse-builder | jq '.[0].HostConfig.Memory'

Troubleshooting

Container Won't Start

# Check logs
docker logs argparse-builder

# Inspect container
docker inspect argparse-builder

# Try running interactively (Alpine image)
docker run -it --rm argparse-builder:alpine sh

Port Already in Use

# Find process using port
lsof -i :8080

# Use different port
docker run -p 3000:8080 argparse-builder

Permission Denied

# Check file permissions
ls -la argparse-builder

# Ensure binary is executable
chmod +x argparse-builder

Out of Memory

# Increase memory limit
docker run --memory="256m" argparse-builder

# Check current limits
docker inspect argparse-builder | jq '.[0].HostConfig'

CI/CD Integration

GitHub Actions

name: Docker Build and Push

on:
  push:
    branches: [main]
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Login to Registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

GitLab CI

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

Image Size Comparison

Dockerfile	Base Image	Size	Use Case
Dockerfile	scratch	~7 MB	Production
Dockerfile.alpine	alpine:3.19	~15 MB	Development
(no optimization)	golang:1.23	~900 MB	Not recommended

Registry Options

GitHub Container Registry

docker tag argparse-builder:latest ghcr.io/username/argparse-builder:latest
docker push ghcr.io/username/argparse-builder:latest

Docker Hub

docker tag argparse-builder:latest username/argparse-builder:latest
docker push username/argparse-builder:latest

Private Registry

docker tag argparse-builder:latest registry.example.com/argparse-builder:latest
docker push registry.example.com/argparse-builder:latest