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
94
README.md
94
README.md
@@ -3,7 +3,7 @@
|
||||
A comprehensive tool for creating, validating, previewing, and downloading Linux systemd unit files. UnitForge provides both a command-line interface and a simple web UI for managing systemd service configurations.
|
||||
|
||||
|
||||
[](https://python.org)
|
||||
[](https://python.org)
|
||||
[](https://fastapi.tiangolo.com)
|
||||
[](https://github.com/astral-sh/uv)
|
||||
[](LICENSE)
|
||||
@@ -27,7 +27,7 @@ A comprehensive tool for creating, validating, previewing, and downloading Linux
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.8 or higher
|
||||
- Python 3.11 or higher
|
||||
- [uv](https://github.com/astral-sh/uv) package manager (recommended for fast installs)
|
||||
- Linux system with systemd (for deployment)
|
||||
|
||||
@@ -60,12 +60,7 @@ source .venv/bin/activate
|
||||
uv pip install -e ".[dev,web]"
|
||||
```
|
||||
|
||||
3. **Alternative manual setup:**
|
||||
```bash
|
||||
uv venv .venv
|
||||
source .venv/bin/activate
|
||||
uv pip install -e ".[dev,web]"
|
||||
```
|
||||
|
||||
|
||||
### Running the Web Interface
|
||||
|
||||
@@ -80,11 +75,8 @@ make server
|
||||
# Custom configuration
|
||||
./start-server.sh --host 127.0.0.1 --port 3000 --log-level debug
|
||||
|
||||
# Docker development (if networking works)
|
||||
# Docker development
|
||||
make docker-dev
|
||||
|
||||
# Docker with host networking (workaround)
|
||||
make docker-dev-host
|
||||
```
|
||||
|
||||
Access the web interface at: **http://localhost:8000**
|
||||
@@ -375,10 +367,10 @@ uv pip show <pkg> # Show package info
|
||||
|
||||
**Docker Development:**
|
||||
```bash
|
||||
make docker-build # Build images (may fail due to networking)
|
||||
make docker-build # Build images
|
||||
make docker-dev # Development environment
|
||||
make docker-dev-host # Development with host networking (workaround)
|
||||
make docker-clean # Clean up containers
|
||||
make registry-push # Build and push to container registry
|
||||
```
|
||||
|
||||
### Code Style
|
||||
@@ -390,7 +382,7 @@ make docker-clean # Clean up containers
|
||||
|
||||
## 🐳 Docker Support
|
||||
|
||||
⚠️ **Current Status**: Docker networking issues prevent standard container builds. Use native development instead.
|
||||
UnitForge provides full Docker support with modern container workflows.
|
||||
|
||||
### Container Templates
|
||||
UnitForge includes templates for containerized services:
|
||||
@@ -407,22 +399,28 @@ UnitForge includes templates for containerized services:
|
||||
--param image=registry.example.com/myapp:v1.0
|
||||
```
|
||||
|
||||
### Docker Commands (when networking is fixed)
|
||||
### Docker Commands
|
||||
```bash
|
||||
make docker-build # Build images
|
||||
make docker-dev # Development environment
|
||||
make docker-prod # Production environment
|
||||
make docker-dev-host # Development with host networking (workaround)
|
||||
make docker-clean # Clean up containers
|
||||
make registry-push # Build and push to container registry
|
||||
make docker-login # Login to container registry
|
||||
```
|
||||
|
||||
**Recommended**: Use native development until Docker networking is resolved:
|
||||
### Container Registry Support
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
./start-server.sh
|
||||
```
|
||||
# Configure registry in .env file
|
||||
CONTAINER_REGISTRY_URL=http://gitea-http.taildb3494.ts.net/will/unitforge
|
||||
CONTAINER_TAG=latest
|
||||
|
||||
See `docker/README.md` for detailed Docker troubleshooting and workarounds.
|
||||
# Build and push to registry
|
||||
make registry-push
|
||||
|
||||
# Pull from registry
|
||||
make docker-pull
|
||||
```
|
||||
|
||||
## 🔍 Validation Features
|
||||
|
||||
@@ -437,26 +435,15 @@ UnitForge provides comprehensive validation:
|
||||
|
||||
## 🚀 Performance & Tooling
|
||||
|
||||
### Why uv?
|
||||
### Modern Python Tooling with uv
|
||||
|
||||
UnitForge has been fully migrated to use [uv](https://github.com/astral-sh/uv) for blazing-fast Python package management:
|
||||
UnitForge uses [uv](https://github.com/astral-sh/uv) for blazing-fast Python package management:
|
||||
|
||||
- **10-100x faster** than pip for installs
|
||||
- **Rust-powered** dependency resolution and caching
|
||||
- **Drop-in replacement** for pip with better UX
|
||||
- **Parallel downloads** and installs
|
||||
- **Consistent** cross-platform behavior
|
||||
- **Modern Python tooling** with `pyproject.toml` support
|
||||
|
||||
### Migration Benefits
|
||||
|
||||
The migration from traditional pip/npm tooling to uv provides:
|
||||
|
||||
- ⚡ **Faster CI/CD**: Dependencies install in seconds, not minutes
|
||||
- 🔒 **Better reproducibility**: More reliable dependency resolution
|
||||
- 🎯 **Modern standards**: Full `pyproject.toml` configuration
|
||||
- 🐳 **Optimized Docker**: Smaller images with faster builds
|
||||
- 🛠️ **Better DX**: Integrated tooling with consistent commands
|
||||
- **Container-optimized** builds and deployments
|
||||
- **Consistent** cross-platform behavior
|
||||
|
||||
### Make Commands
|
||||
|
||||
@@ -468,7 +455,8 @@ The migration from traditional pip/npm tooling to uv provides:
|
||||
| `make test-cov` | Tests with coverage | Standard |
|
||||
| `make lint` | Run all linters | Standard |
|
||||
| `make format` | Format code | Standard |
|
||||
| `make docker-dev` | Docker development | 5x faster builds |
|
||||
| `make docker-dev` | Docker development | Standard |
|
||||
| `make registry-push` | Build and push to registry | Fast |
|
||||
| `make clean` | Clean cache files | Standard |
|
||||
| `make status` | Show project status | Standard |
|
||||
|
||||
@@ -517,29 +505,15 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
|
||||
|
||||
## 📈 Project Evolution
|
||||
|
||||
**v1.0** - Initial release with traditional pip/venv tooling
|
||||
**v1.1** - ⚡ **Complete migration to uv** - No pip fallbacks, pure uv workflow:
|
||||
**v1.0** - Initial release
|
||||
**v1.1** - ⚡ **Modern Python tooling** - Complete migration to uv, container registry support:
|
||||
|
||||
### 🚀 Performance Improvements
|
||||
- Setup time: ~2-5 minutes → ~30 seconds (**5x faster**)
|
||||
- CI/CD pipeline: ~10-15 minutes → ~3-5 minutes (**3x faster**)
|
||||
- Docker builds: ~5-10 minutes → ~1-2 minutes (**5x faster**)
|
||||
- Package installs: ~1-2 minutes → ~5-10 seconds (**12x faster**)
|
||||
|
||||
### 🛠️ Tooling Modernization
|
||||
- **Eliminated pip fallbacks** - Pure uv-only workflow
|
||||
- **Modern pyproject.toml** - Replaced setup.py entirely
|
||||
- **Comprehensive Makefile** - 20+ development commands
|
||||
- **GitHub Actions optimization** - uv-native CI/CD
|
||||
- **Docker multi-stage builds** - uv-optimized containers
|
||||
- **Pre-commit automation** - Quality gates with uv integration
|
||||
|
||||
### 🎯 Developer Experience
|
||||
- **One-command setup**: `make setup-dev` handles everything
|
||||
- **Consistent environments**: No more "works on my machine"
|
||||
- **Faster feedback loops**: Tests, linting, building all accelerated
|
||||
- **Modern standards**: Following latest Python packaging best practices
|
||||
- **No legacy dependencies**: Clean, fast, reliable toolchain
|
||||
### 🚀 Key Features
|
||||
- **Lightning-fast setup**: `make setup-dev` handles everything in ~30 seconds
|
||||
- **Container registry**: Native support for Gitea/Docker registries
|
||||
- **Modern packaging**: Pure `pyproject.toml` configuration
|
||||
- **Developer experience**: One-command workflows for all operations
|
||||
- **Quality automation**: Pre-commit hooks and comprehensive testing
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
|
||||
151
docker/README.md
151
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
|
||||
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