GRI-1937: setup wizard, setup mode and Settings screen #145

Merged
vivy merged 3 commits from feature/GRI-1937-setup-wizard into dev 2026-11-12 17:48:20 +00:00
Owner

Part 3 of the plan on GRI-1937 (document setup-wizard-plan): a first-run setup wizard and a Settings screen, so a non-technical admin can set the server up from the browser.

Server

  • Setup mode. With no database from any source, the server starts anyway and serves only the panel, /health, the setup status, the settings routes and two database routes. Every other /api/v1 path answers 503 setup_required. config.database is now optional; config.toml.example no longer sets a placeholder URL.
  • The panel's settings file (settings.file, default /var/lib/grimoire-signage/settings.toml, mode 0600). It sits between config.toml and the environment. The panel cannot write config.toml: /etc is read-only to the service under the systemd unit. A value set by an SIGNAGE_* variable is reported as environment and refused on write (setting_locked).
  • New env overrides: SIGNAGE_HTTP_PUBLIC_URL, SIGNAGE_SETTINGS_FILE, SIGNAGE_ENROLMENT_TRUSTED_PROXIES (comma list).
  • Routes: GET/PUT /api/v1/settings, POST /api/v1/server/restart, POST /api/v1/setup/database/test, POST /api/v1/setup/database. GET /setup/status adds database_configured.
  • A change applies on restart, done in place by exec of /proc/self/exe (same PID; works under systemd, Docker, Kubernetes and a shell). If exec fails, the process exits 75 and the supervisor restarts it.
  • The database test connects once and checks CREATE on public, the right a hand-made database most often lacks. Both database routes answer 409 once a database exists, so they cannot be used to make the server probe other hosts.
  • Who may call these routes: anybody while there is no database or no user, a signed-in user after that. This is the same first-run window in which POST /setup already lets anybody create the first admin.

Panel

  1. Reverse proxy? Yes: the proxy address(es), or "trust every address" with a warning. The HTTPS-only cookie is on (opt-out). No: the cookie is off (opt-in), plus a public address and the port. A changed port redirects the browser to the new port after the restart.
  2. Database: shown only in setup mode. Separate fields (no URL to build), the psql/createdb commands to create it, a test button, and save + restart.
  3. Admin account: the existing screen.

Settings (new nav entry) shows the same values with their source, locks environment-set values, saves, and offers "Restart now".

Installer

  • --native without PostgreSQL: pressing Enter at the URL question (or no terminal) now starts the server in setup mode, and the panel asks for the database. Before, the installer stopped with an error.
  • The database.env drop-in is optional (EnvironmentFile=-).
  • The final message points to the setup page.

Tested

  • cargo clippy --all-targets -D warnings, cargo fmt --check: clean.
  • cargo test -p server --include-ignored against Postgres: everything passes except two PDF tests. They need pdftoppm, which this build host does not have; CI does.
  • npm run check: 31 tests (new: proxy/no-proxy flow, trust-all warning, database step, Settings save + restart).
  • End-to-end with the real binary: setup mode → database test (bad and good password) → settings saved → database saved → in-place restart → migrations → admin created with a non-Secure cookie (the panel setting applied) → settings refuse an anonymous caller afterwards.

Not in this PR: the upgrade documentation per install type (item 4).

Part 3 of the plan on GRI-1937 (document `setup-wizard-plan`): a first-run setup wizard and a Settings screen, so a non-technical admin can set the server up from the browser. ## Server - **Setup mode.** With no database from any source, the server starts anyway and serves only the panel, `/health`, the setup status, the settings routes and two database routes. Every other `/api/v1` path answers `503 setup_required`. `config.database` is now optional; `config.toml.example` no longer sets a placeholder URL. - **The panel's settings file** (`settings.file`, default `/var/lib/grimoire-signage/settings.toml`, mode 0600). It sits between `config.toml` and the environment. The panel cannot write `config.toml`: `/etc` is read-only to the service under the systemd unit. A value set by an `SIGNAGE_*` variable is reported as `environment` and refused on write (`setting_locked`). - New env overrides: `SIGNAGE_HTTP_PUBLIC_URL`, `SIGNAGE_SETTINGS_FILE`, `SIGNAGE_ENROLMENT_TRUSTED_PROXIES` (comma list). - Routes: `GET/PUT /api/v1/settings`, `POST /api/v1/server/restart`, `POST /api/v1/setup/database/test`, `POST /api/v1/setup/database`. `GET /setup/status` adds `database_configured`. - **A change applies on restart**, done in place by `exec` of `/proc/self/exe` (same PID; works under systemd, Docker, Kubernetes and a shell). If `exec` fails, the process exits 75 and the supervisor restarts it. - The database test connects once and checks `CREATE` on `public`, the right a hand-made database most often lacks. Both database routes answer `409` once a database exists, so they cannot be used to make the server probe other hosts. - **Who may call these routes:** anybody while there is no database or no user, a signed-in user after that. This is the same first-run window in which `POST /setup` already lets anybody create the first admin. ## Panel 1. **Reverse proxy?** Yes: the proxy address(es), or "trust every address" with a warning. The HTTPS-only cookie is on (opt-out). No: the cookie is off (opt-in), plus a public address and the port. A changed port redirects the browser to the new port after the restart. 2. **Database:** shown only in setup mode. Separate fields (no URL to build), the `psql`/`createdb` commands to create it, a test button, and save + restart. 3. **Admin account:** the existing screen. **Settings** (new nav entry) shows the same values with their source, locks environment-set values, saves, and offers "Restart now". ## Installer - `--native` without PostgreSQL: pressing Enter at the URL question (or no terminal) now starts the server in setup mode, and the panel asks for the database. Before, the installer stopped with an error. - The `database.env` drop-in is optional (`EnvironmentFile=-`). - The final message points to the setup page. ## Tested - `cargo clippy --all-targets -D warnings`, `cargo fmt --check`: clean. - `cargo test -p server --include-ignored` against Postgres: everything passes except two PDF tests. They need `pdftoppm`, which this build host does not have; CI does. - `npm run check`: 31 tests (new: proxy/no-proxy flow, trust-all warning, database step, Settings save + restart). - End-to-end with the real binary: setup mode → database test (bad and good password) → settings saved → database saved → in-place restart → migrations → admin created with a non-Secure cookie (the panel setting applied) → settings refuse an anonymous caller afterwards. Not in this PR: the upgrade documentation per install type (item 4).
The server starts without a database and serves only the panel and the
setup routes. The panel writes its own settings file in the state
directory, between config.toml and the environment. A change applies
on restart, which the server does in place by exec of /proc/self/exe.
Step 1 asks whether a TLS reverse proxy is in front: with one, its
address (or trust all, with a warning) and the HTTPS-only cookie on as
an opt-out; without one, the cookie off as an opt-in, a public address
and the port. Step 2 asks for the database only in setup mode, shows
how to create it and tests it. Step 3 is the admin account. Settings
shows the same values, locks what the environment sets, and restarts
the server to apply a change.
GRI-1937: the setup status now says whether a database is configured
Some checks failed
CI / cargo fmt (pull_request) Successful in 11s
CI / the pre-push hook (pull_request) Successful in 12s
CI / cargo deny advisories (pull_request) Failing after 2m11s
CI / cargo deny (pull_request) Successful in 2m12s
CI / cargo clippy (pull_request) Successful in 2m49s
CI / repository boundary (pull_request) Successful in 48s
CI / frontend-web (pull_request) Successful in 1m44s
CI / cargo test (pull_request) Successful in 5m38s
CI / Notify gate failed (pull_request) Has been skipped
CI / CI (pull_request) Successful in 4s
fa1f208dcc
vivy merged commit 4f07342750 into dev 2026-11-12 17:48:20 +00:00
vivy deleted branch feature/GRI-1937-setup-wizard 2026-11-12 17:48:20 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Grimoirix/grimoire-of-digital-signage!145
No description provided.