incus-compose

README

incus-compose

Bring the familiar Docker Compose workflow to Incus containers. incus-compose implements the Compose specification for the Incus ecosystem, allowing you to define and run multi-container applications using the same docker-compose.yml files you already know.

https://github.com/user-attachments/assets/f4a82695-9d4f-4ee4-9376-562c48c87575

Why incus-compose?

Incus provides powerful system containers and virtual machines with superior security and isolation, but lacks the declarative multi-container orchestration that Docker Compose offers. This tool bridges that gap:

• Use existing docker-compose.yml files with Incus containers
• Leverage Incus's native OCI registry support for image pulling
• Run Docker/OCI images directly from registries
• Manage complex multi-container applications with familiar commands
• Benefit from Incus's resource efficiency and security model

Features

Status: Beta - testing the beta release of incus-compose.

• Familiar commands: up, down, start, stop, restart, list (and ps), logs, exec, config, plus build, healthd, incus (pass-through), and self-update
• Compose project parsing via compose-go, with automatic compose.incus.yaml overrides and x-incus / x-incus-compose extensions for raw Incus options
• OCI image pulling from docker.io, ghcr.io, and other registries
• Two-stage image cache in a dedicated Incus project (survives down/up, avoids registry rate limits)
• Local image building via Podman/Docker doc
• Bridge networks with automatic name sanitization
• Static IPv4/IPv6 addresses with automatic DHCP ranges doc
• Port forwarding via proxy devices or kernel NAT mode doc
• Storage volumes with UID/GID shifting; bind mounts (pass-through by default, optional seeding) doc
• Health checks, restart policies, and depends_on: service_healthy ordering via the ic-healthd sidecar doc
• Service scaling with up --scale and orphan pruning
• Incus project isolation
• Resource limits and other advanced compose features (shm_size, container_name, etc.)
• Configuration via INCUS_COMPOSE_* environment variables for every flag, with a configurable parallel worker count doc

Quick Start

Requires podman or docker for image building and an Incus https remote (needed for healthchecking) with OCI registries added. See Getting Started for the full setup walkthrough.

Install the latest release (the script verifies the SHA-256 checksum):

curl -sSfL https://raw.githubusercontent.com/lxc/incus-compose/main/install.sh | sh -s -- -b ~/.local/bin

Or grab a prebuilt archive from the Releases Page.

Then point it at your existing compose.yaml:

# Start services
incus-compose up

# View logs
incus-compose logs -f

# List running services
incus-compose list

# Stop and remove
incus-compose down

Quick Links

Full docs index: docs/README.md

• Getting Started - Install and run your first compose project
• CLI Reference - Commands and options
• Compose Compatibility - What works and what doesn't
• Architecture - How it works under the hood
• Why Incus? - Benefits over Docker
• Contributing - Contributing to incus-compose

Architecture

incus-compose uses a resource-first design, see Architecture Documentation for details.

Support and community

The following channels are available for you to interact with the Incus community.

Bug reports

You can file bug reports and feature requests at: https://github.com/lxc/incus-compose/issues/new

Community support

Community support is handled at: https://discuss.linuxcontainers.org

Documentation

The official documentation is available at: https://github.com/lxc/incus-compose/tree/main/docs

Contributing

Fixes and new features are greatly appreciated. Make sure to read our contributing guidelines first!

Credits

This project is inspired by @bketelsen. Some components are adapted from docker compose. The install.sh script is adapted from golangci-lint, based on the GoReleaser install-script template.

This project uses AI tools as development aids (drafting, iteration, reviews, tests, and documentation). Architecture, constraints, and final code decisions are owned by the human committers.

Earlier development was on Gitlab.

License

Apache 2.0