docs: The release template ties deploy-vps to traefik, which sends readers to write a local action they do not need #78

New issue

Closed

opened 2026-09-09 18:18:41 +00:00 by ahmad · 1 comment

ahmad commented

2026-09-09 18:18:41 +00:00

Owner

Context

The header of templates/release.yml tells a reader to choose between two
deploy paths, and the distinction it draws is not the real one:

This template deploys with the shared deploy-vps action (a traefik VPS
host). For a host behind a reverse proxy on published ports, replace the
deploy step with your own local .forgejo/actions/deploy (see
ahmad/imamah).

That reads as: deploy-vps implies traefik; published ports behind a reverse
proxy imply writing your own action. Neither half holds.

deploy-vps does no routing at all. It copies docker-compose.vps.yml and
infra/alloy/config.alloy, writes the host .env, pulls and rolls out. What
routes traffic is whatever the compose declares — traefik labels, published
ports, or nothing.

ahmad/namey is the counter-example and it is deployed today: it uses
deploy-vps@v3 and publishes LAN ports (MARKETING_PUBLISH, PORTAL_PUBLISH)
for the fleet's nginx-proxy-manager edge to forward to. By this header's
advice its author should have written a local action, which would have been
work for nothing.

The apps host is behind nginx-proxy-manager, not traefik — the same claim was
corrected in ahmad/portfolio's documents on 2026-09-09, where three places
attributed routing to traefik and the compose header said the opposite.

The cost is not the wrong word. It is that the sentence sends a reader who is
behind a reverse proxy — which is every application on this fleet — away from
the shared action and toward maintaining their own, and a local deploy action
then diverges: ahmad/imamah's leaves COMPOSE_PROFILES empty on a partial
GRAFANA_PROM_* set where deploy-vps exits 1, so a half-configured deploy
succeeds silently without metrics.

Scope

In: the header comment block of templates/release.yml, and any other line
in this repository that ties deploy-vps to traefik or to a particular edge.
Out: deploy-vps's behaviour. Nothing about the action changes.
Out: the README.md sections for the other actions, unless they carry the
same claim.
Out: ahmad/imamah's local action, and whether it should be replaced.

Acceptance criteria

Given templates/release.yml, when its header is read, then it does not
state or imply that deploy-vps requires or assumes traefik.
Given that header, when it describes when to write a local deploy action,
then the reason given is one that actually distinguishes the two — not
the presence of a reverse proxy or of published ports.
Given a reader deploying behind nginx-proxy-manager with published ports,
when they follow the template, then they are pointed at deploy-vps and
an example that does the same (ahmad/namey).
Given this repository, when it is searched for "traefik", then every
remaining occurrence is accurate for the host it describes.

### Context The header of `templates/release.yml` tells a reader to choose between two deploy paths, and the distinction it draws is not the real one: > This template deploys with the shared `deploy-vps` action (a traefik VPS > host). For a host behind a reverse proxy on published ports, replace the > deploy step with your own local `.forgejo/actions/deploy` (see > `ahmad/imamah`). That reads as: `deploy-vps` implies traefik; published ports behind a reverse proxy imply writing your own action. Neither half holds. `deploy-vps` does no routing at all. It copies `docker-compose.vps.yml` and `infra/alloy/config.alloy`, writes the host `.env`, pulls and rolls out. What routes traffic is whatever the compose declares — traefik labels, published ports, or nothing. `ahmad/namey` is the counter-example and it is deployed today: it uses `deploy-vps@v3` and publishes LAN ports (`MARKETING_PUBLISH`, `PORTAL_PUBLISH`) for the fleet's **nginx-proxy-manager** edge to forward to. By this header's advice its author should have written a local action, which would have been work for nothing. The apps host is behind nginx-proxy-manager, not traefik — the same claim was corrected in `ahmad/portfolio`'s documents on 2026-09-09, where three places attributed routing to traefik and the compose header said the opposite. The cost is not the wrong word. It is that the sentence sends a reader who is behind a reverse proxy — which is every application on this fleet — away from the shared action and toward maintaining their own, and a local deploy action then diverges: `ahmad/imamah`'s leaves `COMPOSE_PROFILES` empty on a partial `GRAFANA_PROM_*` set where `deploy-vps` exits 1, so a half-configured deploy succeeds silently without metrics. ### Scope - In: the header comment block of `templates/release.yml`, and any other line in this repository that ties `deploy-vps` to traefik or to a particular edge. - Out: `deploy-vps`'s behaviour. Nothing about the action changes. - Out: the `README.md` sections for the other actions, unless they carry the same claim. - Out: `ahmad/imamah`'s local action, and whether it should be replaced. ### Acceptance criteria - [ ] Given `templates/release.yml`, when its header is read, then it does not state or imply that `deploy-vps` requires or assumes traefik. - [ ] Given that header, when it describes when to write a local deploy action, then the reason given is one that actually distinguishes the two — not the presence of a reverse proxy or of published ports. - [ ] Given a reader deploying behind nginx-proxy-manager with published ports, when they follow the template, then they are pointed at `deploy-vps` and an example that does the same (`ahmad/namey`). - [ ] Given this repository, when it is searched for "traefik", then every remaining occurrence is accurate for the host it describes.

ahmad added the

labels

2026-09-09 18:18:41 +00:00

ahmad self-assigned this

2026-09-09 19:17:41 +00:00

ahmad added

state/in-progress

and removed

state/ready

labels

2026-09-09 19:17:42 +00:00

ahmad commented

2026-09-09 19:17:42 +00:00

Author

Owner

Plan.

templates/release.yml's header is the only place that ties deploy-vps to traefik; README.md's deploy-vps section describes what the action does and does not make the claim. So this is a header rewrite plus a grep -i traefik sweep of the repository to satisfy the fourth criterion.

The replacement has to say something true about when a local deploy action is warranted, since removing the false reason leaves a gap. From the two live examples: deploy-vps copies docker-compose.vps.yml by that exact filename plus infra/alloy/config.alloy, writes the host .env from app-env, pulls and rolls out with a health check. A repository needs its own action when it cannot work that way — ahmad/imamah uses a different compose filename set and its own health-check strategy. Publishing ports is not a reason: ahmad/namey publishes MARKETING_PUBLISH / PORTAL_PUBLISH behind the nginx-proxy-manager edge and uses the shared action.

One ambiguity, resolved the safe way: I will not claim traefik is unused fleet-wide. suhba/suhba-docs runs on vps-production and its traefik labels are live and load-bearing. The header will say routing is the compose's business and name both shapes, rather than replacing one wrong edge with another.

templates/release.yml is also touched by the open #82 (the notify status: expression, ~line 311). This change is confined to the header comment block, so the two do not overlap; whichever lands second rebases cleanly.

Plan. `templates/release.yml`'s header is the only place that ties `deploy-vps` to traefik; `README.md`'s `deploy-vps` section describes what the action does and does not make the claim. So this is a header rewrite plus a `grep -i traefik` sweep of the repository to satisfy the fourth criterion. The replacement has to say something true about *when* a local deploy action is warranted, since removing the false reason leaves a gap. From the two live examples: `deploy-vps` copies `docker-compose.vps.yml` by that exact filename plus `infra/alloy/config.alloy`, writes the host `.env` from `app-env`, pulls and rolls out with a health check. A repository needs its own action when it cannot work that way — `ahmad/imamah` uses a different compose filename set and its own health-check strategy. Publishing ports is not a reason: `ahmad/namey` publishes `MARKETING_PUBLISH` / `PORTAL_PUBLISH` behind the nginx-proxy-manager edge and uses the shared action. One ambiguity, resolved the safe way: I will not claim traefik is unused fleet-wide. `suhba/suhba-docs` runs on `vps-production` and its traefik labels are live and load-bearing. The header will say routing is the compose's business and name both shapes, rather than replacing one wrong edge with another. `templates/release.yml` is also touched by the open #82 (the notify `status:` expression, ~line 311). This change is confined to the header comment block, so the two do not overlap; whichever lands second rebases cleanly.

ahmad referenced this issue from a pull request that will close it,

2026-09-09 19:19:10 +00:00

docs: Stop tying deploy-vps to a traefik edge #83

ahmad

2026-09-09 19:19:11 +00:00