From 761dc6c13f91da91f6340e298260620ca4a55cc7 Mon Sep 17 00:00:00 2001
From: Riccardo Schirone <562321+ret2libc@users.noreply.github.com>
Date: Mon, 18 May 2026 16:15:53 +0200
Subject: [PATCH] Add compose.prebuilt.yaml overlay for prebuilt GHCR images
 (#548)

Adds an overlay for dev/docker-compose that resets the `build:` block
of every locally-built component and points it at the matching prebuilt
image from GHCR, so developers can run the stack without local builds.
Image tag defaults to "main" and is overridable via BUTTERCUP_IMAGE_TAG.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci: allow Docker Compose !reset/!override tags in YAML check

The static-checks YAML step uses yaml.safe_load_all, which rejects the
Compose-specific !reset/!override merge tags used by
compose.prebuilt.yaml. Register no-op constructors for those tags so
compose overlays validate without masking real YAML errors elsewhere.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/static-checks.yml      |  3 ++
 dev/docker-compose/README.md             | 13 ++++++
 dev/docker-compose/compose.prebuilt.yaml | 54 ++++++++++++++++++++++++
 3 files changed, 70 insertions(+)
 create mode 100644 dev/docker-compose/compose.prebuilt.yaml

diff --git a/.github/workflows/static-checks.yml b/.github/workflows/static-checks.yml
index 7d7e4425..2b8507db 100644
--- a/.github/workflows/static-checks.yml
+++ b/.github/workflows/static-checks.yml
@@ -40,6 +40,9 @@ jobs:
           python3 -c "
           import yaml
           from pathlib import Path
+          # Docker Compose merge tags are valid in compose files but unknown to safe_load
+          for _t in ('!reset', '!override'):
+              yaml.SafeLoader.add_constructor(_t, lambda loader, node: None)
           for f in Path('.').rglob('*.yaml'):
               if 'deployment/k8s' not in str(f):
                   list(yaml.safe_load_all(f.read_text()))
diff --git a/dev/docker-compose/README.md b/dev/docker-compose/README.md
index b50699ae..9220ac1c 100644
--- a/dev/docker-compose/README.md
+++ b/dev/docker-compose/README.md
@@ -18,11 +18,24 @@ cd dev/docker-compose && docker-compose --profile graphdb up -d
 cd dev/docker-compose && docker-compose down
 ```
 
+### Using prebuilt images (skip local builds)
+
+`compose.prebuilt.yaml` is an overlay that replaces every locally-built
+component with its prebuilt image from GHCR, so nothing is built locally:
+
+```bash
+cd dev/docker-compose && docker compose -f compose.yaml -f compose.prebuilt.yaml up -d
+
+# Pin a specific image tag (defaults to "main"):
+BUTTERCUP_IMAGE_TAG=<branch-or-tag> docker compose -f compose.yaml -f compose.prebuilt.yaml up -d
+```
+
 ## Configuration
 
 - `env.template` - Template for environment variables (copy to `.env` and customize)
 - `env.dev.compose` - Development-specific environment configuration
 - `compose.yaml` - Main compose file with all services
+- `compose.prebuilt.yaml` - Overlay that pulls prebuilt GHCR images instead of building locally
 
 ## Notes
 
diff --git a/dev/docker-compose/compose.prebuilt.yaml b/dev/docker-compose/compose.prebuilt.yaml
new file mode 100644
index 00000000..0a8d0396
--- /dev/null
+++ b/dev/docker-compose/compose.prebuilt.yaml
@@ -0,0 +1,54 @@
+# Overlay for compose.yaml that pulls the prebuilt component images from GHCR
+# instead of building them locally. It only overrides the services that have a
+# `build:` block, resetting it and pointing at the published image.
+#
+# Usage (from dev/docker-compose):
+#   docker compose -f compose.yaml -f compose.prebuilt.yaml up -d
+#
+# Override the image tag (defaults to "main"):
+#   BUTTERCUP_IMAGE_TAG=<branch-or-tag> docker compose -f compose.yaml -f compose.prebuilt.yaml up -d
+
+services:
+  program-model:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-program-model:${BUTTERCUP_IMAGE_TAG:-main}
+
+  coverage-bot:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-fuzzer:${BUTTERCUP_IMAGE_TAG:-main}
+
+  build-bot:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-fuzzer:${BUTTERCUP_IMAGE_TAG:-main}
+
+  tracer-bot:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-fuzzer:${BUTTERCUP_IMAGE_TAG:-main}
+
+  fuzzer-bot:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-fuzzer:${BUTTERCUP_IMAGE_TAG:-main}
+
+  task-downloader:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-orchestrator:${BUTTERCUP_IMAGE_TAG:-main}
+
+  task-server:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-orchestrator:${BUTTERCUP_IMAGE_TAG:-main}
+
+  scheduler:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-orchestrator:${BUTTERCUP_IMAGE_TAG:-main}
+
+  seed-gen:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-seed-gen:${BUTTERCUP_IMAGE_TAG:-main}
+
+  patcher:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-patcher:${BUTTERCUP_IMAGE_TAG:-main}
+
+  buttercup-ui:
+    build: !reset null
+    image: ghcr.io/trailofbits/buttercup/buttercup-orchestrator:${BUTTERCUP_IMAGE_TAG:-main}