Federation — local driver vs FediFuel offload
Getting started
Federation — local driver vs FediFuel offload
VulaSocial is an ActivityPub-compatible node. The Federation setting (admin: Settings → Federation) decides where the heavy ActivityPub work happens:
- Local — this node performs its own WebFinger, actor documents, RSA signing, HTTP-signature verification and delivery. Works out of the box, no external service.
- FediFuel — crypto and delivery are offloaded to your FediFuel bridge service. Ideal for modest shared-hosting nodes or popular accounts that need massive fan-out.
The one setting that matters
FEDERATION_PUBLIC_BASE_URL must be your real public domain:
FEDERATION_PUBLIC_BASE_URL=https://your-node.example
This is what the "Federated" badge, your member addresses (@handle@your-domain),
WebFinger and actor documents are built from. Never use localhost or an IP.
Local driver (default)
FEDERATION_DRIVER=local
No configuration beyond the base URL. The node generates RSA keys, serves
/.well-known/webfinger and /users/{handle}, and signs + verifies traffic
itself. This is fully functional on shared hosting.
FediFuel offload
FEDERATION_DRIVER=fedifuel
FEDI_OFFLOADER_URL=https://off.fedifuel.com
FEDI_BRIDGE_SECRET=<generated>
FEDI_RELAY_SECRET=<generated>
The app signs each handoff to the offloader with FEDI_BRIDGE_SECRET (HMAC)
and sends X-Tenant (your host) + X-Bridge-Event + X-Bridge-Signature
headers. The offloader owns keys and delivery and relays inbound activity back
(signed with FEDI_RELAY_SECRET).
In the admin panel (recommended)
Settings → Federation:
- Choose FediFuel as the processing mode.
- Enter the FediFuel URL and your FediFuel API key (
ff_...). - Click Connect & provision — the app registers this instance and stores the returned bridge/relay secrets encrypted in settings.
- Use Test connection to confirm reachability.
If you only have
FEDI_*values in.env, the app uses them as a fallback. Settings stored in the admin panel win over.env.
WebFinger / actor endpoints
When federation is enabled, these must be reachable publicly (no login):
/.well-known/webfinger?resource=acct:handle@your-node.example/users/{handle}(actor document)
Verifying federation works
# Local driver
curl 'https://your-node.example/.well-known/webfinger?resource=acct:test@your-node.example'
# Health of the active driver
php artisan federation:status
A proper WebFinger response returns a JSON JRD. {"error":"actor not found"}
is correct for a handle that doesn't exist — the endpoint itself is working.
FediFuel service
FediFuel is a separate service (a Laravel control plane + a Node offloader
engine). See the FediFuel repository for deploying it. The wire contract the
app speaks is /api/v1/outbound, /api/v1/register and /api/v1/health.
Related
- Configuration reference
- Dashboard & analytics (federation activity charts)
Still stuck? Contact the node administrator.