Monitoring Homebox with Vigilmon: Health, API Availability & SSL Alerts

Homebox is a lightweight self-hosted home inventory manager — you use it to track where things are, what you own, and asset details like purchase dates and warranties. It's a single Go binary, which makes it easy to run but also easy to forget about. When it goes down, looking up "where did I put that" becomes frustratingly manual. Vigilmon keeps an eye on Homebox around the clock so you don't have to. In this tutorial you'll set up monitoring for the health endpoint, web UI, REST API, and SSL certificate.

What You'll Build

A Vigilmon HTTP monitor for Homebox's health endpoint
A web UI availability check
An API availability check for the items endpoint
SSL certificate expiry alerts
Email alert routing

Prerequisites

A running Homebox instance (Docker is the most common deployment)
Homebox accessible at a public or VPN-routable URL
A free Vigilmon account

Step 1: Monitor the Health Endpoint

Homebox exposes a /api/v1/status endpoint that confirms the application and its embedded SQLite database are operational.

curl https://homebox.yourdomain.com/api/v1/status
# {"health":true}

In Vigilmon, create a new HTTP Monitor:

| Field | Value | |---|---| | URL | https://homebox.yourdomain.com/api/v1/status | | Method | GET | | Check interval | 60 seconds | | Expected status | 200 | | Keyword match | true | | Timeout | 10 seconds | | Regions | 2–3 for redundancy |

Homebox is a Go binary — if it crashes, it stays down until the container or process is restarted. This 60-second check means you'll know within a minute. The keyword match on true ensures the health response body confirms a healthy state, not just an HTTP 200 from a misconfigured proxy.

Step 2: Web UI Availability Check

The Homebox UI is served by the same Go process, but a bad Nginx/Caddy configuration in front of Homebox can break the UI while the Go process itself stays healthy. Create a second monitor to validate end-to-end web UI access:

| Field | Value | |---|---| | URL | https://homebox.yourdomain.com | | Method | GET | | Expected status | 200 | | Keyword match | Homebox | | Check interval | 5 minutes |

If you've configured Homebox with an authentication-required frontend (all pages behind login), the root URL may return a 302 redirect to /login. Adjust the monitor to follow redirects and use /login as the target URL, with a keyword like Sign In or Login.

Step 3: API Availability Check

Beyond confirming the process is alive, it's useful to verify that the API layer — which your inventory data depends on — actually responds to authenticated requests. Homebox's REST API requires a JWT token obtained at login.

First, obtain a token (store it securely — rotate it periodically):

curl -s -X POST https://homebox.yourdomain.com/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin@example.com","password":"yourpassword"}' \
  | jq -r '.token'

Then create a Vigilmon HTTP monitor for an authenticated API call:

| Field | Value | |---|---| | URL | https://homebox.yourdomain.com/api/v1/groups/statistics | | Method | GET | | Expected status | 200 | | Keyword match | totalItems | | Headers | Authorization: Bearer YOUR_JWT_TOKEN | | Check interval | 5 minutes |

The /api/v1/groups/statistics endpoint returns aggregate data about your inventory (total items, locations, labels). If the API layer or database is degraded, this check fails even when the health endpoint returns 200.

Tip: Create a dedicated monitoring user with read-only permissions rather than using your admin credentials for the API check. This limits the blast radius if the token is ever logged.

Step 4: SSL Certificate Expiry Alerts

Homebox stores sensitive household data — a lapsed SSL certificate causes browser security warnings that block access. Enable certificate monitoring on your health endpoint monitor in Vigilmon:

| Field | Value | |---|---| | Alert when expiry < | 21 days | | Alert again at | 7 days |

If you're using Let's Encrypt with Caddy (the most common Homebox setup), Caddy auto-renews certificates. This alert catches the case where Caddy's ACME challenge fails — for example, if your domain's DNS records changed or a firewall rule blocks port 80.

Step 5: Docker Health Check

Pair Vigilmon's external monitoring with Docker's internal health check so Homebox self-heals when the Go process crashes:

# docker-compose.yml
services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:7745/api/v1/status"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    volumes:
      - homebox-data:/data
    ports:
      - "7745:7745"
    restart: unless-stopped

volumes:
  homebox-data:

Docker restarts the container when the health check fails three times in a row. Vigilmon fires an alert even if Docker successfully restarts it — so you see flapping and can investigate the root cause (OOM, disk full, corrupted SQLite file) before it becomes a recurring problem.

Step 6: Alert Routing

Email

Vigilmon → Alert Channels → Email → assign to the health endpoint and API monitors. For a homelab setup, a personal email is usually sufficient.

Slack or Discord

If your household uses Slack or Discord:

Create an incoming webhook (Slack: Apps → Incoming Webhooks; Discord: Server Settings → Integrations → Webhooks)
Vigilmon → Alert Channels → Add Channel → Webhook → paste the URL
Assign to all monitors

A homelab alert message:

🔴 *homebox.yourdomain.com/api/v1/status* is DOWN
Status: connection refused | Duration: 4m 10s
SSH in and check: docker ps | grep homebox

Production Checklist

[ ] /api/v1/status health monitor with keyword match
[ ] Web UI check every 5 minutes
[ ] Authenticated API monitor with statistics endpoint
[ ] Dedicated read-only monitoring user for API auth
[ ] Docker healthcheck configured in Compose
[ ] SSL expiry alert at 21 days
[ ] Alert channels tested

Wrapping Up

Homebox is a set-it-and-forget-it kind of app — which is exactly why it needs monitoring. Without it, a crashed Go process can sit unnoticed for days until someone tries to look something up. With Vigilmon you now have:

Process health: /api/v1/status polled every 60 seconds
UI availability: web UI checked every 5 minutes
API layer: authenticated statistics endpoint confirms data access
SSL: expiry alerts before certs lapse
Self-healing: Docker healthcheck restarts crashes automatically

The total setup time is under 15 minutes, and the free Vigilmon tier covers all these monitors with no ongoing cost.