From df1e3c68838f16571d0f1ef211500c60c3fce20a Mon Sep 17 00:00:00 2001
From: ErenAri <erenari27@gmail.com>
Date: Fri, 19 Jun 2026 14:32:44 +0300
Subject: [PATCH] Document deploying the git-ignored aegis sample artifact

The "Try our aegis sample" button serves examples/aegis-live/aegis.bpf.o,
which is git-ignored, so a fresh server checkout 404s on
/api/v1/sample/aegis/artifact. Document copying the object out-of-band to a
persistent path and pointing BPFCOMPAT_SAMPLE_ARTIFACT at it (runbook step 1b
+ env example), so re-provisioning keeps the sample working.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/hetzner-runbook.md                       | 23 +++++++++++++++++++
 packaging/systemd/bpfcompat-serve.env.example |  6 +++++
 2 files changed, 29 insertions(+)

diff --git a/docs/hetzner-runbook.md b/docs/hetzner-runbook.md
index f43f675..ab06c92 100644
--- a/docs/hetzner-runbook.md
+++ b/docs/hetzner-runbook.md
@@ -35,6 +35,29 @@ export HETZNER_HOST=<server-ip>
 make hetzner-bootstrap-vm
 ```
 
+## 1b) Install the "Try our aegis sample" artifact
+
+The empty-state **"Try our aegis sample"** button serves
+`examples/aegis-live/aegis.bpf.o`. That object is **git-ignored** (we never
+commit built `.bpf.o`s), so a fresh checkout does not contain it and the
+`/api/v1/sample/aegis/artifact` endpoint 404s until you copy it out-of-band.
+
+Copy the sample to a path that survives re-provisioning (the state dir is not
+wiped by re-clones) and point the server at it via `BPFCOMPAT_SAMPLE_ARTIFACT`:
+
+```bash
+scp examples/aegis-live/aegis.bpf.o \
+  root@$HETZNER_HOST:/var/lib/bpfcompat-demo/sample-aegis.bpf.o
+ssh root@$HETZNER_HOST '
+  chown bpfcompat-demo:bpfcompat-demo /var/lib/bpfcompat-demo/sample-aegis.bpf.o
+  chmod 0644 /var/lib/bpfcompat-demo/sample-aegis.bpf.o
+  grep -q "^BPFCOMPAT_SAMPLE_ARTIFACT=" /etc/bpfcompat/serve.env \
+    && sed -i "s|^BPFCOMPAT_SAMPLE_ARTIFACT=.*|BPFCOMPAT_SAMPLE_ARTIFACT=/var/lib/bpfcompat-demo/sample-aegis.bpf.o|" /etc/bpfcompat/serve.env \
+    || echo "BPFCOMPAT_SAMPLE_ARTIFACT=/var/lib/bpfcompat-demo/sample-aegis.bpf.o" >> /etc/bpfcompat/serve.env'
+```
+
+(If the unit is already running, `systemctl restart bpfcompat-serve` after.)
+
 ## 2) Set the write key and start the demo server
 
 The server binds `127.0.0.1:8080` only. Anonymous visitors may validate and read
diff --git a/packaging/systemd/bpfcompat-serve.env.example b/packaging/systemd/bpfcompat-serve.env.example
index 64a1c2b..ee50fcb 100644
--- a/packaging/systemd/bpfcompat-serve.env.example
+++ b/packaging/systemd/bpfcompat-serve.env.example
@@ -21,6 +21,12 @@ BPFCOMPAT_API_REDACT_RUNTIME_DETAILS=true
 # Do not mirror demo runs into a cloud registry.
 BPFCOMPAT_API_AUTO_SYNC_REGISTRY=false
 
+# Path to the bundled "Try our aegis sample" artifact. The default
+# (examples/aegis-live/aegis.bpf.o, relative to WorkingDirectory) is git-ignored,
+# so on a fresh deployment copy the object out-of-band and point this at it (see
+# docs/hetzner-runbook.md step 1b). Leave unset to use the in-repo default.
+BPFCOMPAT_SAMPLE_ARTIFACT=/var/lib/bpfcompat-demo/sample-aegis.bpf.o
+
 # Note: the run tree location is set via the --workdir flag in the unit's
 # ExecStart (/var/lib/bpfcompat-demo), not an env var. .bpfcompat/runs/** under
 # it holds per-run SSH keys, so it must stay inside the state dir only.