Fediversity Panel

Feature Specification: Service deployment

Created: 2026-09-23

Status: Implemented

Input: Reconstructed from the code of panel/ at 0bf4ecd36, the documentation of the panel, pull requests #1105, #1182, #1650, #1659, #1714, #1730, #1766, #1815, #1893, #1901 and #1902, and the design notes of the maintainers.

User Scenarios & Testing (mandatory)

User Story 1 - Run the panel as a NixOS service (Priority: P1)

A hosting provider enables the NixOS module of the panel, and sets the domain, the address of api, the secrets, and optionally the identity provider and the address of the event service (Centrifugo) of api. The module runs the panel behind nginx, prepares the static files, applies the database migrations, and gives the administrator a management command. The panel reads its settings from its environment, and the module can add framework settings that replace the defaults.

Why this priority: this is how a hosting provider runs the panel.

Independent Test: a VM test where the panel answers on its domain and an administrator logs in, and unit tests of the runtime settings.

Acceptance Scenarios:

  1. Given the module with a domain, When the machine starts, Then the panel answers on the domain through nginx.
  2. Given a production setup, When the machine starts, Then nginx redirects HTTP to HTTPS and serves the panel over TLS, with the certificate that the SSL resource of the component gives.
  3. Given a changed client secret of the identity provider, When the secret changes, Then the panel restarts and uses the new secret.
  4. Given a database address, When the panel starts, Then the panel uses that database. Without it, the panel uses SQLite in its state directory.
  5. Given extra framework settings, When the panel starts, Then they replace the defaults.
  6. Given that the secret key of the panel is missing, When the panel starts, Then the panel stops with an error.

User Story 2 - Develop and check the panel (Priority: P2)

A developer enters the development shell, runs the panel against a local api, and runs the checks. The checks cover the server tests, the browser tests, the migrations, the formatting, the documentation, the database diagram, a basic VM test, and an end-to-end VM test with api.

Independent Test: each check of the panel.

Acceptance Scenarios:

  1. Given a change of the data model without a migration, When the migration check runs, Then the check fails.
  2. Given the documentation, When it builds, Then it includes the options of the module, the user guide for operators and the screenshots.

User Story 3 - Choose a light or dark theme (Priority: P3)

The operator switches between the light and the dark theme with one control. The page follows the preference of the system until the operator chooses.

Independent Test: a unit test of the theme control.

Acceptance Scenarios:

  1. Given a first visit, When the page opens, Then it follows the preference of the system.
  2. Given a choice of the operator, When the operator opens another page, Then the choice stays.

Edge Cases

  • The identity provider uses a private CA: the component gives the CA bundle to the panel.
  • Centrifugo is on a different subdomain: the session cookie must reach both hosts. When the host of Centrifugo is below the domain of the panel, the cookie is limited to the domain of the panel, so other hosts of the parent domain do not get it.
  • The browser address of api is not set: the browser calls api on the host of the panel.

Requirements (mandatory)

Functional Requirements

  • FR-001: The plain Nix entry point of the panel MUST give all outputs. The flake MUST only add the per-system layer.
  • FR-002: The NixOS module MUST take the address of api, the identity provider, the event service and the secrets as configuration.
  • FR-003: The panel MUST read its secrets from files or systemd credentials, never from the Nix store.
  • FR-004: The panel MUST apply the database migrations before it serves requests.
  • FR-005: The documentation MUST describe the current options of the module.
  • FR-006: The documentation MUST include a user guide that tells an operator how to deploy, use, change and remove a deployment.
  • FR-007: The screenshots of the documentation MUST come from the UI that the revision builds. The capture MUST seed api only through its HTTP API. A fake job runner behind api reports each deploy as a success, so the pages show a deployed state while nothing is built.

Key Entities

  • NixOS module: the service module of the panel, which a hosting provider can use on its own.
  • Component: the wiring of the panel into a group of the hosting provider.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: A hosting provider can run the panel with the module and its own identity provider, api and event service, without the component.
  • SC-002: All checks of the panel pass on each pull request that changes the panel.

Assumptions

  • api and Centrifugo run as separate services that the module can reach by address.

Known Deviations

None.