Sanitized mirror from private repository - 2026-04-20 01:32:01 UTC

docs/services/matrix/FEDERATION.md

@@ -0,0 +1,171 @@
+# 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
+# .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:
+```json
+{
+  "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)
+```bash
+curl "https://mastodon.vish.gg/.well-known/webfinger?resource=acct:vish@mastodon.vish.gg"
+```
+
+### Test Actor Endpoint
+```bash
+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**:
+```bash
+# 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
+
+```bash
+# 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
+```bash
+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