tutorial

Monitoring Hajimari Startpage with Vigilmon

Hajimari is the Kubernetes-native startpage that auto-discovers your cluster's services via Ingress annotations. Learn how to monitor its pod health, Kubernetes API connectivity, Ingress scanning, and web UI availability with Vigilmon.

Hajimari is the startpage purpose-built for Kubernetes homelabs. Rather than manually maintaining a YAML list of services (like Homer or Mafl), Hajimari queries the Kubernetes API and discovers every service with a hajimari.io/enable: "true" Ingress annotation — building your bookmarks automatically as you deploy. It's an elegant solution for clusters that change frequently.

But Hajimari itself is a Kubernetes workload with real dependencies: it needs the Kubernetes API server, Ingress objects with correct annotations, and a functioning pod. When Hajimari goes dark, you lose your entire cluster navigation index — and you're stuck kubectl-ing to find your own services.

Vigilmon closes this monitoring gap: pod availability checks, Kubernetes API connectivity verification, Ingress scanning health, and web UI response time — all in a single dashboard.

What You'll Set Up

  • Hajimari pod/web UI availability monitoring
  • Kubernetes API server connectivity verification
  • Ingress annotation scanning health via heartbeat
  • Custom bookmarks configuration validity check
  • Search provider endpoint reachability
  • Web UI response time monitoring
  • TLS/Ingress certificate expiry alerts

Prerequisites

  • Hajimari deployed in a Kubernetes cluster via Helm (namespace: typically hajimari)
  • Hajimari's Ingress accessible from your monitoring host
  • kubectl access to the cluster (for cron-based checks)
  • A free Vigilmon account

Step 1: Monitor Hajimari Web UI Availability

Hajimari's Go/HTMX web server serves the startpage on port 3000 inside the cluster, exposed externally via an Ingress. This is the primary health check — if users can't load the startpage, the pod or Ingress is down.

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

Hajimari's root path serves the full startpage HTML. A 200 response confirms:

  • The pod is running and ready
  • The Kubernetes Service is routing traffic to the pod
  • The Ingress controller is forwarding external traffic correctly

Step 2: Verify Kubernetes API Server Connectivity

Hajimari's core feature — automatic service discovery — depends entirely on querying the Kubernetes API server to list Ingress objects. If the API server becomes unreachable from the Hajimari pod (network policy change, API server restart, RBAC misconfiguration), the startpage stops updating with new services.

Set up a cron heartbeat that verifies the Kubernetes API is accessible from within the cluster:

  1. In Vigilmon, go to Add Monitor → Cron / Heartbeat.
  2. Set expected interval to 5 minutes.
  3. Copy the heartbeat ping URL.

Create a Kubernetes CronJob that checks API connectivity and fires the heartbeat:

# hajimari-api-health-cronjob.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: hajimari-api-health
  namespace: hajimari
spec:
  schedule: "*/5 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName: hajimari  # reuse Hajimari's SA (has Ingress read access)
          containers:
          - name: health-check
            image: curlimages/curl:latest
            command:
            - /bin/sh
            - -c
            - |
              TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
              STATUS=$(curl -fsS -o /dev/null -w "%{http_code}" \
                --cacert /var/run/secrets/kubernetes.io/serviceaccount/ca.crt \
                -H "Authorization: Bearer $TOKEN" \
                https://kubernetes.default.svc.cluster.local/apis/networking.k8s.io/v1/ingresses)
              if [ "$STATUS" = "200" ]; then
                curl -fsS "https://vigilmon.online/api/heartbeat/YOUR_TOKEN"
              fi
          restartPolicy: Never

Apply with:

kubectl apply -f hajimari-api-health-cronjob.yaml

If the Kubernetes API becomes unreachable from inside the cluster, the heartbeat stops and Vigilmon alerts you that Hajimari's discovery engine is blind.

Step 3: Monitor Ingress Annotation Scanning Health

Beyond API reachability, Hajimari needs Ingress objects with correct hajimari.io/enable: "true" annotations to populate the startpage. A misconfigured RBAC role, namespace scope issue, or annotation typo means new services never appear.

Set up a health check that verifies Hajimari is actually discovering Ingresses:

  1. Add a new HTTP monitor in Vigilmon.
  2. URL: https://hajimari.yourdomain.com/
  3. Keyword check: Look for a known service name that should appear in the startpage HTML (e.g., the name of your most-used service).

In Vigilmon, under the HTTP monitor settings, add a content check:

  • Contains keyword: Nextcloud (or any service you know has the annotation)
  • Check interval: 5 minutes

If the keyword disappears from the page, it means either that service went away or Hajimari stopped discovering Ingresses — both worth an alert.

Step 4: Monitor Hajimari Pod Availability via Kubernetes CronJob

For direct pod-level monitoring (independent of the Ingress/load-balancer path), create a CronJob that checks the pod's ClusterIP service:

# hajimari-pod-health-cronjob.yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: hajimari-pod-health
  namespace: hajimari
spec:
  schedule: "*/2 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: health-check
            image: curlimages/curl:latest
            command:
            - /bin/sh
            - -c
            - |
              STATUS=$(curl -fsS -o /dev/null -w "%{http_code}" \
                http://hajimari.hajimari.svc.cluster.local:3000/ \
                --max-time 5)
              if [ "$STATUS" = "200" ]; then
                curl -fsS "https://vigilmon.online/api/heartbeat/YOUR_POD_HEALTH_TOKEN"
              fi
          restartPolicy: Never

This bypasses the Ingress entirely and probes the Kubernetes Service directly, giving you a clean signal of pod health independent of Ingress controller health.

Step 5: Monitor Search Provider Endpoint Reachability

Hajimari supports custom search providers (DuckDuckGo, SearXNG, Google, and self-hosted options). If your configured search endpoint becomes unreachable, search from the startpage silently breaks.

For a self-hosted SearXNG search provider:

  1. Add an HTTP monitor in Vigilmon.
  2. URL: https://searxng.yourdomain.com/healthz
  3. Expected HTTP status: 200
  4. Check interval: 5 minutes

For public search providers, you can skip this — their uptime is not your responsibility. Focus monitoring on self-hosted search backends.

Step 6: Monitor Web UI Response Time

Hajimari is a Go/HTMX app that renders server-side. Response times should be under 200ms — it is just rendering a list of Ingresses. Elevated response times indicate:

  • The Kubernetes API is slow to respond (API server overloaded)
  • The pod is CPU-throttled
  • Too many Ingress objects to enumerate (unusual but possible in large clusters)

Vigilmon automatically tracks response time for every HTTP monitor. After adding the web UI monitor in Step 1:

  1. Navigate to the monitor in Vigilmon.
  2. Open the Response Time chart.
  3. Set an alert threshold: if response time exceeds 2000ms (2 seconds), investigate.

Step 7: Configure TLS Certificate Monitoring

Hajimari is served via an Ingress with TLS — your Ingress controller handles certificate management (cert-manager with Let's Encrypt is standard). Monitor the certificate:

  1. Add an SSL Certificate monitor in Vigilmon.
  2. Domain: hajimari.yourdomain.com
  3. Alert threshold: 14 days before expiry.
  4. Click Save.

In Kubernetes environments, cert-manager usually handles renewal automatically. But ACME challenge failures, DNS provider issues, or rate limits can cause renewal to silently fail. The 14-day alert gives you ample time to investigate before expiry.

Step 8: Configure Alerting

Hajimari is a navigation hub. When it's down, the whole team is navigating by memory. Configure immediate alerts:

  1. In Vigilmon, navigate to Alert Settings.
  2. Add email alerts for the web UI monitor: notification after 1 failed check.
  3. Add a webhook to your team's chat or notification system (Slack, Discord, Mattermost, Ntfy).
  4. For cron heartbeats, alert after 1 missed heartbeat (15 minutes of silence).

Recommended Hajimari Helm Values for Observability

When deploying or updating Hajimari via Helm, these values improve observability alongside your Vigilmon monitors:

# values.yaml additions for observability
resources:
  requests:
    memory: "64Mi"
    cpu: "50m"
  limits:
    memory: "128Mi"
    cpu: "200m"

# Liveness and readiness probes (improves Kubernetes self-healing)
livenessProbe:
  httpGet:
    path: /
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 10

With readiness probes configured, Kubernetes will remove unhealthy Hajimari pods from the Service endpoints before external traffic reaches them — reducing the window where your Vigilmon check succeeds at the Ingress but the page is actually broken.

Summary: Full Hajimari Monitoring Coverage

| Monitor | URL / Target | Expected | Interval | |---|---|---|---| | Web UI | https://hajimari.domain/ | 200 | 1 min | | K8s API heartbeat | CronJob → heartbeat URL | Heartbeat | 5 min | | Pod ClusterIP heartbeat | CronJob → heartbeat URL | Heartbeat | 2 min | | Content check (service name) | https://hajimari.domain/ | Keyword present | 5 min | | SearXNG (if self-hosted) | https://searxng.domain/healthz | 200 | 5 min | | TLS Certificate | hajimari.domain | 14-day alert | daily |

Conclusion

Hajimari's automatic Kubernetes service discovery is elegant — but it adds real dependencies that can break silently. A Kubernetes API disconnect, an Ingress RBAC change, or a crashed pod all leave your team navigating blind. The Vigilmon setup above — combining external HTTP checks with in-cluster CronJob heartbeats — gives you full coverage from both inside and outside the cluster, so you know immediately when your Kubernetes startpage can't actually see your Kubernetes cluster.

Start monitoring Hajimari for free at Vigilmon →

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles