Monitoring YunoHost with Vigilmon

YunoHost turns a plain Debian server into a fully managed self-hosting platform — web apps, email, LDAP user directory, and SSL certificates all configured through a single web admin panel. It's remarkably powerful for individuals and small organizations who want to own their services without deep sysadmin knowledge. But YunoHost doesn't ship with an uptime monitoring layer: you won't know the webadmin is down, an SSL certificate expired, or a hosted app became unreachable until a user reports it. Vigilmon closes that gap with external probes for your YunoHost webadmin, admin API, hosted apps, and Let's Encrypt certificates.

What You'll Set Up

• YunoHost webadmin UI availability monitor (port 443 HTTPS)
• YunoHost REST API health check at /yunohost/api/swaggerui
• Hosted app availability monitor for your primary installed application
• SSL certificate expiry alerts for all YunoHost-managed domains
• Heartbeat monitor for YunoHost service health via the domains API

Prerequisites

• YunoHost installed on a Debian server or VPS (v11+ recommended)
• YunoHost webadmin accessible at https://yourdomain.com/yunohost/admin
• A free Vigilmon account

Step 1: Monitor the YunoHost Webadmin UI

The YunoHost webadmin is an Angular SPA served by YunoHost's Nginx reverse proxy at /yunohost/admin on port 443. A 200 response confirms both the Nginx proxy and the webadmin frontend are operational.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: https://yourdomain.com/yunohost/admin.
4. Set Check interval to 5 minutes.
5. Set Expected HTTP status to 200.
6. Click Save.

If YunoHost redirects unauthenticated requests, the monitor should still receive a 200 for the SPA shell. If you see consistent 302 or 401 responses, try monitoring the root path https://yourdomain.com instead — a working Nginx proxy will serve something on the root even if the webadmin redirects.

Step 2: Monitor the YunoHost Admin API

YunoHost provides a Python Flask REST API for programmatic administration. The /yunohost/api/swaggerui endpoint serves the API documentation UI and confirms the Flask backend is running and accessible:

1. Click Add Monitor → HTTP / HTTPS.
2. Set URL to https://yourdomain.com/yunohost/api/swaggerui.
3. Set Check interval to 5 minutes.
4. Set Expected HTTP status to 200.
5. Click Save.

This endpoint doesn't require authentication and returns 200 when the YunoHost API backend is fully operational. A failure here while the webadmin UI monitor is healthy suggests the Flask API process has crashed or the Nginx upstream configuration for /yunohost/api is broken.

You can also check the API root directly:

https://yourdomain.com/yunohost/api

This returns a JSON response listing available API endpoints, confirming the API is alive and routing correctly.

Step 3: Monitor Your Primary Hosted Application

YunoHost installs apps on subdomains or subdirectories — the exact URL depends on how you configured the app during installation. Add a Vigilmon monitor for each critical hosted application:

1. Click Add Monitor → HTTP / HTTPS.
2. Set the URL to your app's address, for example:
   • Nextcloud: https://cloud.yourdomain.com
   • WordPress: https://yourdomain.com/wordpress
   • Bitwarden/Vaultwarden: https://vault.yourdomain.com
3. Set Check interval to 5 minutes.
4. Set Expected HTTP status to 200.
5. Click Save.

Repeat for each critical app. A hosted app going down while the YunoHost webadmin is healthy typically means the specific app container has crashed or its upstream service is not responding — YunoHost's Nginx proxy will return a 502 in this case.

If your app exposes a health endpoint, use it:

https://cloud.yourdomain.com/status.php      # Nextcloud
https://yourdomain.com/bitwarden/alive       # Vaultwarden

Dedicated health endpoints give you a richer signal than just checking that Nginx serves a page.

Step 4: SSL Certificate Alerts for YunoHost Domains

YunoHost automatically manages Let's Encrypt certificates for every configured domain. Auto-renewal can fail if the ACME HTTP challenge is blocked, the domain has DNS issues, or the renewal cron job encounters an error. Expired certificates break HTTPS access for all apps on that domain.

Add a certificate expiry monitor for each domain:

1. Open the webadmin monitor created in Step 1.
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.
5. Repeat for each additional domain hosted on your YunoHost server.

To list all domains on your YunoHost server:

yunohost domain list

Add one Vigilmon SSL monitor per domain. YunoHost certificates renew 14 days before expiry by default — a 21-day alert gives you a full week to investigate if automatic renewal fails before the cert expires.

To manually trigger renewal for a domain:

yunohost domain cert renew yourdomain.com

Step 5: Heartbeat Monitoring for YunoHost Service Health

The YunoHost admin API /yunohost/api/domains endpoint returns the list of configured domains when authenticated. Use a scheduled API call as a heartbeat to confirm the YunoHost backend, LDAP directory, and Nginx proxy are all functional:

1. Click Add Monitor → Cron Heartbeat in Vigilmon.
2. Set the expected ping interval to 30 minutes.
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Generate a YunoHost admin API token by authenticating via the API:

# Get an API session token (from the YunoHost server itself or a trusted machine)
TOKEN=$(curl -s -X POST https://yourdomain.com/yunohost/api/login \
  -d "credentials=admin:YOUR_ADMIN_PASSWORD" \
  -c /tmp/yunohost-cookie.txt | python3 -c "import sys,json; print(json.load(sys.stdin).get('token',''))")

5. Set up a cron job that calls the domains endpoint and pings Vigilmon on success:

# /etc/cron.d/yunohost-health-heartbeat
*/30 * * * * root curl -sf --cookie /tmp/yunohost-cookie.txt \
  https://yourdomain.com/yunohost/api/domains | grep -q '\[' \
  && curl -s https://vigilmon.online/heartbeat/abc123

This confirms the YunoHost API is responding, authentication is working, and the LDAP/domain management layer is operational. If the heartbeat stops arriving, Vigilmon alerts you — indicating the API, LDAP service, or cron runner has gone offline.

For a simpler unauthenticated heartbeat, probe the Swagger UI endpoint instead:

*/30 * * * * root curl -sf https://yourdomain.com/yunohost/api/swaggerui > /dev/null \
  && curl -s https://vigilmon.online/heartbeat/abc123

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add email, Slack, Discord, or Telegram notifications.
2. Set Consecutive failures before alert to 2 on the webadmin and API monitors — YunoHost occasionally restarts Nginx and the API during system upgrades.
3. For the heartbeat monitor, set the Grace period to 35 minutes to account for the 30-minute cron interval plus execution overhead.
4. Add maintenance windows in Vigilmon before running yunohost upgrade or reconfiguring domains — upgrades can cause 2–5 minute outages as services restart.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Webadmin UI | https://yourdomain.com/yunohost/admin | Nginx down, SPA not loading | | Admin API | https://yourdomain.com/yunohost/api/swaggerui | Flask API process crash | | Hosted app | App subdomain or subdirectory URL | App container crash, proxy 502 | | SSL certificate | Each configured domain | Let's Encrypt renewal failure | | Service health heartbeat | /yunohost/api/domains | API, LDAP, or cron offline |

YunoHost makes self-hosting accessible without sacrificing control — Vigilmon makes sure you know the moment any part of that self-hosted stack stops working for your users.