From 348a9817a37312a66216ad2ad6bd535fa7f6c35f Mon Sep 17 00:00:00 2001 From: William Valentin Date: Sun, 14 Sep 2025 16:59:55 -0700 Subject: [PATCH] docs(docker): add comprehensive Docker documentation and troubleshooting - Create docker/README.md with complete setup guide - Document known networking issues and workarounds - Provide alternative deployment strategies - Include troubleshooting steps for common problems - Explain host networking workaround usage - Recommend native development as primary option --- docker/README.md | 166 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 docker/README.md diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000..f3db987 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,166 @@ +# 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 \ No newline at end of file