homelab-optimized/hosts/vms/matrix-ubuntu-vm/docs/FEDERATION.md

Mastodon Federation Guide

What is Federation?

Federation allows your Mastodon instance to communicate with other Mastodon instances (and other ActivityPub-compatible servers). Users can follow accounts on other servers, and posts are shared across the network.

Federation Requirements

1. HTTPS (Required)

Federation only works over HTTPS. Cloudflare provides this automatically when proxying is enabled.

2. Correct Domain Configuration

# .env.production
LOCAL_DOMAIN=mastodon.vish.gg

⚠️ Warning: Changing LOCAL_DOMAIN after setup will break existing accounts!

3. Webfinger Endpoint

Must respond correctly at:

https://mastodon.vish.gg/.well-known/webfinger?resource=acct:username@mastodon.vish.gg

Expected response:

{
  "subject": "acct:vish@mastodon.vish.gg",
  "aliases": [
    "https://mastodon.vish.gg/@vish",
    "https://mastodon.vish.gg/users/vish"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://mastodon.vish.gg/@vish"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://mastodon.vish.gg/users/vish"
    }
  ]
}

4. ActivityPub Actor Endpoint

Must respond at:

https://mastodon.vish.gg/users/vish

With Accept: application/activity+json header.

Testing Federation

Test Webfinger (from external server)

curl "https://mastodon.vish.gg/.well-known/webfinger?resource=acct:vish@mastodon.vish.gg"

Test Actor Endpoint

curl -H "Accept: application/activity+json" "https://mastodon.vish.gg/users/vish"

Test Outbound Federation

Search for a remote user in your Mastodon instance:

1. Go to https://mastodon.vish.gg
2. Search for @Gargron@mastodon.social
3. If federation works, you'll see the user's profile

Test from Another Instance

Go to any public Mastodon instance and search for:

@vish@mastodon.vish.gg

Cloudflare Configuration

Required Settings

1. Proxy Status: Orange cloud (Proxied) ✅
2. SSL/TLS Mode: Full (strict)
3. Cache Level: Standard (or Bypass for API endpoints)

Origin Rules (if using non-standard ports)

Since nginx listens on port 8082, configure an origin rule:

Rule:

• If hostname equals mastodon.vish.gg
• Then: Override destination port to 8082

Firewall Rules

Ensure port 8082 is accessible from Cloudflare IPs or use Cloudflare Tunnel.

Common Federation Issues

Issue: Remote users can't find your instance

Cause: DNS not properly configured or Cloudflare not proxying Fix:

1. Verify DNS A record points to your server
2. Enable Cloudflare proxy (orange cloud)
3. Wait for DNS propagation

Issue: Webfinger returns 301 redirect

Normal behavior: Mastodon redirects HTTP to HTTPS Solution: Ensure requests come via HTTPS

Issue: Cannot follow remote users

Cause: Outbound connections blocked Fix:

1. Check firewall allows outbound HTTPS (443)
2. Verify sidekiq is running: docker compose ps
3. Check sidekiq logs: docker compose logs sidekiq

Issue: Federation lag

Cause: High queue backlog in sidekiq Fix:

# Check queue status
docker compose exec web bin/tootctl sidekiq status

# Clear dead jobs if needed
docker compose exec web bin/tootctl sidekiq kill

Federation Debug Commands

# Check instance connectivity
cd /opt/mastodon
docker compose exec web bin/tootctl domains crawl mastodon.social

# Refresh a remote account
docker compose exec web bin/tootctl accounts refresh @Gargron@mastodon.social

# Clear delivery failures
docker compose exec web bin/tootctl domains purge <domain>

Security Considerations

Block/Allow Lists

Configure in Admin → Federation:

• Block specific domains
• Silence (limit) specific domains
• Allow specific domains (whitelist mode)

Rate Limiting

Mastodon has built-in rate limiting for federation requests to prevent abuse.

Monitoring Federation Health

Check Sidekiq Queues

docker compose exec web bin/tootctl sidekiq stats

Healthy queues should have:

• Low push queue (outbound deliveries)
• Low pull queue (fetching remote content)
• Minimal retries

Check Federation Stats

In Admin → Dashboard:

• Known instances count
• Active users (remote)
• Incoming/outgoing messages