argparser/docs/container.md

# Docker Deployment Guide

## Quick Start

```bash
# 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

```bash
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

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

## Build Commands

### Standard Build

```bash
docker build -t argparse-builder:latest .
```

### Multi-platform Build

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

### Build with Cache

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

### Optimized Build Args

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

## Run Options

### Basic Run

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

### With Custom Port

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

### With Environment Variables

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

### With Resource Limits

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

### With Read-only Root Filesystem

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

## Docker Compose

### Start Services

```bash
docker-compose up -d
```

### View Logs

```bash
docker-compose logs -f
```

### Stop Services

```bash
docker-compose down
```

### Rebuild and Restart

```bash
docker-compose up -d --build
```

### Scale (if needed)

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

## Health Checks

### Check Container Health

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

### Manual Health Check

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

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

### View Health Status

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

## Image Management

### List Images

```bash
docker images | grep argparse-builder
```

### Tag Image

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

### Push to Registry

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

### Clean Up

```bash
# Remove stopped containers
docker container prune

# Remove unused images
docker image prune -a

# Remove everything
docker system prune -a
```

## Kubernetes Deployment

### Basic Deployment

```yaml
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

```bash
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

```dockerfile
FROM golang:1.23-alpine AS builder
```

### 2. Run as Non-root User

```dockerfile
USER 65534:65534
```

### 3. Drop All Capabilities

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

### 4. Use Read-only Root Filesystem

```bash
docker run --read-only argparse-builder
```

### 5. Scan for Vulnerabilities

```bash
docker scan argparse-builder:latest
```

## Performance Tuning

### Build-time Optimizations

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

# No CGO
CGO_ENABLED=0

# Strip debug info
-w -s
```

### Runtime Optimizations

```bash
# 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

```bash
docker stats argparse-builder
```

### Logs

```bash
docker logs -f --tail 100 argparse-builder
```

### Resource Usage

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

## Troubleshooting

### Container Won't Start

```bash
# 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

```bash
# Find process using port
lsof -i :8080

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

### Permission Denied

```bash
# Check file permissions
ls -la argparse-builder

# Ensure binary is executable
chmod +x argparse-builder
```

### Out of Memory

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

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

## CI/CD Integration

### GitHub Actions

```yaml
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

```yaml
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

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

### Docker Hub

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

### Private Registry

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