Fediverse Playground

Run multiple fediverse software instances locally for development and federation testing.

Requirements

• Nix with flakes enabled (recommended), or Bun installed manually
• direnv (optional, recommended with Nix)
• Docker and Docker Compose
• Git

With Nix + direnv, entering the repo provides bun, docker, git, openssl, curl, and typescript.

Local hostnames

Instances use names like social.localhost and social.fediverse, served by the shared nginx container on 8080 (HTTP) and 8443 (HTTPS).

Many systems resolve *.localhost to 127.0.0.1 automatically. Names under *.fediverse do not — they must be added to /etc/hosts.

Nix + direnv

After generate, entering the dev shell checks whether *.fediverse names resolve. If not, you'll see a one-line hint — direnv itself won't fail or run nixos-rebuild.

Apply hostnames manually:

fediverse-playground apply-hosts

Or merge the marked block from files/hosts.snippet into /etc/hosts yourself.

NixOS (declarative /etc/hosts)

To make *.fediverse work everywhere (e.g. browsers from the app launcher), import the optional module once:

imports = [
  /path/to/fediverse-playground/nix/hosts-module.nix
];

Then run nixos-rebuild switch after changing instances.

Without NixOS (manual)

After generate:

fediverse-playground apply-hosts

Check resolution:

getent ahosts social.fediverse
getent ahosts v2.localhost

Configuration

defaults.local_tld: fediverse adds a second name for each instance (e.g. v2.localhost → v2.fediverse). Optional per-instance names:

instances:
  my-v2:
    hostname: v2.localhost
    alt_hostnames:
      - custom.fediverse

Quick start

direnv allow   # or: nix develop

bun bin/fediverse-playground.ts init
# edit playground.config.yaml, or use the example:
cp playground.config.example.yaml playground.config.yaml

bun bin/fediverse-playground.ts sync-worktrees
bun bin/fediverse-playground.ts up -d

generate runs automatically after bun install and when entering the dev shell if playground.config.yaml changed.

CLI commands

Command	Description
init	Create playground.config.yaml
add	Add an instance via flags
edit <key>	Update an existing instance
remove <key>	Remove an instance
list	List configured instances
sync-worktrees	Ensure mirror repos and worktrees exist
apply-hosts	Merge files/hosts.snippet into /etc/hosts
install	Regenerate outputs when config is new or changed (postinstall hook)
generate	Render docker-compose.yml and supporting files
up / down	Start or stop the stack

Example:

bun bin/fediverse-playground.ts add \
  --key gnusocial-alice \
  --software social-v3 \
  --hostname alice.localhost \
  --name "Alice's Node"

Configuration

Instances are declared in playground.config.yaml. Each instance gets:

• its own git worktree under instances/<id>
• its own application container
• its own database name on the shared Postgres service

Shared services (web, db, redis) are emitted once and reused across instances.

Supported software

• GNU social v3 (priority)
• GNU social v2 (WIP baseline)

Additional recipes (Mastodon, Lemmy, Friendica, etc.) can be added under src/recipes/.

Build standalone executable

bun run build:exe

Legacy Python tool

The previous Python/whiptail workflow (configure, menu.py) remains in the repo during migration but is superseded by the Bun CLI.

Contributing

Add a recipe module under src/recipes/ implementing the recipe interface, then register it in the recipe registry.