Add docker/README.md documenting published images, compose example, and required container privileges
- Dominant language
- Python
- Stars
- 670
- Forks
- 183
- Avg merge
- 15h 13m
- Merged PRs (30d)
- 368
Description
## Motivation
Once the epic publishes the seven `lablup/backend.ai-*` images, operators need a single place that explains what each image is, where it lives on Docker Hub, how to compose them, and which containers need elevated privileges. The `docker/` directory currently has dockerfiles but no README, and the privilege requirements (especially for the DooD agent, BA-7271) are non-obvious and easy to get wrong.
## Objective
A `docker/README.md` that lets an operator go from "pulled the images" to "running deployment" without reading the dockerfiles or agent source.
## Details
1. **Image index**: table mapping each dockerfile to its Docker Hub repository page (`https://hub.docker.com/r/lablup/backend.ai-`) with a one-line role description, and the tagging scheme (version tags; `latest` = latest final release only).
1. **Suggested docker compose file**: a reference `docker-compose` example composing the published images (can point to / align with `docker-compose.monorepo.yml`), including the halfstack dependencies it assumes.
1. **Privilege matrix** for containers that need more than defaults:
- **manager**: `network_mode: host`, `privileged: true`, `/var/run/docker.sock` bind mount
- **agent**: `network_mode: host`, `privileged: true`, `/var/run/docker.sock` bind mount, host `/sys` (sysfs) visibility, `pid: host`, and `cgroupns: host` (compose `cgroup: host`)
- Explain _why_ each is needed (DooD kernel control via the host daemon, sysfs/cgroup metrics reads, host PID namespace for process visibility, host networking for kernel↔agent ports; host cgroupns because the PID-translation logic in `src/ai/backend/agent/utils.py` / `src/ai/backend/common/cgroup.py` parses `/proc/{pid}/cgroup` expecting host-rooted `docker/` paths — a private cgroupns breaks it) so operators can consciously accept the blast radius rather than cargo-cult it.
- Call out the trap explicitly: on cgroup v2 hosts Docker defaults to a **private** cgroup namespace even for `--privileged` containers, so `cgroupns: host` must be set explicitly.
- Include the agent path-parity requirement from BA-7271 (scratch/ipc/vfolder mount sources must exist at identical absolute paths on host and in the agent container).
1. Keep it per the repo writing style: conclusion first, tables over prose, interfaces/contracts only. Cross-check the `README.md`/`AGENTS.md` split — guardrails belong in `AGENTS.md` if one is added later; this README is for human operators.
Depends on: image names/tagging finalized in BA-7268; agent privilege details finalized in BA-7271.
## Success Criteria
- [ ] `docker/README.md` exists with the image↔Docker Hub index and tagging scheme.
- [ ] A working compose example (or explicit pointer to the maintained compose file) is included.
- [ ] Privilege matrix covers manager and agent (`--net=host`, `--privileged`, docker.sock; agent additionally host `/sys` visibility, `pid: host`, `cgroupns: host`) with rationale for each.
- [ ] Verified against a real deployment during BA-7270 (compose example actually starts).
JIRA Issue: BA-7272
Contributor guide
Research direction
Start with the existing dockerfiles, docker-compose.monorepo.yml, and the referenced agent paths src/ai/backend/agent/utils.py and src/ai/backend/common/cgroup.py. Add docker/README.md with the image index, tagging rules, compose guidance, and manager/agent privilege rationale, while keeping operator guidance separate from any future AGENTS.md guardrails. Done means the success criteria are covered and the compose example is verified during BA-7270.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, docker-compose, python
- Domain
- devops, documentation, infrastructure
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 58/100