Docker Compose
The interactive installer can deploy the Web UI, Controller, or Agent independently, or deploy all three together. It uses the canonical docker-compose.yaml.
Interactive installer
Download the installer as a file so you can inspect it before execution. Do not pipe it directly into a shell:
curl -fLO https://forgejo.alexma.top/alexma233/composia/raw/branch/main/install.sh
less install.sh
sh install.shThe installer:
- asks which role to install and collects the required configuration;
- prints every directory, download, generated file, container command, and Compose command before making changes;
- redacts secrets from the plan and terminal output;
- waits for one explicit confirmation;
- executes and labels every step.
It does not install Docker, alter the firewall, or create system services. Generated secrets remain in mode-600 configuration files. Web passwords are converted locally to Argon2id hashes by the published Web image in a container with networking disabled, and are never written in plaintext.
The manual instructions below remain available if you prefer to create every file yourself.
Manual installation
Download the files
You do not need to clone the whole repository for a Docker Compose install. Download the compose file and environment template:
curl -LO https://forgejo.alexma.top/alexma233/composia/raw/branch/main/docker-compose.yaml
curl -L https://forgejo.alexma.top/alexma233/composia/raw/branch/main/.env.example -o .envEdit .env before starting the stack. The template is grouped by role; for the all-in-one stack, keep all groups. See Configuration for the meaning of each variable.
Find the Docker socket group ID on the host:
stat -c '%g' /var/run/docker.sockSet DOCKER_SOCK_GID to that value.
Agent repository path
COMPOSIA_AGENT_REPO_DIR is mounted as:
- ${COMPOSIA_AGENT_REPO_DIR}:${COMPOSIA_AGENT_REPO_DIR}The host path and container path must be the same. The agent invokes the host Docker daemon, and the host Docker daemon resolves bind mounts from the host filesystem. If the service repository is mounted at a different path inside the agent container, Docker Compose can generate host paths that do not exist.
Use the same absolute path on both sides, for example:
COMPOSIA_AGENT_REPO_DIR=/data/repo-agentSet agent.repo_dir in config.yaml to the same absolute path.
Basic config.yaml
Create config.yaml inside COMPOSIA_CONFIG_DIR. The Docker Compose file mounts this directory at /app/configs.
controller:
listen_addr: ":7001"
repo_dir: "/data/repo-controller"
state_dir: "/data/state-controller"
log_dir: "/data/logs"
access_tokens:
- name: "web"
token: "REPLACE_WITH_WEB_ACCESS_TOKEN"
enabled: true
nodes:
- id: "main"
display_name: "Main"
enabled: true
token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
agent:
controller_addr: "http://controller:7001"
node_id: "main"
token: "REPLACE_WITH_MAIN_AGENT_TOKEN"
repo_dir: "/data/repo-agent"
state_dir: "/data/state-agent"Set WEB_CONTROLLER_ACCESS_TOKEN in .env to the same value as controller.access_tokens[0].token.
Web password
WEB_LOGIN_PASSWORD_HASH must be an Argon2id PHC hash. Generate a ready-to-paste .env entry below:
Generated locally in your browser. Your password is never sent or stored.
Generate WEB_SESSION_SECRET with any cryptographically secure random generator, for example:
openssl rand -hex 32Start
docker compose up -d
docker compose psOpen the web UI at http://localhost:3000.
Role split
The compose file is sectioned by role:
- Controller stack:
init-repo-controller,init-perms-controller,controller. - Web UI:
web. - Shared init:
init-config-perms. - Agent stack:
init-perms-agent,agent.
Start a single role by naming its main service. Compose starts that role’s initialization dependencies automatically:
docker compose up -d web
docker compose up -d controller
docker compose up -d agentRun docker compose up -d for the all-in-one topology. A standalone Web UI or Agent must use a Controller URL reachable from its container. Each Agent node needs its own Docker socket access.
For a split deployment, install the Controller first. Copy its generated Web access token and Agent node token from config/config.yaml into the corresponding prompts on the other nodes. The Controller initialization container may change that file’s owner to UID 65532, so reading it later can require sudo.
Images
Release images are published to Forgejo, GHCR, and Docker Hub:
| Component | Forgejo | GHCR | Docker Hub |
|---|---|---|---|
| CLI | forgejo.alexma.top/alexma233/composia-cli | ghcr.io/alexma233/composia-cli | alexma233/composia-cli |
| Controller | forgejo.alexma.top/alexma233/composia-controller | ghcr.io/alexma233/composia-controller | alexma233/composia-controller |
| Agent | forgejo.alexma.top/alexma233/composia-agent | ghcr.io/alexma233/composia-agent | alexma233/composia-agent |
| Web | forgejo.alexma.top/alexma233/composia-web | ghcr.io/alexma233/composia-web | alexma233/composia-web |
Canary images are published only to Forgejo and GHCR.
Common checks
- Controller cannot start: verify
config.yamlexists underCOMPOSIA_CONFIG_DIRand that required controller paths exist or can be created. - Agent cannot use Docker: verify
DOCKER_SOCK_GIDmatches/var/run/docker.sockon the host. - Web cannot reach controller:
WEB_CONTROLLER_ADDRis for the web server container, whileWEB_BROWSER_CONTROLLER_ADDRis for the browser.