unitforge/README.md

# 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.

![UnitForge Logo](https://img.shields.io/badge/UnitForge-systemd%20unit%20files-blue?style=for-the-badge)
[![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)

> ⚡ **Now powered by [uv](https://github.com/astral-sh/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](https://github.com/astral-sh/uv) package manager (recommended for fast installs)
- Linux system with systemd (for deployment)

### Quick Installation with uv

1. **Install uv (if not already installed):**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

2. **Clone and setup:**
```bash
git clone <repository-url>
cd unitforge
./setup-dev.sh  # Automated setup with uv
```

### Manual Installation

1. **Clone the repository:**
```bash
git clone <repository-url>
cd unitforge
```

2. **Set up with uv (recommended):**
```bash
uv venv
source .venv/bin/activate
uv pip install -e ".[dev,web]"
```



### Running the Web Interface

Start the development server:
```bash
# 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

```bash
# 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:**
```bash
./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:**
```bash
./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:**
```bash
./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:**
```bash
./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

```bash
# 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:

```bash
./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):**
```bash
git clone <repository-url>
cd unitforge
make setup-dev  # Uses uv for fast setup
```

2. **Manual setup:**
```bash
git clone <repository-url>
cd unitforge
uv venv
source .venv/bin/activate
uv pip install -e ".[dev,web]"
```

3. **Development workflow:**
```bash
# 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:
```python
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:**
```bash
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:**
```bash
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:**
```bash
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:

```bash
# 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
```bash
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
```bash
# 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](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
- **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**](docs/README.md):

- **[User Guide](docs/README.md#user-documentation)** - Installation, usage, and configuration
- **[Developer Guide](CONTRIBUTING.md)** - Development setup and contribution workflow
- **[Environment Configuration](docs/ENVIRONMENT.md)** - Complete environment variable reference
- **[Docker Setup](docker/README.md)** - Container development and deployment
- **[Scripts & Utilities](scripts/README.md)** - Development tools and color utilities

### 🔗 External References
- [systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) - Unit configuration
- [systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html) - Service units
- [systemd.timer(5)](https://www.freedesktop.org/software/systemd/man/systemd.timer.html) - Timer units
- [systemd.socket(5)](https://www.freedesktop.org/software/systemd/man/systemd.socket.html) - Socket units
- [systemd documentation](https://systemd.io/) - Official documentation

## 🔄 CI/CD

UnitForge includes comprehensive CI/CD workflows for automated testing, building, and deployment using Gitea Actions.

### Workflow Overview

- **Pull Request Checks** (`pr-check.yml`) - Validates PRs with tests, builds, and configuration checks
- **Main Build Pipeline** (`build-container.yml`) - Builds and pushes multi-arch container images
- **Release Pipeline** (`release.yml`) - Automated releases with security scanning and PyPI publishing
- **Nightly Builds** (`nightly.yml`) - Daily builds with comprehensive testing and performance checks

### Multi-Architecture Support

All container images are built for multiple architectures:
- `linux/amd64` - Standard x86_64 architecture
- `linux/arm64` - ARM64 architecture (Apple Silicon, ARM servers)

### Container Registry

Images are pushed to the configured container registry:
```bash
# Default registry configuration
REGISTRY: gitea-http.taildb3494.ts.net
IMAGE_NAME: will/unitforge

# Available tags
latest              # Latest stable release
develop            # Latest development build
v1.2.3             # Specific version
nightly-latest     # Latest nightly build
```

### Local CI/CD Testing

Set up your local environment for CI/CD development:

```bash
# Setup CI/CD environment
./scripts/setup-ci.sh

# Test local builds
./scripts/setup-ci.sh --test-build

# Test container health
./scripts/health_check.sh

# Build multi-arch locally
make docker-buildx-local

# Build and push to registry
make registry-push
```

### Required Secrets

Configure these secrets in your Gitea repository:

```bash
CONTAINER_REGISTRY_USERNAME=your-registry-username
CONTAINER_REGISTRY_PASSWORD=your-registry-password
PYPI_API_TOKEN=your-pypi-token
GITHUB_TOKEN=your-github-token
```

### Workflow Features

- **Automated Testing**: Comprehensive test suite across Python versions
- **Security Scanning**: Trivy vulnerability scanning with blocking on critical issues
- **Performance Testing**: Basic performance validation and memory usage checks
- **Multi-stage Deployment**: Staging and production environment support
- **Artifact Management**: Automatic cleanup of old nightly builds
- **Build Caching**: GitHub Actions cache for faster builds

For detailed CI/CD documentation, see [`.gitea/workflows/README.md`](.gitea/workflows/README.md).

## 🤝 Contributing

**New contributors**: Please see the [**Contributing Guide**](CONTRIBUTING.md) 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](CONTRIBUTING.md) 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](LICENSE) file for details.

## 🙏 Acknowledgments

- [systemd](https://systemd.io/) team for excellent documentation
- [FastAPI](https://fastapi.tiangolo.com/) for the web framework
- [Click](https://click.palletsprojects.com/) for CLI functionality
- [Bootstrap](https://getbootstrap.com/) for responsive UI components
- [uv](https://github.com/astral-sh/uv) for revolutionizing Python package management
- [Astral](https://astral.sh/) 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! 🚀