ADR 0001: one image repository, many variant tags¶
Status: accepted
Context¶
Every stack (Node, PHP, Flutter, …) needs the same foundation: Debian, an agent CLI, the Multica CLI, git, a non-root user, and the same entrypoint. Only the toolchain differs.
The alternatives were:
- one repository/package per stack;
- one image with every tool installed;
- one base image plus a variant tag per stack, all in one package.
Option 1 multiplies CI, documentation, and the number of places where a security fix must land. Option 2 produces a huge image and forces every task to carry PHP, Android SDK, and Terraform whether it needs them or not.
Decision¶
Use one package (ghcr.io/proreka/multica-runtime) with a tag per variant:
:base :node :python :php :go :flutter :devops :qa :design
Each variant is FROM base and adds only its toolchain. All tags are built from
the same commit and share the base layers, so pulling a second variant downloads
only the difference.
The autoscaler is a separate package (multica-autoscaler) because it is not a
runtime: different entrypoint, different permissions, different lifecycle.
Consequences¶
- One CI pipeline, one changelog, one place to bump a version.
- A base-layer fix reaches every variant on the next build.
- Registry storage is efficient: the shared base is stored once.
- Users must understand tags;
:phpis not a separate product. - A breaking change in
baseaffects every variant at once. CI builds them all on every PR, which is the point. - A variant that needs a different base OS is not possible without forking the model. Nothing so far needs it.