One docker run turns a git-hosted ArchiMate model into a live,
auto-updating HTML report with an RU/EN + light/dark theme.

🥧 Killer feature: Archi finally runs on a Raspberry Pi.
There's no official Linux ARM64 build of Archi — we build one natively from source, no box64/QEMU at runtime.

🇬🇧 English · 🇷🇺 Русский

A Docker image that clones a git repository containing an ArchiMate model (a single *.archimate file or a coArchi repository, format auto-detected), runs it through the official Archi CLI to generate an HTML report, and serves it as static files via Caddy. Accepts a webhook from GitHub/GitLab/anything generic to regenerate the report on push.

This README is the project's common entry point: it covers the core contract (env vars, webhook, volumes, compose) and gets you to a running service. Deeper topics live in their own docs (each also available in Russian, with a .ru.md suffix):

Multiple models from one instance. Besides a single model via GIT_URL, the service can serve several ArchiMate reports from one container — each under its own /<slug>/ path, configured via indexed MODEL_<N>_* variables. Details, including recommendations for external path-based authentication, are in docs/MULTI_MODEL.md and docs/SECURITY.md.

• 🥧 Archi on a Raspberry Pi — finally. There's no official Linux ARM64 build of Archi, and emulating the x86_64 build via box64 runs into an open upstream bug (JVM/SWT/GTK3 — hangs or SIGBUSes) — so we build Archi natively from source for linux/gtk/aarch64 (Tycho/Maven) right at docker buildx build time. No QEMU/box64 at runtime — on a Pi 5, the report is generated on native silicon, byte-identical to the amd64 output. Details in docs/PATCHES.md.
• Model format is auto-detected. A single .archimate file or a coArchi repository (the git-native model format, one file per element) — no manual configuration needed in the common case.
• RU/EN + light/dark report theme out of the box (USE_MODERN_CSS, on by default) — language/theme toggle right in the report, better panel proportions. Prefer stock Archi styling? One flag turns it all off.
• 📝 Element documentation renders as Markdown, not raw text. Archi's stock report just prints the Documentation field's contents as-is — even if you wrote lists/tables/code in there. Here it goes through a real Markdown renderer right in the browser, so your model's documentation finally looks like documentation instead of a wall of text. Details in docs/THEMING.md.

• Debounced webhook. github/gitlab/generic signature schemes, a single-slot queue — concurrent pushes never race two generations against each other.
• Validated before publishing. The report is generated into a scratch directory and checked (non-empty index.html, see archi#980) — only then does its content replace what Caddy serves. That swap isn't a single atomic rename(2) (that breaks the moment /data/report is a mounted volume — see "Volumes" below), just a fast sequence of mvs, so in theory there's a vanishingly short window of mixed old/new content — not an issue in practice since the report is regenerated wholesale on every run anyway.
• No surprises at startup. Healthcheck, git operation timeouts/retries, and clear fail-fast configuration errors instead of a silently broken service.

docker run -d \
  --name archimate-report \
  -p 3000:3000 \
  -e GIT_URL=https://github.com/your-org/your-model-repo.git \
  -e GIT_TOKEN=ghp_xxx \
  umkabeaf/archimate-report:latest

The same image is mirrored to GHCR — ghcr.io/umka-beaf/archimate-report (tags always match Docker Hub, see "Building and publishing the image" below); substitute that address for umkabeaf/archimate-report:latest if you'd rather pull from ghcr.io.

The report is available at http://localhost:3000 a few seconds after start (the first generation runs synchronously before the web server comes up).

* — exactly one git auth method (or none, for public repositories). ** — required only together with WEBHOOK_SECRET.

GET /status (same port as the report) returns JSON {generating, last_run_at, last_success, last_error} — used as the container healthcheck.

Without WEBHOOK_SECRET, the /webhook endpoint isn't registered at all (returns 404) — a safe default, nothing is enabled implicitly. If WEBHOOK_SECRET is set, WEBHOOK_PROVIDER is required — the container fails at startup with a clear error if it's missing or invalid.

The endpoint path is configurable via WEBHOOK_PATH (default /webhook). A successful request immediately returns 202 Accepted — generation runs asynchronously. Check progress/result via GET /status. A single-slot debounce queue means concurrent pushes never race two git clone/Archi CLI runs against each other.

Three working directories; none are declared as VOLUME in the image — without explicit mounting they're ordinary container layers that don't survive docker rm:

For a full docker-compose.yml example (YAML anchors, an external reverse-proxy network, etc.), see the Russian README — it hasn't been translated separately, but the compose file itself is language-neutral.

• linux/amd64 — official Archi build (Archi-Linux64-*.tgz).
• linux/arm64 — Archi built natively from source (Tycho/Maven, linux/gtk/aarch64) at image build time. No official Linux ARM64 build of Archi exists — the Eclipse p2 repository already ships the needed SWT/GTK fragments, upstream just never requested that target. The additive patch lives in docker/patches/.

Since CI doesn't rebuild the image on every commit (see below), run docker/scripts/smoke-test.sh before a manual release. It builds the image for the host platform only (a multi-arch manifest can't be produced with --load) and runs regression checks against the logic shared by both architectures: generate.sh, entrypoint.sh, the Caddyfile, the webhook.

It checks: the plain model format (explicit MODEL_PATH) and the coArchi format with auto-detection — in both cases the container comes up, GET /status returns valid JSON, the report is served over HTTP 200 and isn't empty; plus a real webhook round-trip (correct secret → 202 → wait for the regeneration to finish; wrong secret → 401).

./docker/scripts/smoke-test.sh                       # build + test, ARCHI_VERSION=latest
ARCHI_VERSION=5.9.0 ./docker/scripts/smoke-test.sh    # pin a version
SKIP_BUILD=1 IMAGE=archi-report:m5 ./docker/scripts/smoke-test.sh   # reuse an already-built image

Containers it starts only live for the duration of the run — cleaned up automatically (trap cleanup EXIT) regardless of outcome. Exit 0 means it's safe to move on to the real multi-arch build and --push; a non-zero exit means read the log above the failing check and don't publish the image.

No CI auto-builds on every commit — publishing is manual, triggered by a new Archi release:

docker buildx build \
  -f docker/Dockerfile \
  --platform linux/amd64,linux/arm64 \
  -t <your-dockerhub-namespace>/archimate-report:<ARCHI_VERSION> \
  -t <your-dockerhub-namespace>/archimate-report:latest \
  --push .

(umkabeaf/archimate-report earlier in this README is our published image — pull that as-is. <your-dockerhub-namespace> here is only for forks publishing their own copy; substitute your own Docker Hub username/org.)

Run from the repo root (not docker/) — the build context is deliberately the whole repo so the Dockerfile can pull favicons straight from assets/favicon/ instead of keeping a second, hand-synced copy under docker/.

ARCHI_VERSION can be pinned explicitly via --build-arg ARCHI_VERSION=5.9.0; it defaults to resolving latest via the GitHub Releases API at build time.

The same multi-arch build+push can also be run manually from GitHub Actions — see .github/workflows/docker-publish.yml (workflow_dispatch, no auto-trigger on every push). CI splits the build into separate jobs — linux/amd64 builds on a regular runner, linux/arm64 on a native ubuntu-24.04-arm runner (no QEMU emulation, much faster than emulating the Tycho/Maven build under an amd64 runner) — then a merge job assembles both digests into one manifest list and publishes it to both Docker Hub and, as a mirror, GHCR (ghcr.io/umka-beaf/archimate-report) with tags identical to Docker Hub, via docker buildx imagetools create, with no rebuild.

The same workflow_dispatch run (as long as push isn't explicitly disabled) also publishes docs/DOCKERHUB.md as the repository's long description on the Docker Hub page — no separate step needed, it reuses the same DOCKERHUB_USERNAME/DOCKERHUB_TOKEN secrets as the registry login. The same script (docker/scripts/publish-dockerhub-readme.sh) can also be run manually, locally, if you only need to update the description without rebuilding the image:

DOCKERHUB_USERNAME=your-dockerhub-user DOCKERHUB_TOKEN=dckr_pat_xxx \
  ./docker/scripts/publish-dockerhub-readme.sh

MIT. The image itself bundles Archi (Eclipse Public License 2.0) and the coArchi plugin (archimatetool.com's own license) — downloaded/built at docker build time, not distributed as part of this repository's source.