Fediversity

Fediversity

This site documents the Nix parts of Fediversity, rendered from the project's own module options and function doc-comments. Each subject below is a page in its own right, with its option reference rendered inline.

Subjects

  • Hosting-provider guide -- how to find and use the web UIs of a hosting-provider deployment: SSO, users, monitoring, containers, deploy logs and domain claims.
  • Flake attributes -- the attributes the flake exposes (packages, checks, NixOS configurations, apps), generated from the flake on every build.
  • Maintainer guide -- how to check a change, deploy it from CI or a workstation, test a feature branch and read the deploy logs.
  • Add an application -- how to add an application that operators deploy from the panel, and where to register it.
  • Threat model -- what Fediversity must protect, the trust boundaries, the controls in the code and the gaps that issues track.
  • SBOM -- where CI publishes the SBOM of each node, how to find the SBOM of a commit, and what it describes.
  • Data protection -- the GDPR roles of the actors, and the personal data that each application and service keeps, where and how long.
  • Contract templates -- a data processing agreement and switching and exit clauses, with the annexes that the code fills in.
  • Contracts and data flow -- how an operator configuration becomes a deployment, and how contracts connect consumers to providers, with diagrams and further reading.
  • Utility functions -- the helper functions under core/lib and core/effects, one section per file, generated from their doc-comments. Covers every function exercised by the project's nix-unit tests.
  • Data model -- the typed data model in core/lib/data-model.nix and the resources it builds on. Covers the request/policy resource pattern and the data model's own options.
  • Hosting resources -- the concrete request options each resource module declares (e.g. garage's buckets and access keys).
  • Operator configuration -- the operator-facing configuration schema, the same tree that drives the frontend JSON schema.
  • Specifications -- what core must do, and the principles that apply to all changes in core/.

The operator-facing web frontend and the deployment backend have their own documentation sites, built from their respective components:

  • Panel -- the Django web frontend operators use to configure and trigger deployments, and its services.panel NixOS options. Its user guide tells operators how to deploy and manage their applications.
  • API -- the HTTP and Centrifugo pub/sub backend that runs deployments and reports progress, and its services.fediversity-api NixOS options. Its wire surface is also browsable as Swagger UI (HTTP) and AsyncAPI (Centrifugo pub/sub).

Worked examples

For end-to-end examples of how the data model is exercised -- defining a resource, requesting it from a component, and resolving it through an environment -- see core/lib/data-model-test.nix.