examples/compose.pangolin.yml is stale (wrong env names, wrong Pangolin label prefix)

[strausmann]

Problem

`examples/compose.pangolin.yml` was last updated 2026-05-10 and has accumulated bit-rot. When used as a copy-paste template for a hhdocker02 production deploy (2026-05-17), the file caused two distinct failure modes — both silent.

Concrete issues

1. Wrong env var names

The compose uses bare names but the backend reads the `PRINTER_HUB_` prefix everywhere:

compose.pangolin.yml (wrong)	actual env var (Settings)
`PRINTERS`	`PRINTER_HUB_PRINTERS`
`SNMP_COMMUNITY`	`PRINTER_HUB_PRINTER_SNMP_COMMUNITY`
`DATABASE_URL`	`PRINTER_HUB_DATABASE_URL`
`WEBHOOK_API_KEY`	`PRINTER_HUB_WEBHOOK_API_KEY`
`UI_BASE_URL`	(no such setting; remove)

Result: backend starts with defaults (mock printer, no webhook auth, default DB path) and the user never sees a config-time error.

2. Wrong Pangolin blueprint label prefix

```yaml

• "pangolin.resources.printerhub.protocol=https" # WRONG
  ```

The correct prefix is `pangolin.public-resources.` per Pangolin Blueprints docs. The `pangolin.resources.` prefix is silently ignored by Newt — no warning, no error, the resource just never registers.

3. Missing required label fields

The current labels omit:

• `pangolin.public-resources..ssl=true`
• `pangolin.public-resources..targets[0].method=http`
• `pangolin.public-resources..targets[0].path-match=prefix`

Without these, Newt rejects the resource (when prefix is fixed in #2).

4. `protocol` should be `http` not `https`

The frontend container speaks plain HTTP on port 8080; SSL termination happens at the Pangolin edge. With `ssl=true` set, traffic stays end-to-end encrypted from client to Pangolin and from Pangolin to Traefik — only the last hop into the container is HTTP.

5. Network name + alias missing

```yaml
networks:
pangolin-newt: # WRONG — name depends on deployer's compose project
external: true
```

The actual Pangolin management network in our environment is `pangolin_pangolin_mgmt`. The robust form is:

```yaml
networks:
pangolin_mgmt:
name: pangolin_pangolin_mgmt
external: true
```

This works regardless of where Pangolin is deployed because the alias decouples local service-name from network-name.

6. "Restart pangolin-newt" comment can mislead users with managed Docker

```yaml

After deploy, restart the newt container so blueprint labels are reloaded:

docker restart pangolin-newt

```

Users running Pangolin under any management UI (Portainer, Dockhand, etc.) should use that UI's restart action rather than bypassing it with raw `docker`. Suggest rewording to a neutral "reload via your container management tool".

Verified working compose

The compose that successfully registered the resource on hhdocker02:

```yaml
services:
frontend:
labels:
- "pangolin.public-resources.label-printer-hub.name=Label Printer Hub"
- "pangolin.public-resources.label-printer-hub.full-domain=labels.strausmann.cloud"
- "pangolin.public-resources.label-printer-hub.protocol=http"
- "pangolin.public-resources.label-printer-hub.ssl=true"
- "pangolin.public-resources.label-printer-hub.targets[0].method=http"
- "pangolin.public-resources.label-printer-hub.targets[0].port=8080"
- "pangolin.public-resources.label-printer-hub.targets[0].path-match=prefix"
- "pangolin.public-resources.label-printer-hub.auth.sso-enabled=true"
networks:
pangolin_mgmt:
name: pangolin_pangolin_mgmt
external: true
```

A patchmon stack in the same environment was used as a reference for the working label syntax.

Suggested changes

1. Fix all env var names to include `PRINTER_HUB_` prefix
2. Switch label prefix to `pangolin.public-resources.*`
3. Add `ssl=true`, `targets[0].method=http`, `targets[0].path-match=prefix`
4. Change `protocol=https` → `protocol=http`
5. Use the alias-network pattern for `pangolin_pangolin_mgmt`
6. Replace the `docker restart` comment with a neutral "reload via your container management tool" note
7. Add the second resource for `webhooks` (`auth.bypass=true` + `path-prefix=/api/webhook/`) — already documented in the file's header comment but not actually in the labels

Out of scope for this issue: webhook resource implementation will land in a follow-up since it touches more than just the example.

Acceptance criteria

• `examples/compose.pangolin.yml` deploys cleanly against a stock Pangolin instance
• All env vars match the `PRINTER_HUB_*` naming in `app/config.py`
• Pangolin resource auto-registers within 60s of deploy
• `examples/.env.example` env names match

Refs #22