# 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