added docs and container (podman + docker) setup
This commit is contained in:
478
docs/container.md
Normal file
478
docs/container.md
Normal file
@@ -0,0 +1,478 @@
|
||||
# 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
|
||||
```
|
Reference in New Issue
Block a user