Skip to content

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.env matches every Dockerfile, no version ARG has a default;
  • bash -n on every script;
  • shellcheck --severity=warning when 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

  1. Create images/<name>/Dockerfile starting with:
ARG BASE_IMAGE=multica-runtime:base
FROM ${BASE_IMAGE}
  1. Declare version ARGs without defaults:
ARG MY_TOOL_VERSION

The value must exist in versions.env.

  1. Install the tool, verify it runs (mytool --version), and leave the base ENTRYPOINT in place unless you need a variant entrypoint.

  2. Add the context to scripts/build.sh (context_for) and the expected binaries to scripts/test-image.sh (commands_for).

  3. Add it to the image lists in scripts/ci-plan.py and scripts/ci-release.py.

  4. Document it in docs/variants.md and 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, then execs /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.md for user-visible changes.
  • Do not commit .env, generated inventory, or build artifacts.

Release

  1. Update tools/code and CHANGELOG.md in a PR.
  2. Merge to main; CI builds/tests only affected images and updates rolling tags.
  3. 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.