Running a node

A birdd node is home base for a flock. It stores the flock’s observations, signs new events with the flock identity, and exchanges permitted observations with other nodes through relays.

At minimum, running a node means taking care of three pieces of persistent state:

• The flock’s private key
• The SQLite database
• The node configuration

Important

Keep the private key private and back it up. The key is your flock’s identity; losing it means losing the ability to sign as that flock.

What Runs on a Node

birdd is the core of a node, but a typical end-to-end deployment includes the services that let flock members submit observations and operators administer the system:

• birdd stores observations, signs events, and synchronizes with federation relays.
• signal-cli connects the flock’s Signal account to the Signal adapter.
• Grist provides the operator-facing spreadsheet used to review and edit local observations.
• Garage provides private S3-compatible storage for sanitized image and audio attachments.
• birdd-admin-web provides the node administration portal.
• Authelia authenticates access to Grist, the administration portal, and the metrics interface.
• Caddy terminates HTTPS and routes requests to those local services.
• Prometheus and Grafana collect and display node metrics. Alloy, Loki, and Tempo support metric ingestion, logs, and traces used by the operator portal.

This is the recommended reference deployment, not a required architecture. The core birdd service can run independently, and operators may enable only the adapters they need or use their own object storage, ingress, authentication, administration, and observability stack. The NixOS full-node role is an opinionated serving suggestion that provides a complete system with known integration points.

These services normally communicate over loopback and are not each exposed to the internet. The NixOS full-node role configures their service accounts, startup ordering, local endpoints, HTTPS ingress, and restart behavior. It also means a full node has persistent state beyond the three core files, including Signal account state, Grist data, Garage objects and metadata, Authelia data, and local observability data. See Backups and recovery for what must be preserved.

Get Running

Note

This is not necessary information if using the reference stack.

Install birdd, choose a persistent location for its files, and initialize the node:

birdd --config /var/lib/birdd/birdd.toml init \
  --node-name pallet \
  --flock-name "Pallet Town Birders" \
  --database /var/lib/birdd/birdd.sqlite \
  --key-file /var/lib/birdd/flock.key \
  --relay wss://relay.example.com

Start the node after reviewing the generated configuration:

birdd --config /var/lib/birdd/birdd.toml run

run keeps federation syncing and serves a read-only admin API on loopback. Signal, Grist, and other adapters run alongside the node as separate processes. For a long-running deployment, use a service manager so each process starts on boot and restarts after a failure.

Operator Guide

• Installation covers installing and updating the node.
• Configuration documents every birdd.toml setting.
• Relays explains how nodes exchange events.
• Identity and trust covers flock keys and choosing which neighbors to trust.
• Federation and audiences covers public and restricted sharing policies.
• Media storage covers observation attachments.
• Backups and recovery covers the persistent files you need to protect.
• Monitoring covers health and metrics.
• Troubleshooting collects common operator problems.
• The Birdd reference stack covers the recommended NixOS stack and third-party service setup.