Development¶
CI builds Docker. You do not have to.¶
Images are built in GitHub Actions only when affected. Base changes rebuild all
inheriting images on main; a variant-only change builds that variant. Version
changes are mapped to Dockerfile ARGs, so a Ruff bump builds only Python, while
a shared Playwright bump builds Node, QA, and design. Docs-only changes never
build Docker images. A local Docker daemon remains optional.
PRs validate a changed base once and any directly changed variants against it; otherwise affected variants use the published base (amd64). Main publishes affected images for their supported architectures, then smoke-tests them in the same job; PHP/design also run service checks. Publish jobs run at most three variants concurrently. Main compares against the last successful build, so failed or coalesced pushes are not forgotten.
Lint, version checks, and the autoscaler tests need nothing but Bash, Python and (optionally) shellcheck:
make lint
That runs:
scripts/check-versions.sh—versions.envmatches every Dockerfile, no version ARG has a default;bash -non every script;shellcheck --severity=warningwhen installed;- the autoscaler unit tests.
Repository layout¶
images/base/ base Dockerfile, entrypoint, lib/*.sh
images/<variant>/ one Dockerfile per variant
autoscaler/ Python autoscaler + unit tests
scripts/ build.sh, test-image.sh, check-versions.sh
deploy/ compose, swarm, ecs, kubernetes, dokploy examples
docs/ this documentation
versions.env single source of truth for every tool version
compose.yaml quickstart
Building locally (optional)¶
VARIANTS=base scripts/build.sh
VARIANTS=base,node scripts/test-image.sh
scripts/build.sh loads versions.env, exports every key, and passes each as a
build arg. A push build publishes base first, then the variants that inherit
from it.
PUSH=1 VERSION=0.2.0 scripts/build.sh
That is for maintainers with registry credentials; CI does it automatically.
Releasing¶
After a successful image-changing push to main, CI automatically increments
the latest stable release's patch version, adds versioned GHCR tags, and creates
a GitHub release. No manual Git tag, second build, or second test matrix.
Release promotion copies manifest references, not image layers. Unchanged variants reuse their previous image. All source digests are resolved before promotion; a release appears only after every versioned tag succeeds. The Git tag reserves the patch number before promotion; failed promotions can leave an unused patch number, never overwrite its image tags. Re-running an already released commit leaves its versioned tags untouched. Older commits cannot release after a newer main commit exists. OCI version labels keep the original build commit, including for reused images.
Manual recovery: dispatch Build on main with variants=all or a comma-separated
subset. This builds/publishes only the selection; it does not create a release.
Tag pushes no longer trigger builds. Manual publication is restricted to main. Major/minor releases remain a separate
maintainer decision.
Adding a variant¶
- Create
images/<name>/Dockerfilestarting with:
ARG BASE_IMAGE=multica-runtime:base
FROM ${BASE_IMAGE}
- Declare version ARGs without defaults:
ARG MY_TOOL_VERSION
The value must exist in versions.env.
-
Install the tool, verify it runs (
mytool --version), and leave the baseENTRYPOINTin place unless you need a variant entrypoint. -
Add the context to
scripts/build.sh(context_for) and the expected binaries toscripts/test-image.sh(commands_for). -
Add it to the image lists in
scripts/ci-plan.pyandscripts/ci-release.py. -
Document it in
docs/variants.mdand the README table.
Run make lint. CI builds it on the PR.
Adding a version¶
# versions.env
MY_TOOL_VERSION=1.2.3
One line. Do not add a default to the Dockerfile — check-versions.sh rejects
it, because a default is how an image silently stops being pinned.
Variant entrypoints and hooks¶
Most variants inherit the base entrypoint unchanged. Two mechanisms exist:
- A variant entrypoint (
images/php,images/design) runs before the base one, starts side services, thenexecs/usr/local/bin/multica-entrypoint. - A hook (
/usr/local/lib/multica/hooks/*.sh) is sourced after Claude Code and OpenCode are configured. The design image uses this to register the Penpot MCP server with both CLIs.
Hooks run in lexical order and get the resolved environment (CLAUDE_CONFIG_DIR,
MR_*, config paths). A failing hook logs a warning and does not abort startup.
Style¶
- Shell: Bash 3.2 compatible in scripts that may run on macOS (no associative
arrays, no
mapfile, no${var,,}).set -Eeuo pipefail. - Prefer
local; quote expansions; fail loudly. - Dockerfile: one purpose per layer,
set -eux, clean apt lists and caches in the same layer. - Python: standard library only for the autoscaler, type hints, docstrings that explain why.
- Prose: explain decisions, not mechanics. No secrets, ever.
Commits and PRs¶
- Small, focused commits with an imperative subject
(
fix(php): wait for postgres before creating the user). - A PR should say what changed, why, and how it was verified. CI attaches the build; paste the relevant log lines rather than “works on my machine”.
- Update
CHANGELOG.mdfor user-visible changes. - Do not commit
.env, generated inventory, or build artifacts.
Release¶
- Update tools/code and
CHANGELOG.mdin a PR. - Merge to
main; CI builds/tests only affected images and updates rolling tags. - CI promotes existing images to the next patch version and creates the release.
Testing the entrypoint without a daemon¶
docker run --rm \
--entrypoint /usr/local/bin/multica-entrypoint \
-e MULTICA_TOKEN=test \
-e AI_BASE_URL=http://127.0.0.1:9/v1 \
-e AI_API_KEY=test \
-e AI_MODEL=test-model \
-e AI_MODELS_PROBE=0 \
-e MULTICA_DRY_RUN=1 \
ghcr.io/proreka/multica-runtime:base
It resolves the config, writes the OpenCode file, prints the banner, and exits
without contacting Multica. scripts/test-image.sh does exactly this per variant.