feat(setup): VERVAIN_SETUP_SCHEME/HOST/PORT/BIND_IP listener overrides #42

Merged

David merged 1 commit from feat/setup-listener-env into main

2026-06-06 03:25:31 +02:00

David commented

2026-06-06 03:18:24 +02:00

Owner

What

/setup was unreachable on a fresh deployment behind an http-upstream reverse proxy: setup mode requires config.json to be ABSENT, but without a config.json there is no settings.tls to switch the listener to plain HTTP, so the proxy's http upstream hit the TLS listener and surfaced a 500 (the TLS-alert-as-HTTP-response failure).

Four env vars now shape the listener while setup mode is active. They are honored ONLY while setup mode is active (VERVAIN_SETUP_ENABLE=true and no config.json) and ignored with an info log otherwise; once a config.json exists, config plus the long-term overrides (VERVAIN_TLS_MODE etc.) own the listener.

VERVAIN_SETUP_SCHEME: https (default) or http. With http the setup listener serves plain HTTP and the setup auto-login cookie drops the Secure flag, so onboarding works both through an https-terminating proxy and over a direct plain-HTTP browse.
VERVAIN_SETUP_HOST: hostname the operator browses to; replaces --cert-fqdn (default localhost) for the generated cert chain, server_name, and the WebAuthn origin.
VERVAIN_SETUP_PORT: listener port (default 15443).
VERVAIN_SETUP_BIND_IP: listener address (default 0.0.0.0).

Decisions baked in: an explicit --bind CLI flag still wins over PORT/BIND_IP (the more deliberate knob); malformed values fail the boot with a named-var error; the http setup listener skips the HTTP->HTTPS redirect listener like dev/offload modes do.

Typical Traefik onboarding: VERVAIN_SETUP_ENABLE=true + VERVAIN_SETUP_SCHEME=http, proxy upstream at http://<host>:15443, register the admin, write a config.json with settings.tls.mode = "offload", restart.

Verification

End-to-end smoke test against a fresh datapath with SCHEME=http PORT=18099 BIND_IP=127.0.0.1 HOST=setup.test: GET /api/setup 200, register 200 with non-Secure mc_session cookie + token, cert chain generated for setup.test, probe 404s once the first user exists, overrides logged at boot.
Six new unit tests for the env parsing (defaults, full set, case-insensitive scheme, blank-as-unset, trimming, bad-value rejection).
cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo build --all-targets, cargo test --lib, and cargo test -p meshcentral --bins all pass.

## What `/setup` was unreachable on a fresh deployment behind an http-upstream reverse proxy: setup mode requires config.json to be ABSENT, but without a config.json there is no `settings.tls` to switch the listener to plain HTTP, so the proxy's http upstream hit the TLS listener and surfaced a 500 (the TLS-alert-as-HTTP-response failure). Four env vars now shape the listener while setup mode is active. They are honored ONLY while setup mode is active (`VERVAIN_SETUP_ENABLE=true` and no config.json) and ignored with an info log otherwise; once a config.json exists, config plus the long-term overrides (`VERVAIN_TLS_MODE` etc.) own the listener. - `VERVAIN_SETUP_SCHEME`: `https` (default) or `http`. With `http` the setup listener serves plain HTTP and the setup auto-login cookie drops the `Secure` flag, so onboarding works both through an https-terminating proxy and over a direct plain-HTTP browse. - `VERVAIN_SETUP_HOST`: hostname the operator browses to; replaces `--cert-fqdn` (default `localhost`) for the generated cert chain, `server_name`, and the WebAuthn origin. - `VERVAIN_SETUP_PORT`: listener port (default 15443). - `VERVAIN_SETUP_BIND_IP`: listener address (default 0.0.0.0). Decisions baked in: an explicit `--bind` CLI flag still wins over `PORT`/`BIND_IP` (the more deliberate knob); malformed values fail the boot with a named-var error; the http setup listener skips the HTTP->HTTPS redirect listener like dev/offload modes do. Typical Traefik onboarding: `VERVAIN_SETUP_ENABLE=true` + `VERVAIN_SETUP_SCHEME=http`, proxy upstream at `http://<host>:15443`, register the admin, write a config.json with `settings.tls.mode = "offload"`, restart. ## Verification - End-to-end smoke test against a fresh datapath with `SCHEME=http PORT=18099 BIND_IP=127.0.0.1 HOST=setup.test`: `GET /api/setup` 200, register 200 with non-Secure `mc_session` cookie + token, cert chain generated for `setup.test`, probe 404s once the first user exists, overrides logged at boot. - Six new unit tests for the env parsing (defaults, full set, case-insensitive scheme, blank-as-unset, trimming, bad-value rejection). - `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, `cargo build --all-targets`, `cargo test --lib`, and `cargo test -p meshcentral --bins` all pass.

David added 1 commit

2026-06-06 03:18:24 +02:00

feat(setup): VERVAIN_SETUP_SCHEME/HOST/PORT/BIND_IP listener overrides

Check / fmt + clippy + build + tests (pull_request) Successful in 4m45s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

903f3430e6

A fresh deployment behind an http-upstream reverse proxy could not reach /setup: setup mode requires config.json to be absent, but without config.json there is no settings.tls to switch the listener to plain HTTP, so the proxy's http upstream hit the TLS listener and got a 500/TLS-alert. Four env vars now shape the listener while setup mode is active (and only then; they are ignored with an info log otherwise):

- VERVAIN_SETUP_SCHEME: "https" (default) or "http". http serves the setup listener over plain HTTP; the setup auto-login cookie drops the Secure flag so it works through an https-terminating proxy and over a direct plain-HTTP browse alike.
- VERVAIN_SETUP_HOST: hostname the operator browses to; replaces --cert-fqdn (default localhost) for the generated chain, server_name, and the WebAuthn origin.
- VERVAIN_SETUP_PORT: listener port (default 15443).
- VERVAIN_SETUP_BIND_IP: listener address (default 0.0.0.0).

An explicit --bind still wins over PORT/BIND_IP; malformed values fail the boot. Once a config.json exists, config plus the long-term overrides (VERVAIN_TLS_MODE etc.) own the listener again. The setup gating computation moved up in run_server so the overrides can feed the PKI, bind, and WebAuthn steps.

Verified end to end: with VERVAIN_SETUP_ENABLE=true VERVAIN_SETUP_SCHEME=http VERVAIN_SETUP_PORT=18099 VERVAIN_SETUP_BIND_IP=127.0.0.1 VERVAIN_SETUP_HOST=setup.test against a fresh datapath, GET /api/setup returns 200, register returns 200 with a non-Secure mc_session cookie and token, the cert chain generates for setup.test, and the probe 404s after the first user exists. Six new unit tests cover the env parsing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>