added docs and container (podman + docker) setup

docs/docker/docker.md

@@ -0,0 +1,181 @@
+# Docker Quick Reference
+
+## 🚀 Quick Start
+
+```bash
+# Build and run (one command)
+docker build -t argparse-builder . && docker run -d -p 8080:8080 argparse-builder
+
+# Or with docker-compose
+docker-compose up -d
+```
+
+## 📦 Files Included
+
+```
+Dockerfile              ← Production (scratch-based, ~7MB)
+Dockerfile.alpine       ← Development (Alpine, ~15MB)
+docker-compose.yml      ← Easy deployment
+.dockerignore           ← Build optimization
+k8s-deployment.yaml     ← Kubernetes manifest
+DOCKER_GUIDE.md         ← Complete documentation
+Makefile.docker         ← Build automation
+main_enhancements.go    ← Health check & config code
+```
+
+## 🔨 Build Options
+
+```bash
+# Production (minimal)
+docker build -t argparse-builder .
+
+# Development (with shell)
+docker build -f Dockerfile.alpine -t argparse-builder:alpine .
+
+# Multi-platform
+docker buildx build --platform linux/amd64,linux/arm64 -t argparse-builder .
+```
+
+## ▶️ Run Options
+
+```bash
+# Basic
+docker run -d -p 8080:8080 argparse-builder
+
+# With limits
+docker run -d -p 8080:8080 --memory=128m --cpus=0.5 argparse-builder
+
+# Secure
+docker run -d -p 8080:8080 --read-only --cap-drop=ALL argparse-builder
+```
+
+## 🎯 Image Sizes
+
+| Image   | Size    | Use          |
+| ------- | ------- | ------------ |
+| scratch | ~7 MB   | Production   |
+| alpine  | ~15 MB  | Development  |
+| no-opt  | ~900 MB | ❌ Don't use |
+
+## 🔍 Health Check
+
+```bash
+# Check health
+curl http://localhost:8080/health
+
+# Docker health status
+docker ps --filter "health=healthy"
+```
+
+## 📊 Monitoring
+
+```bash
+# Logs
+docker logs -f argparse-builder
+
+# Stats
+docker stats argparse-builder
+
+# Inspect
+docker inspect argparse-builder
+```
+
+## 🎪 Kubernetes
+
+```bash
+# Deploy
+kubectl apply -f k8s-deployment.yaml
+
+# Check status
+kubectl get pods -n argparse-builder
+kubectl get svc -n argparse-builder
+
+# Logs
+kubectl logs -f deployment/argparse-builder -n argparse-builder
+```
+
+## 🛠️ Makefile Commands
+
+```bash
+make docker-build      # Build image
+make docker-run        # Run container
+make docker-logs       # View logs
+make compose-up        # Start with compose
+make clean             # Clean everything
+```
+
+## 🔒 Security Features
+
+- Non-root user (UID 65534)
+- Read-only filesystem
+- No capabilities
+- Static binary
+- Minimal attack surface
+
+## 📝 Key Points
+
+✅ Dockerfile uses multi-stage build (builder + scratch)
+✅ Healthcheck endpoint at /health
+✅ Environment vars: PORT, LOG_LEVEL
+✅ Graceful shutdown support
+✅ Resource limits configured
+✅ Security hardened by default
+
+## 🌐 Registry Push
+
+```bash
+# GitHub Container Registry
+docker tag argparse-builder ghcr.io/username/argparse-builder
+docker push ghcr.io/username/argparse-builder
+
+# Docker Hub
+docker tag argparse-builder username/argparse-builder
+docker push username/argparse-builder
+```
+
+## 🔄 CI/CD Ready
+
+GitHub Actions example included in DOCKER_GUIDE.md for:
+
+- Automated builds on push
+- Multi-platform support
+- Registry push
+- Cache optimization
+
+See DOCKER_GUIDE.md for complete instructions.
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```