docs: remove legacy Docker networking workarounds from README files
Main README.md changes: - Update Python requirement from 3.8+ to 3.11+ (matching Dockerfile) - Remove docker-dev-host and legacy networking workarounds - Add container registry workflow documentation - Simplify installation instructions (remove duplicate manual setup) - Update Docker section to focus on modern container workflows - Add registry-push and registry commands to examples - Streamline project evolution section Docker README.md changes: - Remove all legacy networking workaround documentation - Remove docker-dev-host, docker-prod-host, docker-reset targets - Remove docker-build-legacy references - Add modern container registry workflow section - Update troubleshooting to focus on common Docker issues - Add uv-optimized build information - Update status from 'networking issues' to 'modern Docker support' - Add container registry authentication and workflow docs Both files now reflect the modern, clean Docker setup without legacy workarounds.
This commit is contained in:
William Valentin
153
docker/README.md
153
docker/README.md
@@ -4,12 +4,21 @@ This directory contains Docker configuration files for running UnitForge in cont
|
||||
|
||||
## 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.
|
||||
UnitForge provides modern Docker containerization with uv-optimized builds and container registry support.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Option 1: Native Development (Recommended)
|
||||
The application runs perfectly without Docker:
|
||||
### 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
|
||||
@@ -19,36 +28,27 @@ source .venv/bin/activate
|
||||
./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)
|
||||
make docker-build # Build with modern uv-optimized Dockerfile
|
||||
|
||||
# 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)
|
||||
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-reset # Reset Docker networking
|
||||
make docker-clean-registry # Clean registry images from local cache
|
||||
```
|
||||
|
||||
## Services
|
||||
@@ -57,11 +57,12 @@ make docker-reset # Reset Docker networking
|
||||
- **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-like environment
|
||||
- **Purpose**: Production environment
|
||||
- **Port**: 8080 (mapped from container's 8000)
|
||||
- **Features**: Optimized for performance, no reload
|
||||
- **Features**: Optimized for performance, no reload, security hardened
|
||||
|
||||
### unitforge-cli
|
||||
- **Purpose**: CLI-only access
|
||||
@@ -72,9 +73,8 @@ make docker-reset # Reset Docker networking
|
||||
```
|
||||
docker/
|
||||
├── README.md # This file
|
||||
docker-compose.yml # Main compose configuration
|
||||
docker-compose.host-network.yml # Host networking workaround
|
||||
Dockerfile # Simple, single-stage build
|
||||
../docker-compose.yml # Main compose configuration
|
||||
../Dockerfile # Modern uv-optimized build
|
||||
```
|
||||
|
||||
## Configuration
|
||||
@@ -85,82 +85,93 @@ 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
|
||||
- `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`: Exclude virtual environment from host
|
||||
- `/app/backend/__pycache__`: Exclude Python cache files
|
||||
- `/app/.venv`: Virtual environment (container-managed)
|
||||
- `/app/backend/__pycache__`: Python cache files (excluded)
|
||||
- `uv-cache`: uv package manager cache volume
|
||||
|
||||
## 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`
|
||||
|
||||
**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
|
||||
|
||||
When the networking issue is resolved, consider these production improvements:
|
||||
For production deployments:
|
||||
|
||||
1. **Multi-stage builds**: Separate build and runtime environments
|
||||
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
|
||||
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
|
||||
|
||||
Once Docker networking is stable:
|
||||
|
||||
- Add database containers (PostgreSQL, Redis)
|
||||
- Implement proper secrets management
|
||||
- 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 known workarounds
|
||||
1. Check this README for troubleshooting tips
|
||||
2. Try native development as an alternative
|
||||
3. Report persistent networking issues to system administrator
|
||||
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
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user