unitforge/docker

Docker Setup for UnitForge

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

Current Status

⚠️ Known Issue: There is a Docker networking issue on this system that prevents containers from starting with the default bridge network. The error operation not supported when creating veth pairs indicates a system-level networking problem.

Quick Start

Option 1: Native Development (Recommended)

The application runs perfectly without Docker:

# Activate virtual environment
source .venv/bin/activate

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

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

Option 2: Docker with Host Networking (Workaround)

If you need to use Docker, use host networking to bypass the bridge network issue:

# Build and run with host networking
make docker-dev-host

This will make the application available directly on the host's port 8000.

Available Docker Commands

# Build images
make docker-build              # Standard build (may fail due to networking)
make docker-build-legacy       # Legacy builder (may fail due to networking)

# Run containers
make docker-dev                # Development mode (may fail)
make docker-dev-host          # Development with host networking (workaround)
make docker-prod              # Production mode (may fail)
make docker-prod-host         # Production with host networking (workaround)

# Utilities
make docker-logs              # View container logs
make docker-shell             # Open shell in container
make docker-clean             # Clean up containers and volumes
make docker-reset             # Reset Docker networking

Services

unitforge-dev

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

unitforge-prod

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

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
docker-compose.host-network.yml  # Host networking workaround
Dockerfile                       # Simple, single-stage 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
• PYTHONPATH: Python module search path

Volumes

• .:/app: Live code mounting for development
• /app/.venv: Exclude virtual environment from host
• /app/backend/__pycache__: Exclude Python cache files

Troubleshooting

Docker Networking Issues

If you encounter networking errors:

1. Use host networking (temporary workaround):

   make docker-dev-host
   

2. Reset Docker networking:

   make docker-reset
   

3. Restart Docker daemon (requires sudo):

   sudo systemctl restart docker
   

4. Use native development (recommended):

   source .venv/bin/activate
   ./start-server.sh
   

Common Issues

Error: operation not supported when creating veth pairs

• Cause: System-level Docker networking issue
• Solution: Use host networking or native development

Error: failed to set up container networking

• Cause: Docker bridge network problems
• Solution: Try make docker-reset or use host networking

Error: Cannot connect to the Docker daemon

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

Production Considerations

When the networking issue is resolved, consider these production improvements:

1. Multi-stage builds: Separate build and runtime environments
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
6. Logging: Structured logging and log aggregation

Future Enhancements

Once Docker networking is stable:

• Add database containers (PostgreSQL, Redis)
• Implement proper secrets management
• Add monitoring stack (Prometheus, Grafana)
• Set up CI/CD pipeline integration
• Add backup and recovery procedures

Support

For Docker-specific issues:

1. Check this README for known workarounds
2. Try native development as an alternative
3. Report persistent networking issues to system administrator

For application issues:

1. Check application logs: make docker-logs
2. Access container shell: make docker-shell
3. Run health checks manually inside container