# docker-compose

Compose, for development work on the two workstations (novox/hq research 027/02: "the distribution's
package and nothing else", assigned only to the workstations; to-be 42 phase 2 step 9). The servers
run nothing through compose.

## Owns

| what | where |
|---|---|
| compose, as the container runtime's plugin (`docker compose`) and as `docker-compose` | package `docker-compose` |

Nothing else. The runtime, its configuration, buildx and the `docker` group are the `docker` module's
(to-be 42 phase 1 step 8). This module needs that runtime on the machine. Until the `docker` module
holds `node-container-runtime` there, nothing in the mesh says so, and the tools answer that the
runtime is missing or unreachable rather than an empty list.

## Improves

- **An owner for a package both workstations already carry.** On both, `docker-compose` 5.5.0 is
  installed explicitly by hand, as the plugin in `/usr/lib/docker/cli-plugins`. Assigning the module
  changes nothing on disk; from then on the package is the mesh's, upgraded with the machine and
  given back when the module goes.
- **The projects become visible from the mesh** without a shell on the machine: which are running,
  where their files are, their containers, logs and rendered configuration.
- **No account-level copy of the plugin** exists on either workstation (`~/.docker/cli-plugins` is
  empty), so there is no second compose to remove.

## Tools

All answer JSON; `(r)` reads, `(a)` acts. They run as the operator account, which reaches the runtime
through the `docker` group. Nothing goes through `sudo`.

A project is named by `dir`, its absolute directory, or by `project`, its name. A directory docker
already knows a project for is that project, with the files it was started from, overrides included.
Any other directory must hold a compose file.

| tool | what |
|---|---|
| `docker_compose_projects` (r) | every project docker knows, running or stopped: status, working directory (from the containers' labels), compose files, services, containers running of total |
| `docker_compose_ps` (r) | one project's containers: service, state, health, exit code, image, published ports |
| `docker_compose_logs` (r) | the last lines per service (default 200, at most 5000), optionally `since`; cut at 256 KiB |
| `docker_compose_config` (r) | the rendered configuration. Values of environment variables, build arguments and labels whose names suggest a secret, and inline secret or config content, are replaced with `[redacted]`, and the answer counts them |
| `docker_compose_up` (a) | `up --detach`, with the pull policy (default `missing`) and optionally `--build`, for all or some services |
| `docker_compose_down` (a) | `down`: containers and networks. **Volumes are kept**: no tool here removes data |
| `docker_compose_restart` (a) | restart all or some services |
| `docker_compose_pull` (a) | pull images without starting anything |
| `docker_compose_job` (r) | a long act's state: running or finished, exit status, the end of its output; without an id, every act this process knows |

**Acts are jobs.** An `up` that pulls or builds takes minutes, and the runtime gives a call 30 s. Each
act runs inside the tool's process for up to 15 minutes, and is waited on for 18 s. A finished act is
answered with its output, and a failed one as an error. One still running is answered with its job id,
which `docker_compose_job` follows. A job ends if the runtime restarts the bundle.

## Leaves as found

The projects themselves are the operator's work, under the operator's directories. Measured on
2026-10-04:

- **laptop:** `anton-lavinmq` and `anton-traefik` running, `anton-redis` stopped.
- **desktop:** `anton-lavinmq`, `lavinmq` (from `/services/lavinmq`, a predecessor's directory) and
  `registry` running.

Whether the desktop's `lavinmq` and `registry` should still run is the operator's call;
`docker_compose_down` with their directory stops them.