# 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:

```bash
# 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:

```bash
# 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

```bash
# 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):
   ```bash
   make docker-dev-host
   ```

2. **Reset Docker networking**:
   ```bash
   make docker-reset
   ```

3. **Restart Docker daemon** (requires sudo):
   ```bash
   sudo systemctl restart docker
   ```

4. **Use native development** (recommended):
   ```bash
   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