Docker Deployment¶

Deploy Machineuse using Docker and Docker Compose.

Container Runtime Limitation

Docker containers cannot run systemd-nspawn (the actual browser container runtime). Docker deployment is for the management plane only. Browser containers require bare-metal or VM deployment with systemd support.

Quick Start¶

Single Node¶

git clone https://github.com/dotcommoners/machineuse.git
cd machineuse

# Start services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

Distributed Mode¶

# Start distributed cluster
docker-compose -f docker-compose.distributed.yml up -d

# Check all services
docker-compose -f docker-compose.distributed.yml ps

Services¶

Single Node (`docker-compose.yml`)¶

Service	Port	Description
machineuse-api	8000	API server
postgres	5432	Database (optional)

Distributed (`docker-compose.distributed.yml`)¶

Service	Port	Description
control-plane	8000, 5555	Control plane
worker-1	8001	Worker node 1
worker-2	8002	Worker node 2
postgres	5432	Shared database

Configuration¶

Environment Variables¶

services:
  machineuse-api:
    environment:
      - MACHINEUSE_LOG_LEVEL=INFO
      - MACHINEUSE_DATA_DIR=/var/lib/machineuse
      - MACHINEUSE_MAX_INSTANCES=20
      # For PostgreSQL backend:
      - MACHINEUSE_DB_URL=postgresql://machineuse:machineuse@postgres:5432/machineuse

Volume Mounts¶

volumes:
  - machineuse-data:/var/lib/machineuse   # Data directory
  - ./config:/etc/machineuse:ro           # Configuration

Custom Configuration¶

Create config/config.json:

{
  "deployment_mode": "single_node",
  "api": {
    "host": "0.0.0.0",
    "port": 8000,
    "cors_origins": ["https://yourdomain.com"]
  },
  "containers": {
    "max_instances": 30
  }
}

Mount it:

volumes:
  - ./config:/etc/machineuse:ro

Building Images¶

Build Locally¶

# Build the image
docker build -t machineuse:latest .

# Build with specific tag
docker build -t machineuse:v2.0.0 .

Multi-architecture Build¶

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t machineuse:latest \
  --push .

Docker Compose Profiles¶

With PostgreSQL¶

# Start with PostgreSQL
docker-compose --profile with-postgres up -d

Development Mode¶

# docker-compose.override.yml
services:
  machineuse-api:
    volumes:
      - ./machineuse-api/machineuse:/app/machineuse:ro
    environment:
      - MACHINEUSE_LOG_LEVEL=DEBUG

docker-compose up -d

Health Checks¶

Built-in health checks:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s

Check health status:

docker inspect --format='{{.State.Health.Status}}' machineuse-api

Scaling Workers¶

# Scale to 3 workers
docker-compose -f docker-compose.distributed.yml up -d --scale worker=3

Networking¶

Internal Network¶

Services communicate on the machineuse-net bridge network:

networks:
  machineuse-net:
    driver: bridge

External Access¶

Expose ports as needed:

ports:
  - "8000:8000"   # API
  - "5555:5555"   # NNG (control plane only)

Custom Network¶

networks:
  machineuse-net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/16

Persistent Storage¶

Named Volumes¶

volumes:
  machineuse-data:
    driver: local
  postgres-data:
    driver: local

Host Mounts¶

volumes:
  - /data/machineuse:/var/lib/machineuse
  - /data/postgres:/var/lib/postgresql/data

Logs¶

View Logs¶

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f machineuse-api

# Last 100 lines
docker-compose logs --tail=100 machineuse-api

Log Driver¶

services:
  machineuse-api:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Backup¶

Database Backup¶

# PostgreSQL backup
docker-compose exec postgres pg_dump -U machineuse machineuse > backup.sql

# Restore
docker-compose exec -T postgres psql -U machineuse machineuse < backup.sql

Volume Backup¶

# Backup data volume
docker run --rm \
  -v machineuse_machineuse-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/machineuse-data.tar.gz /data

Production Considerations¶

Resource Limits¶

services:
  machineuse-api:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

Restart Policy¶

services:
  machineuse-api:
    restart: unless-stopped

Security¶

services:
  machineuse-api:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp

Upgrading¶

# Pull new images
docker-compose pull

# Recreate containers
docker-compose up -d --force-recreate

# Or with zero downtime (requires multiple replicas)
docker-compose up -d --no-deps --scale machineuse-api=2 machineuse-api
docker-compose up -d --no-deps --scale machineuse-api=1 machineuse-api

Troubleshooting¶

Container Won't Start¶

# Check logs
docker-compose logs machineuse-api

# Check container status
docker-compose ps

# Inspect container
docker inspect machineuse-api

Connection Issues¶

# Test internal connectivity
docker-compose exec machineuse-api curl http://postgres:5432

# Check network
docker network inspect machineuse_machineuse-net

Cleanup¶

# Stop and remove containers
docker-compose down

# Remove volumes too
docker-compose down -v

# Remove images
docker-compose down --rmi all