Monitoring Your Funkwhale Instance with Vigilmon

Funkwhale is a federated music streaming platform — users can host their own libraries and follow other instances across the ActivityPub network. But federation is only valuable when your instance is reachable. A Funkwhale server that's down doesn't just affect your listeners; it breaks federation with every instance that tries to contact yours.

This tutorial adds production monitoring to a Funkwhale deployment:

• Web UI availability
• API health endpoint
• Federation endpoint verification
• Audio streaming service
• Celery worker health via heartbeat
• SSL certificate alerts

Step 1: Check the Funkwhale health endpoint

Funkwhale exposes a health check endpoint at /api/v1/instance/nodeinfo/2.0/. It returns instance metadata and is publicly accessible without authentication:

curl https://music.yourdomain.com/api/v1/instance/nodeinfo/2.0/

For a more direct health check, use the root API endpoint:

curl https://music.yourdomain.com/api/v1/

A 200 response confirms the Django application is running and the database is reachable (Funkwhale queries the database to serve the API). A non-200 response indicates the application server (gunicorn/uvicorn) is down or misconfigured.

For the most reliable uptime signal, monitor the landing page:

curl -o /dev/null -w "%{http_code}" https://music.yourdomain.com/

This traverses nginx → application server → Django, catching failures at any layer.

Step 2: Set up HTTP monitoring in Vigilmon

1. Sign up at vigilmon.online
2. Click New Monitor → HTTP
3. Enter https://music.yourdomain.com/api/v1/
4. Set check interval: 1 minute (paid) or 5 minutes (free)
5. Save

Add a second monitor for the web UI:

• URL: https://music.yourdomain.com/
• Keyword match: Funkwhale (or your instance name)

The two monitors catch different failure modes. The API monitor fails if Django crashes. The UI monitor fails if the frontend build is missing or nginx misconfiguration breaks static file serving — something the API check wouldn't catch.

Step 3: Monitor the federation endpoint

Funkwhale uses ActivityPub for federation. Other instances discover yours via /.well-known/webfinger and communicate via actor inboxes. If federation breaks, your followers on other instances stop receiving your updates and you stop receiving theirs.

Add a monitor specifically for the federation endpoint:

1. In Vigilmon, create a new HTTP monitor
2. URL: https://music.yourdomain.com/.well-known/webfinger
3. Expected status: 400 (webfinger returns 400 when no resource query param is supplied, which is fine — it means the endpoint is alive)
4. Alternatively, use a valid webfinger query: https://music.yourdomain.com/.well-known/webfinger?resource=acct:admin@music.yourdomain.com
5. Save

For the parameterised query, set expected status 200 and add a keyword match for "subject" in the response body.

Also monitor the nodeinfo endpoint used by federation crawlers:

• URL: https://music.yourdomain.com/.well-known/nodeinfo
• Expected status: 200
• Keyword match: links

Step 4: Monitor audio streaming

Funkwhale serves audio files either directly through nginx or via your object storage backend (S3, MinIO, etc.). If audio streaming breaks, users can browse the library but nothing plays.

Create a monitor for a known-good audio file or the streaming proxy endpoint:

# Get a sample track URL from your instance
curl -s "https://music.yourdomain.com/api/v1/tracks/?page_size=1" | \
  jq -r '.results[0].listen_url'

In Vigilmon:

1. Create a new HTTP monitor
2. URL: the listen_url from a track on your instance (pick one that won't be deleted)
3. Expected status: 200 or 206 (partial content for streaming)
4. Check interval: 5 minutes (audio URLs may have rate limiting)

Alternatively, monitor your object storage endpoint directly if tracks are stored externally:

• URL: https://your-s3-bucket.s3.amazonaws.com/ (or MinIO endpoint)
• This confirms object storage is reachable even when you can't load a specific track URL

Step 5: Celery worker health via heartbeat

Funkwhale uses Celery for background tasks: audio file processing, federation message delivery, cover art fetching, and transcoding. If Celery workers die, audio uploads appear to succeed but never process, and federation stops working.

Celery doesn't expose an HTTP health endpoint by default. Use the heartbeat pattern: configure a periodic Celery task to ping Vigilmon, confirming workers are alive and the queue is draining.

Add to your Funkwhale Celery configuration:

# config/settings/common.py (or your settings file)
from celery.schedules import crontab

CELERY_BEAT_SCHEDULE = {
    # ... your existing beat tasks ...
    'vigilmon-heartbeat': {
        'task': 'myapp.tasks.ping_vigilmon',
        'schedule': crontab(minute='*/5'),  # every 5 minutes
    },
}

Create the task:

# funkwhale_api/tasks.py (or wherever your tasks live)
import requests
from celery import shared_task

@shared_task
def ping_vigilmon():
    """Ping Vigilmon to confirm Celery workers are alive."""
    import os
    heartbeat_url = os.environ.get('VIGILMON_HEARTBEAT_URL')
    if heartbeat_url:
        try:
            requests.get(heartbeat_url, timeout=5)
        except requests.RequestException:
            pass  # Don't let heartbeat failures affect Celery

Set the environment variable in your Funkwhale .env:

VIGILMON_HEARTBEAT_URL=https://vigilmon.online/ping/your-heartbeat-id

In Vigilmon:

1. Click New Monitor → Heartbeat
2. Set expected interval: 10 minutes (2× the ping frequency, giving buffer for slow tasks)
3. Copy the ping URL and add it to your .env
4. Restart the Funkwhale Celery beat service

Now if Celery workers crash or the beat scheduler stops, Vigilmon alerts you within 10 minutes.

Step 6: SSL certificate monitoring

Funkwhale serves audio content over HTTPS. A lapsed certificate locks out every listener — their audio players will refuse to connect. Add SSL monitoring with a generous lead time:

In Vigilmon:

1. Go to New Monitor → SSL Certificate
2. Enter music.yourdomain.com
3. Set alert threshold: 30 days before expiry
4. Save

If your Funkwhale instance is behind a reverse proxy that also handles federation subdomains, monitor each:

music.yourdomain.com

Step 7: Alerts via Slack or email

In Vigilmon, go to Notifications → New Channel and configure Slack (webhook URL) or email.

Enable alerts on all your Funkwhale monitors. A useful alert routing strategy:

• API + web UI down → immediate Slack ping to #self-hosted-alerts
• Federation endpoint down → Slack ping (federation disruption affects other instance admins too, not just your users)
• Celery heartbeat missed → Slack ping (audio uploads silently failing is a serious data issue)
• SSL expiry warning → email to yourself 30 days out, Slack alert 7 days out

Step 8: Status page

If you run a public Funkwhale instance, your listeners deserve a status page:

1. Go to Status Pages → New Status Page in Vigilmon
2. Add your web UI monitor and API monitor
3. Name it after your instance (e.g., "music.yourdomain.com Status")
4. Link to it from your instance's About page

For a private instance shared with friends or a small community, post the status page URL in your Discord or group chat so members can check before reporting problems.

What you've built

| What | How | |------|-----| | Web UI availability | HTTP monitor → / with keyword match | | API health | HTTP monitor → /api/v1/ | | Federation endpoint | HTTP monitor → /.well-known/webfinger | | Nodeinfo endpoint | HTTP monitor → /.well-known/nodeinfo | | Audio streaming | HTTP monitor → sample track URL | | Celery workers | Heartbeat monitor via periodic task | | SSL certificate | Vigilmon SSL monitor, 30-day threshold | | Slack/email alerts | Vigilmon notification channels | | Status page | Vigilmon public status page |

Your music is on your server. Vigilmon makes sure it stays reachable.

Next steps

• Add response time monitoring to track audio streaming latency (slow streaming degrades the listening experience before it causes full failures)
• Monitor your object storage or CDN endpoint separately from the Funkwhale application
• Use Vigilmon's incident history to correlate Celery failures with Redis availability (Funkwhale uses Redis as the Celery broker)
• If you run multiple Funkwhale instances, create a shared status page showing the health of your whole deployment

Get started free at vigilmon.online.