Skip to content
Documentation
Installation
Package Managers and Binaries

Package Managers and Binaries

Use this page for non-container installs and manual binary downloads.

Runtime tools

Container images already include these tools. Non-container installs must provide them on the host.

Host roleRequired tools
ControllerCA certificates, git.
Agentgit, Docker CLI, Docker Buildx plugin, Docker Compose plugin, access to the Docker daemon.

Linux packages and archives install Composia binaries and optional systemd unit files. They do not install Docker, Docker Compose, or Git for you.

Debian and Ubuntu

Add the Forgejo APT repository:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl https://forgejo.alexma.top/api/packages/alexma233/debian/repository.key \
  -o /etc/apt/keyrings/composia.asc

echo "deb [signed-by=/etc/apt/keyrings/composia.asc] https://forgejo.alexma.top/api/packages/alexma233/debian stable main" \
  | sudo tee /etc/apt/sources.list.d/composia.list

sudo apt update
sudo apt install composia

You can also download the .deb package from the Releases page and install it with your package manager.

Verify:

composia --version

System services

Linux packages install inactive systemd units for the controller and agent. The units are not enabled or started automatically.

The packaged units use the default config paths:

ServiceConfig path
composia-controller.service/etc/composia/controller/config.yaml
composia-agent.service/etc/composia/agent/config.yaml

The packaged units use the default config paths, run as root as shipped, and do not create config files, data directories, or Git repositories for you. Bootstrap them before enabling services:

sudo install -d -m 0755 /etc/composia/controller /etc/composia/agent
sudo install -d -m 0750 \
  /var/lib/composia/controller/repo \
  /var/lib/composia/controller/state \
  /var/lib/composia/controller/logs \
  /var/lib/composia/agent/repo \
  /var/lib/composia/agent/state
sudo chown -R root:root /etc/composia /var/lib/composia
sudo git -C /var/lib/composia/controller/repo init
sudo git -C /var/lib/composia/agent/repo init

Use matching paths in the two config files:

/etc/composia/controller/config.yaml
controller:
  repo_dir: "/var/lib/composia/controller/repo"
  state_dir: "/var/lib/composia/controller/state"
  log_dir: "/var/lib/composia/controller/logs"
/etc/composia/agent/config.yaml
agent:
  repo_dir: "/var/lib/composia/agent/repo"
  state_dir: "/var/lib/composia/agent/state"

Verify ownership, write access, and Git initialization:

stat -c '%U:%G %a %n' \
  /var/lib/composia/controller/repo \
  /var/lib/composia/controller/state \
  /var/lib/composia/controller/logs \
  /var/lib/composia/agent/repo \
  /var/lib/composia/agent/state
sudo test -w /var/lib/composia/controller/repo
sudo test -w /var/lib/composia/agent/repo
sudo git -C /var/lib/composia/controller/repo rev-parse --is-inside-work-tree
sudo git -C /var/lib/composia/agent/repo rev-parse --is-inside-work-tree

If you add a systemd drop-in with User=, chown these paths to that service user instead.

After creating the config files, enable the services explicitly:

sudo systemctl enable --now composia-controller.service
sudo systemctl enable --now composia-agent.service

Linux archives include the same unit files under packaging/systemd/. If you install archive binaries under /usr/local/bin, edit the unit ExecStart paths before enabling them.

Last updated on • Renovate Bot
Docker ComposeConfiguration