unitforge/docker

Docker Setup for UnitForge

This directory contains Docker configuration files for running UnitForge in containers.

Current Status

UnitForge provides modern Docker containerization with uv-optimized builds and container registry support.

Quick Start

Option 1: Docker Development (Recommended)

# Build and run containers
make docker-build
make docker-dev

Access the application at: http://localhost:8000

Option 2: Native Development

The application also runs natively without Docker:

# Activate virtual environment
source .venv/bin/activate

# Start the development server
./start-server.sh --host 0.0.0.0 --log-level debug

Available Docker Commands

# Build images
make docker-build             # Build with modern uv-optimized Dockerfile

# Run containers
make docker-dev               # Development mode with hot reload
make docker-prod              # Production mode

# Container registry
make registry-build           # Build and tag for registry
make registry-push            # Build, tag, and push to registry
make docker-login             # Login to container registry
make docker-pull              # Pull from registry

# Utilities
make docker-logs              # View container logs
make docker-shell             # Open shell in container
make docker-clean             # Clean up containers and volumes
make docker-clean-registry    # Clean registry images from local cache

Services

unitforge-dev

• Purpose: Development environment with hot reload
• Port: 8000
• Features: Debug logging, auto-reload, volume mounting for live code changes
• Build: Modern uv-optimized with virtual environment

unitforge-prod

• Purpose: Production environment
• Port: 8080 (mapped from container's 8000)
• Features: Optimized for performance, no reload, security hardened

unitforge-cli

• Purpose: CLI-only access
• Usage: docker-compose --profile cli run --rm unitforge-cli --help

File Structure

docker/
├── README.md                    # This file
../docker-compose.yml           # Main compose configuration
../Dockerfile                   # Modern uv-optimized build

Configuration

Environment Variables

The containers use the .env file for configuration. Key variables:

• DEBUG: Enable/disable debug mode
• LOG_LEVEL: Logging verbosity (debug, info, warning, error)
• RELOAD: Enable/disable auto-reload
• CONTAINER_REGISTRY_URL: Container registry URL
• CONTAINER_TAG: Image tag for builds
• UV_CACHE_DIR: uv package manager cache directory

Volumes

• .:/app: Live code mounting for development
• /app/.venv: Virtual environment (container-managed)
• /app/backend/__pycache__: Python cache files (excluded)
• uv-cache: uv package manager cache volume

Troubleshooting

Common Issues

Error: Cannot connect to the Docker daemon

• Cause: Docker service not running
• Solution: sudo systemctl start docker

Error: permission denied while trying to connect to Docker daemon

• Cause: User not in docker group
• Solution: sudo usermod -aG docker $USER && newgrp docker

Error: registry authentication required

• Cause: Not logged into container registry
• Solution: make docker-login

Error: uv not found during container build

• Cause: uv installation failed
• Solution: Check network connectivity and retry build

Performance Tips

1. Use registry caching: make registry-build caches layers
2. Volume mounts: Development uses volumes for fast rebuilds
3. uv cache: Persistent cache volumes speed up installs
4. Multi-stage builds: Production images are optimized

Production Considerations

For production deployments:

1. Container Registry: Use make registry-push for deployment
2. Security: Non-root user, read-only filesystem, security contexts
3. Health checks: Comprehensive application health monitoring
4. Resource limits: CPU and memory constraints
5. Secrets management: External secret injection via environment
6. Logging: Structured logging and log aggregation
7. uv Optimization: Cached builds with persistent uv cache

Container Registry Workflow

# Configure registry in .env
CONTAINER_REGISTRY_URL=http://gitea-http.taildb3494.ts.net/will/unitforge
CONTAINER_TAG=latest

# Build and push
make registry-push

# Deploy from registry
make docker-pull
docker run -p 8000:8000 $CONTAINER_REGISTRY_URL:$CONTAINER_TAG

Future Enhancements

• Add database containers (PostgreSQL, Redis)
• Implement Kubernetes manifests
• Add monitoring stack (Prometheus, Grafana)
• Set up CI/CD pipeline integration
• Add backup and recovery procedures
• Multi-architecture builds (ARM64/AMD64)

Support

For Docker-specific issues:

1. Check this README for troubleshooting tips
2. Try native development as an alternative
3. Check container logs: make docker-logs

For application issues:

1. Check application logs: make docker-logs
2. Access container shell: make docker-shell
3. Run health checks manually inside container
4. Verify registry configuration in .env

For container registry issues:

1. Verify registry URL and credentials
2. Try make docker-login for authentication
3. Check network connectivity to registry