felipefontoura/bento/sgtm

You operate the sgtm stack on a bento VPS: Google's gtm-cloud-image as a tagging service (sgtm_sgtm_tagging) and a preview service (sgtm_sgtm_preview). Day-2 work only: redeploys go through /bento:deploy. The full reference — modes, proxy recipes, GTM wiring, troubleshooting — is docs/reference/sgtm.md in the bento repo (on the VPS: ~/.local/share/bento/docs/reference/sgtm.md). When this skill and that doc disagree, the doc wins.

Never print secrets. SGTM_PROXY_KEY, SGTM_CONTAINER_CONFIG and

SGTM_GCP_SA_JSON_B64 stay on the VPS: use them inside commands, never echo

them into the chat, a file you show, or a screenshot.

When to invoke

• "is my sGTM up / check the tagging server", "show sGTM logs"
• "Tag Assistant keeps waiting", "/g/collect returns 404", "Meta gets the wrong IP"
• "set up the proxy for sGTM", "use sGTM without a proxy (direct mode)"
• "rotate the sGTM key", "update sGTM", "let sGTM write to BigQuery"

Discover the instance — don't hardcode

ssh "$user@$host" "jq -r '.envs.sgtm.SGTM_HOST'          \$HOME/.config/bento/state.json"
ssh "$user@$host" "jq -r '.envs.sgtm.SGTM_PREVIEW_HOST'  \$HOME/.config/bento/state.json"
ssh "$user@$host" "jq -r '.envs.sgtm.SGTM_DIRECT_MATCH // \"(proxy only)\"' \$HOME/.config/bento/state.json"

Know the mode before anything else:

• Proxy mode (always on): the site forwards https://<site>/<path> to

https://<SGTM_HOST> with X-Sgtm-Key and the visitor in Forwarded. Without the key, Traefik answers 404.

• Direct mode (only if SGTM_DIRECT_MATCH is set): browsers call

https://<SGTM_HOST> themselves; the visitor IP is Traefik's X-Forwarded-For.

Health

ssh "$user@$host" "docker service ls --filter name=sgtm_ --format '{{.Name}} {{.Replicas}}'"   # both 1/1
curl -s "https://<SGTM_PREVIEW_HOST>/healthy"                                                  # ok
ssh "$user@$host" 'curl -s -H "X-Sgtm-Key: $(jq -r .envs.sgtm.SGTM_PROXY_KEY ~/.config/bento/state.json)" https://$(jq -r .envs.sgtm.SGTM_HOST ~/.config/bento/state.json)/healthy'   # ok
curl -s -o /dev/null -w '%{http_code}\n' "https://<site>/<path>/g/collect?v=2"                 # 400 = proxy → sGTM works

Logs: docker service logs -f --tail 100 sgtm_sgtm_tagging (tag errors, Listening on). Restarts: docker service ps --no-trunc sgtm_sgtm_tagging.

Common tasks

Publishing in GTM needs nothing on the VPS: the tagging server polls for the published version.

Gotchas

• 404 on the site path is almost always the key: compare the proxy's

secret with SGTM_PROXY_KEY (inside a command, not by printing both).

• Wrong visitor IP (datacenter or 10.x): in proxy mode the proxy isn't

sending Forwarded; in direct mode something sits in front of Traefik (Cloudflare orange cloud). Check in the server container's Tag Assistant → request headers and event data ip_override.

• Preview host must be HTTPS and reachable, and the Server container URL

in GTM must be the URL browsers use (the proxy path in proxy mode).

• amd64 only: no ARM image from Google.
• One sGTM per VPS (stack key sgtm).
• **Never test by pointing a copy of the production container at real

vendors** (e.g. a local run with a production config): tags send real events to Meta/GA4. Test with Preview, or on a network where vendor hosts resolve to a mock.

Report back

• Mode, both services' replicas, the /healthy and site-path checks.
• What you changed and that a hit went through (Tag Assistant or logs).

Upstream: Manual setup guide, sGTM APIs.