From 302a3d545c6461690ae6bc036929eff11c2c21b7 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Sun, 14 Sep 2025 17:35:36 -0700 Subject: [PATCH] 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. --- README.md | 94 +++++++++++------------------ docker/README.md | 153 +++++++++++++++++++++++++---------------------- 2 files changed, 116 insertions(+), 131 deletions(-) diff --git a/README.md b/README.md index 5ab9faf..3b0355a 100644 --- a/README.md +++ b/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. ![UnitForge Logo](https://img.shields.io/badge/UnitForge-systemd%20unit%20files-blue?style=for-the-badge) -[![Python](https://img.shields.io/badge/Python-3.8+-green?style=flat-square)](https://python.org) +[![Python](https://img.shields.io/badge/Python-3.11+-green?style=flat-square)](https://python.org) [![FastAPI](https://img.shields.io/badge/FastAPI-Web%20Interface-red?style=flat-square)](https://fastapi.tiangolo.com) [![uv](https://img.shields.io/badge/uv-fast%20Python%20packaging-orange?style=flat-square)](https://github.com/astral-sh/uv) [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](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 # 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 diff --git a/docker/README.md b/docker/README.md index f3db987..e478608 100644 --- a/docker/README.md +++ b/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 \ No newline at end of file +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