feat: let an example run the published image instead of building

The images CI publishes were reachable only by hand: every compose.yml
builds from source and names no image, so there was nothing for a pull
to land on.

Adding `image:` to the base file looked like the fix but is a trap.
Compose's default pull_policy fetches a remote-resolvable image when it
is missing locally, even for a service with a build section, so a plain
`up -d` on a clean checkout would silently run the published image
instead of the contributor's code. `pull_policy: build` avoids that but
makes `docker compose pull` skip the service, losing the point.

An overlay keeps the base file building from source exactly as before
and reaches the registry only when asked, matching how compose.onchain
already layers on. CI now parses the merged pair too.

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

Author: rickstaa

.github/workflows/lint.yml

@@ -32,5 +32,9 @@ jobs:
             example=${dir%/}
             [ -f "$example/compose.yml" ] || continue
             docker compose -f "$example/compose.yml" config --quiet || status=1
+            if [ -f "$example/compose.image.yml" ]; then
+              docker compose -f "$example/compose.yml" \
+                -f "$example/compose.image.yml" config --quiet || status=1
+            fi
           done
           exit $status

README.md

@@ -129,12 +129,15 @@ The orchestrator and signer services are defined once at the repo root and pulle
 
 Each example ships a `Dockerfile` and a `compose.yml` that builds it locally. Those with a `Dockerfile` are also published to the GitHub Container Registry as `ghcr.io/livepeer/runner-example-<name>` (`linux/amd64`), linked from the example's own README. Tags: `latest` (current `main`), `stable` (latest `v*` release), `1.2` / `1.2.3`, `sha-<short>`.
 
-The packages are public, so pulling one needs no account and no login:
+The packages are public, so pulling needs no account and no login. Each example with a `Dockerfile` ships a `compose.image.yml` overlay that swaps the local build for the published image:
 
 ```sh
-docker pull ghcr.io/livepeer/runner-example-hello-world:latest
+cd hello-world
+docker compose -f compose.yml -f compose.image.yml up -d
 ```
 
+The base `compose.yml` always builds from source, so the registry is reached only when you ask for it by adding the overlay. It stacks with the on-chain one (`-f compose.yml -f compose.onchain.yml -f compose.image.yml`).
+
 > [!NOTE]
 > The images previously published under `rickstaa/` on Docker Hub are frozen; use the GHCR ones.
 

echo/compose.image.yml

@@ -0,0 +1,12 @@
+# Run the published image instead of building. Layer it on the offchain base:
+#   docker compose -f compose.yml -f compose.image.yml up -d
+#
+# The base file always builds from source, so this overlay is the only way to
+# reach the registry; `pull_policy: always` keeps a stale local copy from
+# shadowing the published one. Stacks with the on-chain overlay too:
+#   docker compose -f compose.yml -f compose.onchain.yml -f compose.image.yml up -d
+
+services:
+  app:
+    image: ghcr.io/livepeer/runner-example-echo:latest
+    pull_policy: always

hello-world/compose.image.yml

@@ -0,0 +1,12 @@
+# Run the published image instead of building. Layer it on the offchain base:
+#   docker compose -f compose.yml -f compose.image.yml up -d
+#
+# The base file always builds from source, so this overlay is the only way to
+# reach the registry; `pull_policy: always` keeps a stale local copy from
+# shadowing the published one. Stacks with the on-chain overlay too:
+#   docker compose -f compose.yml -f compose.onchain.yml -f compose.image.yml up -d
+
+services:
+  app:
+    image: ghcr.io/livepeer/runner-example-hello-world:latest
+    pull_policy: always

realtime-transcription/compose.image.yml

@@ -0,0 +1,12 @@
+# Run the published image instead of building. Layer it on the offchain base:
+#   docker compose -f compose.yml -f compose.image.yml up -d
+#
+# The base file always builds from source, so this overlay is the only way to
+# reach the registry; `pull_policy: always` keeps a stale local copy from
+# shadowing the published one. Stacks with the on-chain overlay too:
+#   docker compose -f compose.yml -f compose.onchain.yml -f compose.image.yml up -d
+
+services:
+  app:
+    image: ghcr.io/livepeer/runner-example-realtime-transcription:latest
+    pull_policy: always

tiles/compose.image.yml

@@ -0,0 +1,12 @@
+# Run the published image instead of building. Layer it on the offchain base:
+#   docker compose -f compose.yml -f compose.image.yml up -d
+#
+# The base file always builds from source, so this overlay is the only way to
+# reach the registry; `pull_policy: always` keeps a stale local copy from
+# shadowing the published one. Stacks with the on-chain overlay too:
+#   docker compose -f compose.yml -f compose.onchain.yml -f compose.image.yml up -d
+
+services:
+  app:
+    image: ghcr.io/livepeer/runner-example-tiles:latest
+    pull_policy: always