UnitForge

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.

⚡ Now powered by uv - 10-100x faster Python package management!

✨ Features

• 🛠️ CLI Tool: Create and validate systemd unit files from the command line
• 🌐 Web UI: Simple browser-based interface for visual editing
• ✅ Validation: Comprehensive syntax and configuration validation
• 📋 Templates: Pre-built templates for common service types
• 📥 Export: Download generated unit files
• 🔍 Preview: Real-time preview of unit file output
• 🐳 Container Support: Templates for Docker/Podman services
• ⏰ Timer Support: Create systemd timer units for scheduled tasks
• 🔌 Socket Support: Socket-activated services
• 🏗️ Interactive Mode: Step-by-step guided unit file creation

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• uv package manager (recommended for fast installs)
• Linux system with systemd (for deployment)

Quick Installation with uv

1. Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone and setup:

git clone <repository-url>
cd unitforge
./setup-dev.sh  # Automated setup with uv

Manual Installation

1. Clone the repository:

git clone <repository-url>
cd unitforge

2. Set up with uv (recommended):

uv venv
source .venv/bin/activate
uv pip install -e ".[dev,web]"

Running the Web Interface

Start the development server:

# Quick start (automated)
./start-server.sh

# With uv (recommended)
make server

# Custom configuration
./start-server.sh --host 127.0.0.1 --port 3000 --log-level debug

# Docker development
make docker-dev

Access the web interface at: http://localhost:8000

CLI Usage

Basic Commands

# Create a new service unit file
./unitforge-cli create --type service --name myapp --exec-start "/usr/bin/myapp"

# Validate an existing unit file
./unitforge-cli validate /path/to/myapp.service

# Show available templates
./unitforge-cli template list

# Generate from template (interactive)
./unitforge-cli template generate webapp --interactive

# Generate with parameters
./unitforge-cli template generate webapp \
  --param name=mywebapp \
  --param exec_start="/usr/bin/node server.js" \
  --param user=webapp \
  --param working_directory=/opt/webapp

Template Examples

Web Application Service:

./unitforge-cli template generate webapp \
  --param name=mywebapp \
  --param description="My Web Application" \
  --param exec_start="/usr/bin/node /opt/webapp/server.js" \
  --param user=webapp \
  --param group=webapp \
  --param working_directory=/opt/webapp \
  --param port=3000 \
  --param restart_policy=on-failure \
  --param private_tmp=true \
  --param protect_system=strict

Database Service:

./unitforge-cli template generate database \
  --param name=postgresql \
  --param description="PostgreSQL Database Server" \
  --param exec_start="/usr/lib/postgresql/13/bin/postgres -D /var/lib/postgresql/13/main" \
  --param user=postgres \
  --param group=postgres \
  --param data_directory=/var/lib/postgresql/13/main

Container Service:

./unitforge-cli template generate container \
  --param name=nginx-container \
  --param description="Nginx Web Server Container" \
  --param container_runtime=docker \
  --param image=nginx:alpine \
  --param ports="80:80,443:443" \
  --param volumes="/data/nginx:/usr/share/nginx/html:ro"

Backup Timer:

./unitforge-cli template generate backup-timer \
  --param name=daily-backup \
  --param description="Daily database backup" \
  --param schedule=daily \
  --param backup_script="/usr/local/bin/backup.sh" \
  --param backup_user=backup

📁 Project Structure

unitforge/
├── backend/                 # Python backend
│   ├── app/
│   │   ├── main.py         # FastAPI application
│   │   ├── api/            # API routes
│   │   ├── core/           # Business logic
│   │   │   ├── unit_file.py    # Unit file parser/validator
│   │   │   └── templates.py    # Template system
│   │   └── templates/      # Unit file templates
│   ├── cli/                # CLI implementation
│   │   └── __init__.py     # Click-based CLI
│   └── requirements.txt    # Python dependencies
├── frontend/               # Web UI
│   ├── static/            # CSS, JS files
│   │   ├── css/style.css  # Main stylesheet
│   │   └── js/            # JavaScript modules
│   └── templates/         # HTML templates
│       ├── index.html     # Homepage
│       ├── editor.html    # Unit file editor
│       └── templates.html # Template browser
├── tests/                 # Test suite
│   └── test_unit_file.py  # Unit file tests
├── unitforge-cli          # CLI entry point
├── start-server.sh        # Web server startup script
├── demo.sh               # Interactive demo
└── README.md

🎯 Supported Unit Types

UnitForge supports all major systemd unit types:

Type	Description	Example Use Cases
Service	Standard system services	Web servers, databases, applications
Timer	Scheduled tasks	Backups, maintenance jobs, cron-like tasks
Socket	Socket-activated services	Network services, IPC
Mount	Filesystem mount points	Auto-mounting drives, network shares
Target	Service groups and dependencies	Boot targets, service grouping
Path	Path-based activation	File watchers, directory monitoring

🌐 Web Interface Features

Homepage

• Quick access to all tools
• Feature overview
• File upload for validation

Visual Editor

• Form-based unit file creation
• Real-time validation
• Live preview
• Type-specific configuration panels
• Common pattern insertion

Template Browser

• Browse available templates by category
• Interactive parameter configuration
• Live preview generation
• One-click download
• Validation feedback

🔌 API Endpoints

The web interface provides a REST API for integration:

Endpoint	Method	Description
GET /	GET	Web UI homepage
GET /editor	GET	Unit file editor
GET /templates	GET	Template browser
POST /api/validate	POST	Validate unit file content
POST /api/generate	POST	Generate from template
POST /api/create	POST	Create basic unit file
GET /api/templates	GET	List available templates
GET /api/templates/{name}	GET	Get specific template
POST /api/upload	POST	Upload and validate file
POST /api/download	POST	Download unit file
GET /health	GET	Health check

API Documentation

Interactive API documentation is available at:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc

🧪 Running Tests

# Quick test run
make test

# With coverage
make test-cov

# Watch mode for development
make test-watch

# Using uv directly
uv run pytest tests/ -v

# Docker testing
make docker-test

# All quality checks
make check-all

🎮 Interactive Demo

Run the interactive demo to see all features in action:

./demo.sh

The demo will:

• Show CLI capabilities
• Create various unit file types
• Demonstrate template usage
• Show validation features
• Generate example files

🔧 Development

Setting up Development Environment

1. Quick setup (recommended):

git clone <repository-url>
cd unitforge
make setup-dev  # Uses uv for fast setup

2. Manual setup:

git clone <repository-url>
cd unitforge
uv venv
source .venv/bin/activate
uv pip install -e ".[dev,web]"

3. Development workflow:

# Start development server
make server

# Run tests with coverage
make test-cov

# Format and lint code
make format && make lint

# Complete development cycle
make dev  # format + lint + test

# Use development helper
./dev.sh server    # Start server
./dev.sh test      # Run tests
./dev.sh format    # Format code

Adding New Templates

1. Create a new template class in backend/app/core/templates.py
2. Inherit from UnitTemplate
3. Define parameters and generation logic
4. Register in TemplateRegistry

Example:

class MyCustomTemplate(UnitTemplate):
    def __init__(self):
        super().__init__(
            name="my-template",
            description="My custom service template",
            unit_type=UnitType.SERVICE,
            category="Custom Services",
            parameters=[
                TemplateParameter("name", "Service name", "string"),
                # ... more parameters
            ]
        )

    def generate(self, params):
        # Implementation
        pass

Development Tools

Quality Assurance:

make lint          # Run all linters (black, isort, flake8)
make type-check    # Run mypy type checking
make security-check # Run bandit security scan
make pre-commit    # Run pre-commit hooks

Package Management:

make deps-update   # Update all dependencies
make deps-check    # Check for vulnerabilities
uv pip list        # List installed packages
uv pip show <pkg>  # Show package info

Docker Development:

make docker-build       # Build images
make docker-dev         # Development environment
make docker-clean       # Clean up containers
make registry-push      # Build and push to container registry

Code Style

• Python: Follow PEP 8, use type hints, formatted with Black
• JavaScript: ES6+, consistent formatting
• HTML/CSS: Semantic markup, responsive design
• Pre-commit hooks: Automatic formatting and linting

🐳 Docker Support

UnitForge provides full Docker support with modern container workflows.

Container Templates

UnitForge includes templates for containerized services:

# Docker service
./unitforge-cli template generate container \
  --param container_runtime=docker \
  --param image=myapp:latest

# Podman service
./unitforge-cli template generate container \
  --param container_runtime=podman \
  --param image=registry.example.com/myapp:v1.0

Docker Commands

make docker-build         # Build images
make docker-dev           # Development environment
make docker-prod          # Production environment
make docker-clean         # Clean up containers
make registry-push        # Build and push to container registry
make docker-login         # Login to container registry

Container Registry Support

# Configure registry in .env file
CONTAINER_REGISTRY_URL=http://gitea-http.taildb3494.ts.net/will/unitforge
CONTAINER_TAG=latest

# Build and push to registry
make registry-push

# Pull from registry
make docker-pull

🔍 Validation Features

UnitForge provides comprehensive validation:

• Syntax validation: Proper INI format, valid sections
• Semantic validation: Required fields, type checking
• Best practices: Security recommendations, performance tips
• Dependencies: Circular dependency detection
• Time formats: systemd time span validation
• Path validation: File and directory path checking

🚀 Performance & Tooling

Modern Python Tooling with uv

UnitForge uses uv for blazing-fast Python package management:

• 10-100x faster than pip for installs
• Rust-powered dependency resolution and caching
• Modern Python tooling with pyproject.toml support
• Container-optimized builds and deployments
• Consistent cross-platform behavior

Make Commands

Command	Description	Speed Improvement
make setup-dev	Complete development setup	10x faster
make server	Start development server	Instant
make test	Run test suite	Standard
make test-cov	Tests with coverage	Standard
make lint	Run all linters	Standard
make format	Format code	Standard
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

📚 Documentation

📖 Complete Documentation

For comprehensive guides and references, see the Documentation Index:

• User Guide - Installation, usage, and configuration
• Developer Guide - Development setup and contribution workflow
• Environment Configuration - Complete environment variable reference
• Docker Setup - Container development and deployment
• Scripts & Utilities - Development tools and color utilities

🔗 External References

• systemd.unit(5) - Unit configuration
• systemd.service(5) - Service units
• systemd.timer(5) - Timer units
• systemd.socket(5) - Socket units
• systemd documentation - Official documentation

🤝 Contributing

New contributors: Please see the Contributing Guide for complete development setup and workflow instructions.

Quick Contributing Steps

1. Fork the repository
2. Set up development environment: make setup-dev
3. Create a feature branch: git checkout -b feature/amazing-feature
4. Make your changes and add tests
5. Run quality checks: make dev (format + lint + test)
6. Commit and push your changes
7. Submit a pull request

Key Guidelines

• Development Setup: Use Contributing Guide for consistent environment
• Quality Assurance: All code must pass make dev (format, lint, test)
• Documentation: Update relevant docs for new features
• Testing: Write tests for new functionality

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• systemd team for excellent documentation
• FastAPI for the web framework
• Click for CLI functionality
• Bootstrap for responsive UI components
• uv for revolutionizing Python package management
• Astral for modern Python tooling ecosystem

📈 Project Evolution

v1.0 - Initial release v1.1 - ⚡ Modern Python tooling - Complete migration to uv, container registry support:

🚀 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

• Web Interface: http://localhost:8000 (when running)
• API Documentation: http://localhost:8000/api/docs
• GitHub Repository: https://github.com/unitforge/unitforge
• Bug Reports: https://github.com/unitforge/unitforge/issues

---

UnitForge - Making systemd unit file management simple and reliable! 🚀