DrFed 0.1.0: Our first release

[dahlia]

DrFed is a web-based platform for developing and debugging ActivityPub implementations, built by the team behind Fedify.

Today we are releasing DrFed 0.1.0, our first release. It is an MVP: you can run DrFed locally, create test instances and actors, store test objects, and inspect incoming activity deliveries in the web UI.

To be honest, DrFed is not yet especially useful as an ActivityPub debugger. Much of the tooling we have planned is still ahead of us. We are releasing this version to make our progress visible and give you something you can install and try while development continues.

Install and sign in

DrFed 0.1.0 is available on npm as @drfed/drfed. You need Node.js 26 or newer. Install the package globally to make its four commands available on your PATH:

npm install --global @drfed/drfed@0.1.0

Create an account before starting the server, using the same data directory for both commands:

drfed-account create --data-path .pgdata \
  --email alice@example.com --name Alice
drfed-server --root-origin http://drfed.localhost:8888 \
  --data-path .pgdata --mail-log-content

Replace the email address and display name with your own. This example uses PGlite, so you do not need a separate database server. Account creation prepares the database, and the server applies pending migrations on startup. PGlite allows only one process to own its data directory, which is why account creation comes first.

Open http://drfed.localhost:8888, choose Sign in, and enter the email address you used above. The local example prints a login link in the terminal; follow it to sign in. The default mail transport does not deliver email, and --mail-log-content explicitly enables printing message contents for local testing. For a service deployment, configure SMTP or another supported mail transport instead.

The installation guide also covers installing into a local directory and running the commands with npx.

A workspace of test instances

After signing in, open Workspace and choose New instance. DrFed generates an identifier for the instance and gives it a subdomain of your configured root origin. Each instance runs as an ActivityPub server, with its own actors and inbox.

For example, with a root origin of https://drfed.example.com, an instance named example would live at https://example.drfed.example.com. The instance page lists its NodeInfo, WebFinger, and shared inbox endpoints, with copy buttons for using those URLs in your own tests.

The local setup above is useful for exploring the UI and making requests from your own machine. To receive requests from other servers, you need a publicly reachable deployment with wildcard DNS and HTTPS for the instance subdomains. A reverse proxy must preserve the original Host header. See the server README for the deployment details.

Generate actors and create objects

On an instance page, choose Actor and enter how many actors to generate. DrFed creates test identities with generated usernames. An actor's detail page shows its handle, identity, and federation endpoints, including its inbox and outbox. You can copy these addresses into requests from the ActivityPub application you are developing.

Choose Object on the instance page to create a Note or Article attributed to one of its actors. The form accepts an optional name, HTML content, and explicit ActivityPub addressing as JSON. For example, this addresses an object to Public:

{"to": ["https://www.w3.org/ns/activitystreams#Public"]}

The actor page lists its stored objects and shows their HTML as source text. Publicly addressed local objects and their Create activities are also available through ActivityPub, including the actor's outbox. Creating an object does not deliver it to remote servers. This is a way to prepare content for another implementation to fetch, rather than a general activity-sending tool.

Inspect incoming activity deliveries

When your application sends an activity to a DrFed instance's inbox, the instance's Activity log records the delivery. Each entry shows the activity type, status, sender and destination, and time. Expand an entry to inspect and copy the recorded JSON-LD; scroll up to load older entries.

This screenshot shows a deliberately unsigned test request. The inbox refused it with HTTP 401, and the log records it as unverified. Seeing a request in the log does not mean DrFed authenticated its sender or accepted its activity.

DrFed also stores eligible authenticated incoming Create activities containing Note or Article objects. Other activity types can be recorded without becoming stored objects. Delivery contents are restricted to instance members and administrators. The current UI lets you inspect recorded history; it does not yet provide live updates, search, or filters.

Four commands for running DrFed

The npm package includes the commands needed to run and maintain a deployment:

Command	Purpose
drfed-server	Run the backend and embedded web frontend, together by default.
drfed-account create	Create a local account before signing in.
drfed-migrate	Apply database migrations, or inspect migration history with --check.
drfed-web	Run the frontend separately against a DrFed backend.

PGlite stores data in a local directory. You can instead select PostgreSQL with --postgres-url or its alias --database-url. Stop a PGlite server before using the account or migration commands against its data directory. To prepare and then check that database without starting the server:

drfed-migrate --data-path .pgdata
drfed-migrate --data-path .pgdata --check

All four commands accept an explicit TOML configuration file through --config, as well as the relevant DRFED_* environment variables. CLI options take precedence over environment variables, then TOML, then defaults. --print-config shows the effective settings and their sources with secrets redacted. See the configuration guide and CLI reference for the options, mail transports, and separate frontend setup.

Shell completions are available for Bash, zsh, fish, PowerShell, and Nushell. For example:

drfed-server completion bash > drfed-server-completion.bash
source ./drfed-server-completion.bash

Replace drfed-server with another command to generate its completion script. Installation does not activate completions automatically; the completion installation instructions explain persistent setup for each shell.

Current limits and documentation

This release has rough edges. Directly opening an instance detail page can terminate the installed server with a Seroval serialization error. We found this while preparing these notes and are tracking it in #132.

The broader debugging tools described in our project overview, such as a step-by-step signature debugger, JSON-LD comparison tools, and WebFinger/NodeInfo validators, are goals for the project. They are not available as dedicated tools in this release. The object creation form also does not yet send activities to arbitrary remote inboxes.

Our documentation is still incomplete and not yet organized into a systematic user guide. Some overview text describes the platform we intend to build, so it should not be read as a list of completed 0.1.0 features. For now, start with README.md, the CLI package README, and the installation and configuration pages under docs/.

In the next version, we will publish a Docker image alongside the npm packages, making it easier to run DrFed without setting up Node.js yourself.

Thanks, and what comes next

Thank you to the four people on the DrFed development team who have brought us to this first release, listed alphabetically:

• ChanHaeng Lee (@2chanhaeng)
• Hong Minhee (@dahlia)
• Hyeonseo Kim (@dodok8)
• Jiwon Kwon (@sij411)

We also thank NLnet and the NGI0 Commons Fund for funding DrFed's development. Their support gives us time to build this free software tool for ActivityPub developers. You can read more on NLnet's DrFed project page.

We will keep working to make DrFed more useful for investigating federation failures. We hope you will follow the next stages of its development. Release history is kept in CHANGES.md.