Runtipi

Tipi (formerly Runtipi) is a self‑hosted homeserver orchestrator that abstracts Docker composition behind a unified web UI. At its core, the application exposes a RESTful API and a GraphQL‑style query interface for programmatic control, while the UI is built with React and communicates via WebSocket‑driven events. The backend is a NestJS application written in TypeScript, which leverages Docker‑Compose and Docker‑CLI under the hood to spin up, scale, and tear down services. This design allows developers to treat each managed app as a first‑class citizen with its own lifecycle, environment variables, and persistent volumes—all orchestrated by Tipi’s API layer.

Architecture

• Frontend: React 18 + TypeScript, bundled with Vite. The UI consumes a lightweight WebSocket endpoint for real‑time status updates and uses the fetch API for CRUD operations on apps.
• Backend: NestJS (Node.js) with a modular architecture. Key modules include AppStore, DockerManager, and Auth. Docker integration is handled through the official Docker SDK for Node, enabling fine‑grained control over containers, networks, and volumes.
• Data Layer: Tipi persists its configuration in a lightweight SQLite database (or optionally PostgreSQL for advanced setups). All app metadata, environment variables, and user preferences are stored here.
• Container Runtime: Docker Engine (version ≥ 20.10) is the sole runtime requirement. Tipi generates and manages docker-compose.yml files per app, ensuring isolation while sharing a common network stack.

Core Capabilities

• App Store Integration: A JSON‑based manifest system (similar to Docker Compose) defines each app’s image, ports, volumes, and optional pre‑/post‑install hooks. The store is versioned via GitHub repositories, enabling community contributions.
• API Surface: Endpoints for listing apps, installing/uninstalling, updating configuration, and executing custom scripts. Webhooks can be registered to react to lifecycle events (e.g., onStart, onStop).
• Customization: Users can edit the generated Compose file directly; changes persist across updates. Environment variables and secrets are injected via Tipi’s UI, with support for encrypted storage.
• Backup & Restore: Automated snapshots of app volumes are available, callable through the API or UI. Developers can script bulk backups across multiple apps using the provided endpoints.

Deployment & Infrastructure

Tipi is intentionally lightweight: a single binary (or Docker image) plus the Docker Engine. It runs on any 64‑bit Linux distribution, with optional support for ARM64 (e.g., Raspberry Pi). For production deployments, developers can:

• Containerize Tipi itself using the provided Dockerfile, enabling zero‑downtime upgrades.
• Scale horizontally by running multiple instances behind a reverse proxy (Traefik or Nginx) with shared volume mounts for persistence.
• Integrate with CI/CD pipelines to automatically deploy new app manifests or update existing ones via the API.

Integration & Extensibility

Tipi’s plugin architecture is based on app manifests: any Docker image can be wrapped into a manifest that defines UI components, configuration schemas, and lifecycle hooks. Developers can publish new manifests to the public App Store or host a private store on GitHub/Gitea. Additionally, the API exposes webhooks for external services (e.g., monitoring dashboards, Slack notifications) and supports OAuth2 authentication for secure API access.

Developer Experience

• Configuration: All settings are exposed through a JSON schema, making it trivial to generate form UI or validate inputs programmatically.
• Documentation: The official docs include comprehensive sections on the API, app manifest format, and deployment guides. A dedicated docs/api.md file provides inline examples (without installation snippets).
• Community: A vibrant Discord channel and Discourse forum provide rapid support. The project’s open‑source nature encourages pull requests, with a clear contributor guide and all‑contributors badge.

Use Cases

1. Personal Media Center – Spin up Plex, Jellyfin, or Emby with a single click and expose them via Traefik.
2. AI Development Sandbox – Deploy LlamaIndex, LangChain, or custom GPT agents as isolated containers for experimentation.
3. DevOps Testing Lab – Rapidly create temporary services (e.g., databases, message queues) for integration testing.
4. Home Automation Hub – Run Home Assistant or OpenHAB and expose secure dashboards to mobile devices.

Advantages

• Zero‑config Docker: Developers no longer need to write complex Compose files; the UI and API handle it.
• Consistent Lifecycle Management: Updates, rollbacks, and backups are version‑controlled and repeatable.
• Open‑source & Extensible: The manifest system allows any Docker image to become a first‑class app, and the API enables full automation.
• Performance: By delegating to Docker Engine, Tipi incurs minimal overhead compared to running containers natively.
• Licensing: MIT‑licensed, with no vendor lock‑in, allowing free use in commercial or personal projects.

Tipi thus provides a developer‑centric platform for managing self‑hosted services, combining the flexibility of Docker with an intuitive API and UI layer that accelerates deployment, maintenance, and experimentation.