The Fediversity project

This repository contains all the code and code-related files having to do with the Fediversity project.

Goals

Decentralise the operational responsibility for social media. Enable a more robust market of hosting providers, by making it easy to migrate operations and data to different providers.

Note that Fediversity is not about self-hosting. There already exist solutions for self-hosting, but they're not suitable for what we're trying to do. The ones we're aware of require substantial technical knowledge and time commitment by system-operators, especially for scaling to thousands of users. Not everyone has the expertise and time to run their own server.

Status: in development

see our:

• whitepaper
• roadmap
• kanban

Interactions

To reach these goals, we aim to implement the following interactions between actors (depicted with rounded corners) and system components (see the glossary, depicted with rectangles).

Concepts

The actors involved and the vocabulary this project uses are documented at https://core.pages.git.fediversity.eu/concepts.html.

Development

All the code made for this project is freely licenced under EUPL. This means, anyone can use the work here to learn from it or change it according to their needs. You can even read up on development proceedings.

Contact the project team if you have questions or suggestions, or if you're interested in using Fediversity software for your operations:

• E-mail: mailto:contact@fediversity.eu
• Mastodon: https://mastodon.fediversity.eu/@fediversity

Prerequisites

The instructions in this repository use Nix. Most of them use the nix command with a flake reference, for example nix run .#terraform-backend-dev. These commands need the experimental features nix-command and flakes. If these features are not enabled, Nix stops with error: experimental Nix feature 'nix-command' is disabled.

To enable the features for all commands, add this line to ~/.config/nix/nix.conf (or to /etc/nix/nix.conf):

experimental-features = nix-command flakes

On NixOS, set nix.settings.experimental-features = [ "nix-command" "flakes" ]; in your system configuration.

To enable the features for one command only, put the option after nix and before the subcommand:

nix --extra-experimental-features 'nix-command flakes' run .#terraform-backend-dev

For more information, refer to Flakes on the NixOS wiki.

The nix-shell and nix-build commands do not need these features. When an instruction also gives a command without flakes, you can use that command.

Content of this repository

Most of the directories in this repository have their own README going into more details as to what they are for. As an overview:

• panel/ contains the code of our front-end.

• core/ contains source code handling deployments.

Documentation sites

Each component's rendered docs are published on push to main under pages.git.fediversity.eu (see notes/git-pages.md):

• core -- the core NixOS options/module and library docs.
• panel -- the Django front-end docs.
• api -- the API docs, plus its wire surface as Swagger UI (HTTP) and AsyncAPI (Centrifugo pub/sub).

Entrypoints

Rather than one monolithic root flake, each top-level component owns its own entrypoint (a flake.nix + default.nix following the transparent-wrapper pattern), and consumers address it directly:

• core/ -- the shared library leaf (data model, resources, effects, components, setups) plus the pure render combinator that turns a groups set into the orchestration surface: nixosConfigurations, the <group>-<effect>-<machine> deployment packages/apps/devShells, legacyPackages, core-docs, the core-scoped formatter and the default dev shell. core/default.nix runs render with its in-tree frontend-free groups, so ./core#... exposes a default deploy family out of the box.
• api/, panel/ -- each leaf owns its packages, checks, formatter and devShells. Addressed as ./api#..., etc. (The nix-module-form widget the panel embeds lives in its own org repo, consumed here via an npins pin. npins/README.md records, for each pin that is a fork, a branch or a non-vendor source, why it is one and when it can go.)
• the repo root (./) stays thin, retaining only what is inherently root-anchored (see below).

Enumerating attributes cheaply

nix flake show forces every leaf on the surface to report its type, name and meta.description, and the deploy family is ~1400 attributes wide per entrypoint. When all you need is the list of names, ask for the attrset spine instead:

nix eval --json ./core#packages.x86_64-linux --apply builtins.attrNames

This is what nix-flake-check.sh uses to walk the surface. For the deployment family specifically, nix build ./core#deployment-attributes yields the same { attribute, machine } records the api's detect-at-submit guard reads, as JSON, and core/docs/md/flake-attributes-intro.md documents the <group>-<effect>-<machine>[-<verb>] grammar the names follow, so a name can usually be constructed rather than looked up.

When you do run nix flake show, note that its eval cache is keyed on the flake's locked-ref fingerprint: a dirty working tree has no rev and so no fingerprint, and --impure disables the cache outright. Committing first is what makes a repeated nix flake show free.

Why the root entrypoint cannot be removed

Two concerns force a repo-root flake to survive; both are documented inline in default.nix:

1. The deploying-vs-deployed boundary. The generated deploy configuration.nix bakes (import repoRoot {}).boundary.<system> and resolves the operator config through boundary.<system>.deploymentPlan, whose caller is imported as import (repoRoot + "/${caller}") args. Those caller strings span several trees, and hosts-common.nix / the deployment constants.nix anchor root-path at the repo root, so ./. there must remain the repo root.
2. The infra / cross-cutting checks. core/checks/default.nix aggregates checks that cross core/, nix/contracts and multiple leaves, and resist a clean per-leaf split (shared runNixOSTest overlay, requiredMemory passthru, repo-root caller paths), so the root retains them as its checks output.

The root also owns the one repo-wide concern that must scan the whole tree: the pre-commit hook (git-hooks treefmt + trim-trailing-whitespace, src = ./.). Per-leaf treefmt checks cover each leaf's own languages; the repo-wide hook is the backstop so no file falls between leaf scopes.

The out-of-tree npins / flake-mode caveat

Each entrypoint reads its dependencies via sources ? import ../npins, reaching the single npins/ directory at the repo root -- there is no per-leaf npins copy. In flake mode (./core#...) Nix copies each flake's own subtree to the store, so ../npins is only reachable because npins/ is git-tracked at the root; flake mode ignores untracked files. Two consequences:

• New leaf files (flake.nix, flake.lock) must be tracked with git add (or git add -N) before a flake-mode eval sees them, otherwise ../npins (and the leaf itself) resolves against an incomplete tree and fails with a 'npins' is too short to be a valid store path error.
• The leaf flakes are system-scoped and guard builtins.currentSystem (see core/default.nix), but CI evals still pass --impure so currentSystem is available in pure flake eval. Path-mode (import ./core {} / nix-build ./core -A ...) reaches ../npins unconditionally and yields drvPaths identical to flake mode.

Usage

Loading the nix shell should install a pre-commit hook.