feat(hosting): meet DigitalOcean's build standard, and write the catalog copy (#2281)

[obasilakis]

What

DigitalOcean enabled our Vendor Portal account and pointed at
digitalocean/marketplace-partners as the process of record. Auditing the bundle
against that repo — and against droplet-1-clicks@master, where their own build
standard and catalog apps live — found four gaps. Three are fixed here; the
fourth needs a measurement only the DO account can give.

The bundle already matched DO on everything with a stated requirement: vendored
cleanup.sh + img_check.sh (pinned at b708788, which is master HEAD),
per-instance boot hook, 99- MOTD, password generated at boot, Caddy with
profile shortlived. These are the gaps.

1. The build installed no security updates

Their 99-img-check.sh (lines 438–454) scores a pending security update as a
hard [FAIL], not a warning:

uc=$(apt-get --just-print upgrade | grep -i "security" -c)
[FAIL] There are ${update_count} security updates available for this image
((FAIL++)); STATUS=2

Any FAIL exits non-zero, which fails the build — at the last provisioner,
furthest from the cause, reading as a flake.

01-provision.sh ran apt-get update and targeted installs, never an upgrade.
So the 2026-09-03 build passed on luck: either DO's base image was current that
day, or Ubuntu's boot-time unattended-upgrades timers landed before Packer's
SSH session. Neither is ours to own.

Adds the full-upgrade from their reference marketplace-image.json, with their
--force-confdef/--force-confold flags, placed before the first install so
the packages we add are patched too — and before the Caddy repo is added, so the
caddy=2.11.4 pin is untouched.

2. X-DO-MARKETPLACE was missing

Rule 10 of droplet-1-clicks/.github/agents/1-click-agent.md specifies this
header on the reverse-proxy block, and their live catalog ships it — openclaw's
Caddyfile sets it to "openclaw". Our first-boot Caddyfile had the
tls/issuer acme/profile shortlived half and not this line.

It breaks nothing at runtime, which is exactly why it survived review: it is
visible only to a Marketplace reviewer.

3. There was no listing.md

Rule 11 asks for the catalog copy in-repo, so the page and the image are
versioned together. Ours lived nowhere — README.md here is a builder document
for us, not customer-facing copy.

listing.md is also where two acceptance criteria on #2281 finally get written
down: the ≥8 GB sizing recommendation, and the vendor-terms-required statement
that DigitalOcean does not build or support Trinity. Content is checked against
what the droplet actually does — the MOTD's Console-based password path, the
#cloud-config write_files override, the same-disk caveat on our automatic
backups.

4. Submission is now automatable, and the runbook gained the state that blocks it

Their README documents the update path we had only half-recorded. Adds
scripts/mp-submit.sh plus manifest + shell-local post-processors: the
snapshot id is read from the build's own record and PATCHed to
/api/v1/vendor-portal/apps/<app_id> with the real payload — imageId
(required), reasonForUpdate, osVersion, softwareIncluded[].

A post-processors chain block, not two sibling post-processor blocks:
siblings run in parallel and the submit would race the manifest file it reads.
That is a race which passes on a fast disk and fails on a release day.

mp-submit.sh is a no-op unless TRINITY_DO_APP_ID is set, so a plain
packer build still just builds. It names the two API states worth
recognising — notably 400, meaning the app is still pending/in review and
cannot be updated, which otherwise reads as a bad token on release day.

The runbook also gains a submission gate: nothing goes to DigitalOcean until
another team member has QA'd a droplet from that snapshot. A green img_check
says the image is acceptable, not that Trinity works on it.

build_size: 80 GB boot disk → 50 GB

Fixed here after all, in e7687f3c8 and 9cd6cdfd4 — this section previously
said it was deliberately left alone, which is no longer true.

build_size was s-2vcpu-4gb (80 GB disk), under a comment reading "DO's own
guidance builds on the smallest size" — the comment and the value contradicted
each other.

The build droplet's CPU and RAM never reach the snapshot: a snapshot is a disk
image, and Trinity never runs during the build (01-provision.sh installs and
pulls; start.sh runs at first boot on the customer's droplet). The one property
that propagates is the disk size, and DO does not allow shrinking it — "You
can increase the boot disk size when resizing, but you cannot decrease it."

So 80 GB excluded every plan with a smaller boot disk — not just the cheap tiers:
on DO's v5 line disk is decoupled from memory, and s5-8vcpu-16gb-30gb is 8 vCPU
and 16 GiB RAM on a 30 GiB disk, exactly the plan a Trinity operator should
pick, and that snapshot could not deploy to it. Measured against the snapshot the
build actually produces: trinity-v0-9-5-rc2-20260903, min disk 80, size 9.01
GiB. The 80 GB floor came entirely from the build droplet's own disk, so every
customer was pushed onto an 80 GB boot disk, and paying for it, to hold 9 GiB.

Now s-1vcpu-2gb (50 GB). A droplet booted from the 2026-09-10 snapshot reports
/dev/vda1 77G 8.8G 68G 12% / — 8.8 GB with everything installed and Trinity
running. An earlier justification for 50 GB assumed Docker's uncompressed
overlay2 tree would reach 18-20 GB and called 25 GB too tight; that was a guess
dressed as a reason and it was wrong by more than a factor of two. The value is
unchanged by the correction — 50 GB is also what three of DigitalOcean's own
catalog apps build on (openclaw, jellyfin, craftcms) — but the stated reason is
now the measurement.

Still open, and named in the ponytail: marker: 25 GB is settled on disk;
the remaining question is whether 1 GB of RAM survives apt full-upgrade and
docker pull, which is what standing on DO's recommended s-1vcpu-1gb would
require. Their own exa-24-04 builds on that size. One experimental build
settles it.

Tests

tests/unit/test_2281_marketplace_build_standard.py, four guards, each
mutation-checked — reverting exactly one fix turns exactly one guard red,
verified against the committed baseline:

• full-upgrade present and positioned before the first install (an upgrade
  afterwards leaves our own packages unpatched and still fails img_check)
• X-DO-MARKETPLACE present inside the Caddyfile heredoc, not merely
  somewhere in the script
• the submit post-processor is in a post-processors chain with manifest
  ordered first
• the no-op default is executed, not pattern-matched (the fix(packer): make the DigitalOcean 1-Click bundle actually buildable (#2281) #2522 precedent — a
  static rule only knows the spelling it was written against): the script is run
  with a clean environment in an empty directory and must exit 0

All 24 tests in the 2281 suite pass.

Not verified

• packer build has not been re-run against these changes; no DO token in this
  session. The full-upgrade lengthens the build.
• Whether Packer's DO builder and Marketplace review accept v5 sizes, which the
  build_size decision will need.

Related to #2281. Does not close it — the Vendor Portal submission is a
human-gated step, now explicitly behind the QA gate above.

🤖 Generated with Claude Code

https://claude.ai/code/session_011sj48trT3XmyaSus4GUtXB

[vybe]

merge-train 2026-09-10: on this train. No commits pushed to your branch — it was already current with dev. One mechanical edit to the PR body, which matters more than usual here because on squash it becomes the permanent commit message.

What I changed and why. The body carried a section headed "Still open: build_size — Not fixed here, and deliberately so… build_size is s-2vcpu-4gb". The diff says otherwise: trinity.pkr.hcl:131 now reads s-1vcpu-2gb, changed in e7687f3c8 and re-justified in 9cd6cdfd4, both authored after the body was written. Merging as-was would have written a permanent record describing the opposite of what shipped. I replaced that section with prose assembled from your own two commit messages — the 9.01 GiB snapshot measurement, the "cannot decrease a boot disk" constraint, the s5-8vcpu-16gb-30gb exclusion, the corrected /dev/vda1 77G 8.8G reading superseding the 18-20 GB guess, and the still-open 1 GB RAM question named in the ponytail: marker. No new claims, nothing removed but the contradiction.

The coverage answer, proven rather than asserted. test_2281_marketplace_build_standard.py is three-quarters source-text. Two mutations that break the feature completely while leaving the spelling intact:

mutation	real effect	test result
whole apt-get … full-upgrade block → echo "full-upgrade"	no security updates installed — the exact img_check FAIL this PR exists to prevent	4 passed
comment out header X-DO-MARKETPLACE "trinity" in the Caddyfile heredoc	header never sent, Rule 10 unmet	4 passed

Your mutation claim does hold at the text level — I reproduced all four, and each reverts exactly one guard to red. The guards discriminate spelling, and only spelling. The one genuine execution is test_submit_script_is_a_noop_without_an_app_id, which really does subprocess.run(["bash", …]) — correct, and the right application of the #2522 precedent — but it exercises only the 6-line guard clause at mp-submit.sh:21-26 and returns before jq, curl, or the API.

And nothing else runs it either: grep -rE "packer (build|validate|fmt)" .github/ scripts/ → zero hits; container-security.yml is path-filtered on docker/** and friends, and packer/** is not in its filter; no shellcheck, no bash -n anywhere. Worth knowing the pattern already exists in your own suite — test_2281_firstboot_password.py extracts the generator block and runs it under bash.

The two riskiest changes are the two with zero execution anywhere — apt-get full-upgrade and halving the build droplet to 1 vCPU / 2 GB. The 77G measurement came from the old 80 GB build, so nothing has been built at s-1vcpu-2gb; your own HCL comment flags RAM as the open risk. One packer build closes both. That's an accept-or-build call for you before the image is actually built and submitted — it does not block landing on dev, since publishing is a separate human-gated step.

Smaller findings, none fixed by me:

• strip_path = true (trinity.pkr.hcl:214) is set and read by nothing — it affects only the manifest's files[] array, while mp-submit.sh reads .builds[-1].artifact_id, and the DO builder produces no local files. Doubly inert.
• mp-submit.sh:41 — the comment documents a -f that isn't there, and adding it would break the feature: under set -euo pipefail, curl -f would kill the process before the 400/403 explanation branch at :56-62, deleting the exact release-day diagnostic this PR adds. The code is right; the comment instructs the next maintainer to break it.
• mp-submit.sh:47 — no --max-time/--connect-timeout; a hung DO API hangs the post-processor after the snapshot is created and paid for.
• mp-submit.sh:36 — the "could not read a snapshot id" branch is unreachable: null | split(":") makes jq exit non-zero, and under set -e the assignment aborts first, so the friendly message never prints.
• split(":")[1] encodes an assumption about DigitalOcean's artifact_id shape that nothing in the repo verifies, inside the one path nothing executes.
• README.md:96-98 asks for the same token under two names — DIGITALOCEAN_API_TOKEN=… then -var "do_token=$DIGITALOCEAN_TOKEN". A literal copy-paste yields do_token="", in a release-day runbook.
• feat: DigitalOcean Marketplace 1-Click Droplet listing for Trinity (vendor application + Packer snapshot, AI Agents category) #2281's AC says build on s-1vcpu-1gb and record the measured size; the delivered value diverges for a reason the AC doesn't contemplate (RAM, not disk), and that reasoning lives only behind a ponytail: marker — grep -rn ponytail across the whole repo returns exactly that one line, so it isn't a convention anything will resurface. feat: DigitalOcean Marketplace 1-Click Droplet listing for Trinity (vendor application + Packer snapshot, AI Agents category) #2281's body also still says "currently s-2vcpu-4gb", now stale in the opposite direction.

Outward-facing check: clean. No credential, internal URL, IP, or real email enters any file that ships in the image or the listing. mp-submit.sh never echoes the bearer token. I also verified the listing's update path against the bundle's shallow --depth 1 --branch clone end-to-end with a synthetic 3-tag repo — git fetch --tags && git checkout <tag> works — and confirmed the component list, DOCKER-USER rules, MOTD, and Apache-2.0 LICENSE all match reality.

Correctly left with no closing keyword — "Related to #2281. Does not close it" is right, and #2281 already carries status-in-progress.

One process note that isn't about your PR: the merge-train lane classifier triggers deep review on ^docker/ and has never heard of packer/, so a change that rebuilds a public marketplace image classified as ordinary lane B. That's the classifier being stale, and I'm filing it separately.

[vybe]

merge-train: batch validated on train/20260910-1327 (#2686), 32 checks green across all five members together.