refactor: drop proxy-supports-routes capability trigger

The trigger was added to refuse proxy:route:set under openresty and haproxy, but the hard refusal created an ordering dependency for declarative tools and blocked users from staging routes ahead of a backend switch. Routes are now stored regardless of the active backend and silently ignored by backends that do not render them; the docs call out the inert behavior under openresty and haproxy.
This commit is contained in:
Jose Diaz-Gonzalez committed 2026-11-04 14:56:38 -05:00
1 parent 9153bb5097
commit a4d40becd8
11 files changed
+8 -167

No files matched your search

-21
View File
@@ -2390,27 +2390,6 @@ while IFS='|' read -r proc port path strip; do
done < <(plugn trigger proxy-routes-list "$APP")
```
### `proxy-supports-routes`
- Description: Returns `true` if the proxy backend currently selected for the app supports path-based routes (`proxy:route:set`), `false` otherwise. Implemented by each in-tree proxy plugin (nginx, traefik, caddy, and k3s return `true`; openresty and haproxy return `false`). The `proxy:route:set` command calls this trigger and refuses with a "not supported" message when the result is `false`.
- Invoked by: `proxy:route:set` in the `proxy` plugin
- Arguments: `$APP`
- Example:
```shell
#!/usr/bin/env bash
set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
APP="$1"
if [[ "$(plugn trigger proxy-type "$APP")" != "my-proxy" ]]; then
return
fi
echo "true"
```
### `proxy-type`
- Description: Returns the proxy type for an app
+2 -1
View File
@@ -196,7 +196,7 @@ See the [port management documentation](/docs/networking/port-management.md) for
By default, every HTTP/HTTPS request is routed to the `web` process declared in the app's `Procfile`. Use `proxy:route:*` to route specific path prefixes to a different process within the same app - for example, sending `/api/v0/*` to an `api` process or `/ws` to a `websocket` process. The `web` process always handles every other path as an implicit catch-all.
> [!NOTE]
> Path-based routing is supported by the `nginx`, `traefik`, `caddy`, and `k3s` proxy backends. The `openresty` and `haproxy` backends do not currently support it; `proxy:route:set` exits with a "not supported" message under those backends. Support is tracked in [dokku/openresty-docker-proxy#137](https://github.com/dokku/openresty-docker-proxy/issues/137) and the `haproxy-vhosts` sidecar.
> Path-based routing is rendered by the `nginx`, `traefik`, `caddy`, and `k3s` proxy backends. The `openresty` and `haproxy` backends accept and store route declarations, but the routes are inert (no labels are emitted) because the sidecar images do not yet support path-prefix vocabulary. Routes stored ahead of a backend switch will activate automatically once the proxy is changed to a rendering backend. Tracked at [dokku/openresty-docker-proxy#137](https://github.com/dokku/openresty-docker-proxy/issues/137) and the `haproxy-vhosts` sidecar.
#### Adding a route
@@ -273,6 +273,7 @@ dokku proxy:route:set node-js-app api /api/v0/admin
- **nginx**: route changes take effect immediately on the next `proxy-build-config` reload (which `proxy:route:*` invokes automatically).
- **traefik** and **caddy**: routes are applied via Docker labels on the target containers. Containers must be recreated for new or removed labels to take effect. The command prints a notice instructing you to run `dokku ps:rebuild <app>` to recreate containers.
- **k3s**: route changes take effect on the next deploy when the chart is re-rendered.
- **openresty** and **haproxy**: routes are stored but inert under these backends. They activate automatically if you switch to a rendering backend (`nginx`, `traefik`, `caddy`, or `k3s`).
- **WebSocket** traffic is forwarded transparently on `nginx`, `traefik`, `caddy`, and `k3s` backends - no additional configuration is required.
- A route to a process that is scaled to `0` will resolve to no upstream until the process is scaled up (`dokku ps:scale <app> <process>=1`). `proxy:route:set` warns when this is the case.