Monitoring Vikunja with Vigilmon: API Health, Web UI Availability, TCP Port & SSL Alerts

Vikunja is a self-hosted project management platform — an open-source alternative to Trello, Asana, and Todoist that gives your team task boards, Gantt charts, kanban views, and team collaboration without sending your project data to a third party. When Vikunja's API goes down, team members can't create or update tasks, sprint boards go stale, and any integrations or webhooks relying on the API fail silently. If the web UI becomes unreachable, non-technical team members lose access entirely. Vigilmon gives you external visibility into Vikunja's API health endpoint, web interface, TCP port, and SSL certificate so you detect failures before they disrupt your team's workflow.

What You'll Build

• A monitor on Vikunja's /api/v1/info health endpoint
• An HTTP monitor for the Vikunja web UI
• A TCP monitor for the Vikunja backend port
• SSL certificate monitoring for your Vikunja domain
• An alerting setup that distinguishes API failures from frontend or network failures

Prerequisites

• A running Vikunja instance with a public or network-reachable domain
• HTTPS configured (e.g., https://vikunja.example.com)
• A free account at vigilmon.online

Step 1: Verify Vikunja's Info Endpoint

Vikunja exposes a public, unauthenticated info endpoint at /api/v1/info that returns the application version, available authentication methods, and server status:

curl https://vikunja.example.com/api/v1/info

A healthy Vikunja instance returns HTTP 200 with a JSON body containing version information:

{
  "version": "0.23.0",
  "frontend_url": "https://vikunja.example.com",
  "motd": "",
  "link_sharing_enabled": true,
  ...
}

This endpoint requires no authentication and is designed for health checks and client discovery — it confirms the Go backend is running and its configuration is valid.

Step 2: Create a Vigilmon HTTP Monitor for the API Info Endpoint

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://vikunja.example.com/api/v1/info.
3. Check interval: 60 seconds.
4. Response timeout: 10 seconds.
5. Expected status: 200.
6. Keyword: version.
7. Label: Vikunja API Info.
8. Click Save.

This monitor catches:

• Vikunja Go backend process crashes
• Database connectivity failures (Vikunja supports MySQL, PostgreSQL, and SQLite)
• Configuration file errors after upgrades
• Binary or container crashes due to memory or resource exhaustion

The version keyword check ensures the response is a valid Vikunja JSON payload and not a proxy error page, which could also return 200.

Step 3: Monitor the Vikunja Web UI

The API backend and the web frontend are separate in Vikunja's architecture — the backend is a Go binary, and the frontend is a Vue.js single-page application served either by Vikunja's built-in server or a separate nginx/Caddy proxy. Monitor the web UI independently:

1. Add Monitor → HTTP.
2. URL: https://vikunja.example.com.
3. Check interval: 60 seconds.
4. Expected status: 200.
5. Keyword: Vikunja.
6. Label: Vikunja Web UI.
7. Click Save.

This monitor catches reverse proxy failures, frontend asset serving issues, and CDN errors that wouldn't affect the Go backend API but would prevent team members from accessing their task boards.

Step 4: Create a TCP Monitor for the Vikunja Backend Port

Vikunja's backend listens on port 3456 by default (or your configured port). A TCP check confirms the Go backend is bound and accepting connections at the network level, independently of the HTTP response:

1. Add Monitor → TCP.
2. Host: vikunja.example.com (or the internal host if behind a proxy).
3. Port: 3456 (or your configured Vikunja port).
4. Check interval: 60 seconds.
5. Response timeout: 10 seconds.
6. Label: Vikunja Backend TCP.
7. Click Save.

Note: If Vikunja is deployed behind a reverse proxy (nginx, Caddy, Traefik) and the backend port is not publicly exposed, the TCP monitor should target your internal host, or skip this step and rely on the API info endpoint check as the primary backend health signal.

When the TCP monitor fires but the web UI monitor returns 200, the reverse proxy is serving cached or static responses while the backend is down — a split-brain failure that only TCP monitoring can catch.

Step 5: Monitor SSL Certificates

Vikunja uses HTTPS for both the web UI and API. An expired SSL certificate:

• Prevents team members from accessing task boards in their browsers
• Blocks API clients and integrations from connecting
• Breaks mobile app access if you use the Vikunja app

1. Add Monitor → SSL Certificate.
2. Domain: vikunja.example.com.
3. Alert when expiry is within: 30 days.
4. Alert again: 14 days, 7 days, 3 days, 1 day.
5. Click Save.

Step 6: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | /api/v1/info | Non-200 or version missing | Check Vikunja binary/container; inspect database connection; review logs | | Web UI | Non-200 or keyword missing | Check reverse proxy; verify frontend static files are served | | Backend TCP | Connection refused or timeout | Check port binding; restart Vikunja process; review firewall rules | | SSL certificate | < 30 days to expiry | Renew certificate; check ACME/Let's Encrypt renewal logs |

Alert after: 2 consecutive failures for HTTP monitors. 1 failure for the TCP monitor — backend port failures indicate the process has crashed and won't recover on their own.

Common Vikunja Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Go backend process crash | /api/v1/info unreachable; alert within 60 s | | Database down | API returns 500; all task reads and writes fail | | Wrong database config after upgrade | API returns 500 or 503; info endpoint may still return cached data | | Reverse proxy misconfiguration | Web UI monitor fires; backend TCP may still be healthy | | Backend port conflict | TCP monitor fires; reverse proxy returns 502 | | SSL certificate expires | SSL monitor alerts at 30 days; browsers and apps reject connections | | Disk full on host | SQLite database writes fail; Vikunja returns 500 on mutations | | Migration failure after upgrade | Info endpoint returns 500; database schema mismatch | | DNS misconfiguration | All monitors fire simultaneously |

Project management tools exist to reduce chaos — but when the tool itself goes down unexpectedly, it creates exactly the kind of confusion it's meant to prevent. Team members can't see task assignments, sprint progress is unavailable, and blockers can't be tracked. Vigilmon watches Vikunja's API, web UI, backend port, and SSL certificate so you're notified within a minute of any failure, long before your team notices their boards are unreachable.

Start monitoring Vikunja in under 5 minutes — register free at vigilmon.online.