unitforge/docker/README.md

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

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

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

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