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
2025-09-14 16:59:55 -07:00
parent 7131b2ed17
commit 348a9817a3
1 changed files with 166 additions and 0 deletions
--- a/docker/README.md
+++ 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