172 lines
4.3 KiB
Markdown
172 lines
4.3 KiB
Markdown
# 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
|