How to Monitor Your Grocy Instance with Vigilmon

Grocy is an open-source household management system and ERP that tracks groceries, chores, products, and recipes. When you self-host Grocy, you get a privacy-first solution for your home — but you also own the uptime. If Grocy goes down, barcode scanning fails, shopping lists are unavailable, and your household workflow breaks. Vigilmon monitors your Grocy instance from outside your server so you know about problems before your household does.

What You'll Monitor

• The /api/system/info health endpoint (API system check)
• The Grocy web UI (main household management interface)
• The barcode scanning endpoint (product lookup via API)
• SSL certificate expiry

Prerequisites

• A self-hosted Grocy instance (Docker or bare-metal PHP)
• A free Vigilmon account
• Your Grocy API key (found under Manage API keys in the Grocy settings)
• Your Grocy URL (e.g. https://grocy.yourdomain.com)

Why Monitor Grocy?

Grocy is a PHP application that connects to an SQLite or MySQL database. Despite being lightweight, it has real failure modes in a self-hosted environment:

• The PHP-FPM pool exhausts workers and the UI becomes unreachable
• The SQLite database file is locked or corrupted after an unclean shutdown
• A Docker container restarts with a volume mount issue and serves an empty database
• A reverse proxy misconfiguration blocks API requests while the web UI still loads

External monitoring from Vigilmon checks Grocy from the outside the same way your phone's barcode scanner does — and catches these failures before you discover them mid-grocery-trip.

Step 1: Monitor the System Info Endpoint

Grocy exposes /api/system/info as a lightweight health check that returns application version and system status. It requires an API key header.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: https://grocy.yourdomain.com/api/system/info
4. Set Check interval to 1 minute.
5. Set Expected status code to 200.
6. Under Request headers, add:
   • GROCY-API-KEY: your-grocy-api-key
   • Accept: application/json
7. Under Expected body contains, enter "grocy_version" — a healthy response always includes this field.
8. Name it Grocy – System info and click Save.

A healthy response looks like:

{
  "grocy_version": {
    "Version": "4.2.0",
    "ReleaseDate": "2024-03-01"
  },
  "php_version": "8.2.10",
  "sqlite_version": "3.43.0"
}

If the PHP application or database is broken, this endpoint returns an error or times out — Vigilmon fires an alert immediately.

Step 2: Monitor the Web UI

The web interface is what your household uses daily to manage shopping lists, stock levels, and recipes. Monitoring it separately confirms that nginx/Apache is serving the frontend correctly even if the API health check passes.

1. Click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter: https://grocy.yourdomain.com
4. Set Expected status code to 200.
5. Under Expected body contains, enter Grocy — the login page and dashboard include this in the page title.
6. Name it Grocy – Web UI and save.

Step 3: Monitor the Barcode Scanning Endpoint

Grocy's killer feature for many users is barcode scanning via mobile apps like Barcodebuddy or the official Grocy Android app. These apps call the product-by-barcode API endpoint. If this endpoint is slow or broken, scanning simply does nothing — no error message, no feedback.

Add a dedicated monitor for the barcode lookup endpoint:

1. Click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: https://grocy.yourdomain.com/api/stock/products/by-barcode/0000000000000
   • This barcode is a dummy value — Grocy returns a 400 error with a JSON body for unknown barcodes, which still confirms the endpoint is reachable and the API is processing requests.
4. Set Expected status code to 400 — an "unknown barcode" 400 response is actually proof the endpoint is working.
5. Under Expected body contains, enter "error_message" — Grocy's 400 response for unknown barcodes includes this field.
6. Under Request headers, add GROCY-API-KEY: your-grocy-api-key.
7. Name it Grocy – Barcode API and save.

This monitor will alert you if the barcode endpoint stops responding — even if the main web UI is still loading.

Step 4: SSL Certificate Alerts

Grocy's barcode scanning apps on mobile devices are strict about TLS — a certificate error on your domain will silently break all barcode scans even if the app says it's connected.

1. Open each monitor you created.
2. Under SSL Certificate, enable Alert before expiry.
3. Set warnings at 30 days and 7 days before expiry.
4. Save.

Let's Encrypt auto-renewal usually handles this, but renewal failures from nginx config changes or ACME challenge blocks happen more often than expected.

Step 5: Configure Alert Channels

1. In Vigilmon, go to Alert Channels → Add Channel.
2. Add Email, Slack webhook, or a webhook for your notification service.
3. For Slack:

{
  "text": "🚨 *{{monitor_name}}* is {{status}}!\nURL: {{url}}\nTime: {{timestamp}}"
}

4. Attach the channel to all three monitors (System info, Web UI, Barcode API).

Step 6: Verify the Setup

1. Temporarily change the Expected body contains on the system info monitor to vigilmon-test.
2. Wait one check interval — you should receive an alert within 2 minutes.
3. Revert the setting and confirm a recovery notification arrives.
4. For the barcode endpoint: try setting the expected status to 200 (which it won't return) to confirm that monitor also alerts correctly, then revert.

Going Further

• Task and chore monitoring: Grocy's chore system is time-based — if you track recurring chores, add a Vigilmon heartbeat that you ping from a cron job after Grocy's task scheduler runs.
• Backup verification: SQLite databases are easy to back up but easy to forget. Pin a cron job that backs up data/grocy.db and pings a Vigilmon heartbeat so you know backups are running.
• Response time: Grocy on a Raspberry Pi or small VPS can get slow under load. Set a Warn threshold of 800ms on the web UI monitor to catch memory pressure before the UI becomes unusable.

Your Grocy instance is now fully monitored: system health, web UI, barcode scanning endpoint, and SSL — so your household management keeps running smoothly even when you're not watching the server.