Composia

Documentation

Your Compose files, everywhere.

A self-hosted orchestration system crafted for power users. Define services in plain text, keep them in Git, with all configuration file-based and lock-in-free. Backups, DNS, reverse proxying, and image updates — all included.

Unlike PaaS platforms, Composia stays out of your way. Your configuration lives in standard docker-compose.yaml and composia-meta.yaml files that you own. The control plane coordinates and reports, but you always retain direct CLI and file-based access to every node.

# composia-meta.yaml — declare what and where
name: my-app
nodes:
  - main
  - edge

# docker-compose.yaml — standard Compose, no lock-in
services:
  app:
    image: myapp:1.2.3
    ports:
      - "8080:80"
    volumes:
      - ./data:/app/data

Features

• Multi-node Compose — deploy services to any node from a simple configuration; works across NAT, firewalls, and CDNs
• Standard files, no lock-in — docker-compose.yaml + composia-meta.yaml in your own Git repository; open formats, manual control anytime
• Web dashboard — file browsing and editing, live logs, Docker resource views, and interactive terminals; mobile-friendly
• CLI and public API — full-featured CLI ready for automation and AI agents; public APIs for third-party clients
• Backup and restore — automated backups powered by Rustic, with scheduled runs, snapshot management, and on-demand restores
• DNS and reverse proxy — Cloudflare DNS management and Caddy reverse proxying out of the box; auto-sync and reload your Caddyfile
• Image update detection — automatically detect new Docker image tags and apply updates; supports multiple versioning strategies
• Built-in notifications — Email, Telegram, and Alertmanager notifications for task results, backup events, image updates, and node status changes
• And more… — task system, encrypted secrets, automatic deployments, Prometheus metrics, cross-platform support, accessibility

Stack

Component	Technology
Backend	Go
Frontend	SvelteKit (Bun)
Runtime	Docker Compose
State	SQLite
RPC	ConnectRPC
Web UI	shadcn-svelte

Quick Start

• Installation
• Configuration Guide
• Development Guide
• Why Composia?

Repository Layout

cmd/
  composia/            user-facing CLI
  composia-agent/      agent runtime
  composia-controller/  controller runtime
dev/                    local development config and state
gen/go/                 generated protobuf and Connect code
internal/
  app/                  application entrypoints
    agent/              agent server
    cli/                CLI commands
    controller/         controller server
    notify/             notification dispatch
  core/                 domain logic
    backup/             backup and restore operations
    config/             configuration loading
    notify/             notification event system
    repo/               git repo and service file management
    schedule/           cron-based task scheduling
    task/               task execution engine
  platform/             infrastructure
    configpath/         config file resolution
    rpcutil/            RPC helpers
    secret/             age encryption and decryption
    store/              SQLite persistence layer
  version/              build version
proto/                  protobuf definitions
web/                    SvelteKit frontend
  src/routes/
    backups/            backup management
    login/              authentication
    logout/             session termination
    nodes/              node management
    services/           service management
    settings/           system settings
    tasks/              task and schedule management

Attributions

• Dockman — Docker management UI reference for resource list and inspect page patterns (AGPL-3.0)
• Twemoji — the Composia logo is adapted from Twemoji graphics, licensed under CC BY 4.0

License

Source code is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE.

Documentation and website content (including Markdown files and site/content/) are licensed under Creative Commons Attribution 4.0 International. See LICENSES/CC-BY-4.0.txt.

When reusing documentation or website content, provide attribution to the Composia project, link to the original repository when reasonably practicable, link to the CC BY 4.0 license, and indicate if changes were made.

The Composia logo and derived site icons are licensed under CC BY 4.0 with attribution to Twemoji as described above.

This documentation license does not apply to source code, configuration files, generated files, third-party materials, trademarks, service marks, or project logos except where explicitly stated.

For commercial licensing outside AGPL-3.0 scope, contact the author.