tutorial

Yacht Monitoring with Vigilmon

"Learn how to monitor Yacht, the self-hosted Docker container management UI, with Vigilmon — covering web dashboard availability, Docker socket connectivity, container state polling health, template registry fetching, compose stack management API, and user session service monitoring."

Yacht Monitoring with Vigilmon

Yacht is a self-hosted Docker container management UI built with TypeScript and Node.js. It provides a web dashboard for deploying and managing Docker containers, pulling from template libraries, managing compose stacks, and viewing container logs — all from a browser-based interface. Teams running homelabs, internal tooling, or edge deployments use Yacht to avoid SSH-based Docker management and give non-technical team members a safe container management surface.

Because Yacht is the control plane for Docker containers on its host, an undetected outage means containers can crash and restart without the team noticing. Template fetches can fail silently, compose deployments can stall, and user sessions can expire — all without alerting anyone unless monitoring is in place.

This guide covers how to monitor Yacht with Vigilmon.

Why Yacht Needs Monitoring

Yacht failures can leave container infrastructure unmanaged and unobserved:

  • Web dashboard crash — the Node.js server stops responding; operators lose visibility into all containers managed through Yacht and cannot deploy or stop services
  • Docker socket disconnection — Yacht loses its connection to /var/run/docker.sock; the UI loads but all container state is stale or missing, and start/stop/restart operations silently fail
  • Container state polling failure — the background polling loop stops; the dashboard freezes on an outdated snapshot, hiding container crashes and restarts
  • Template registry fetch failure — Yacht cannot reach its configured template repositories; new deployments from templates are blocked and template updates are not applied
  • Compose stack management API failure — the REST API for stack operations returns errors; automated deployments and CI/CD integrations that use the Yacht API cannot create or update stacks
  • User session expiry or auth failure — JWT sessions expire prematurely or the auth middleware breaks; all operators are logged out and cannot access the dashboard

Vigilmon monitors all of these failure modes so your team is alerted before container management is blocked.

Yacht Architecture Overview

| Component | Default Port | Role | Monitoring Priority | |-----------|-------------|------|---------------------| | Yacht web server (Node.js) | 8000 | Web dashboard and REST API | Critical | | Docker socket | /var/run/docker.sock | Container state and control | Critical | | Template registry | External (HTTP) | Template library fetching | High | | Compose stack API | 8000 (same server) | Stack deployment and management | High |

Monitor 1: Yacht Web Dashboard Availability

Monitor the Yacht login page to confirm the Node.js server is up:

  1. Log in to Vigilmon → Monitors → New Monitor
  2. Type: HTTP
  3. Name: Yacht - Web Dashboard
  4. URL: http://your-yacht-host:8000/
  5. Method: GET
  6. Expected status: 200
  7. Keyword check: Yacht
  8. Interval: 1 minute

Test your endpoint:

curl -s http://your-yacht-host:8000/ | grep -i "yacht"
# Expected: HTML containing "Yacht"

Monitor 2: Yacht API Health (Unauthenticated)

The /api/ endpoint returns HTTP 401 when unauthenticated. A 401 confirms the Express API is running and routing correctly — a 502 or 500 indicates the Node.js process has crashed or the reverse proxy lost its upstream:

  1. Type: HTTP
  2. Name: Yacht - API Health
  3. URL: http://your-yacht-host:8000/api/
  4. Method: GET
  5. Expected status: 401
  6. Interval: 2 minutes
curl -s -o /dev/null -w "%{http_code}" http://your-yacht-host:8000/api/
# Expected: 401 (unauthenticated — API is functional)
# Error: 500 or 502 (server or proxy failure)

Monitor 3: Docker Socket Connectivity (Container List API)

Yacht's container list endpoint depends on an active Docker socket connection. A successful response (even an empty array) confirms Docker socket connectivity. An error or stale data here indicates the socket has been lost:

  1. Type: HTTP
  2. Name: Yacht - Docker Socket Connectivity
  3. URL: http://your-yacht-host:8000/api/containers/
  4. Method: GET
  5. Expected status: 200
  6. Interval: 2 minutes
  7. Authentication: Bearer token (see note below)

To test with a Bearer token:

# Step 1: Obtain a token
TOKEN=$(curl -s -X POST http://your-yacht-host:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin@yacht.local","password":"pass"}' | python3 -c "import sys,json; print(json.load(sys.stdin).get('access_token',''))")

# Step 2: Verify container list (Docker socket connectivity)
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  http://your-yacht-host:8000/api/containers/
# Expected: 200 with JSON array (may be empty if no containers)

For continuous monitoring, set up a heartbeat script (see Monitor 5) to test this path end-to-end rather than using static credentials in monitor headers.

Monitor 4: SSL Certificate Alert

If Yacht is exposed via a reverse proxy with HTTPS:

  1. Type: HTTP
  2. Name: Yacht - SSL Certificate
  3. URL: https://yacht.your-domain.com/
  4. SSL certificate expiry alert: 21 days before expiry
  5. Interval: 1 hour
curl -vI https://yacht.your-domain.com/ 2>&1 | grep "expire date"
# Expected: a future expiry date with at least 21 days remaining

Monitor 5: Yacht Container Management Heartbeat

An hourly end-to-end check authenticates to Yacht, lists containers, and confirms Docker socket connectivity. This catches silent Docker daemon failures that the web UI may mask with cached data:

Heartbeat Script

#!/bin/bash
# yacht-heartbeat.sh — run hourly via cron
set -euo pipefail

YACHT_URL="http://your-yacht-host:8000"
YACHT_USER="admin@yacht.local"
YACHT_PASS="$YACHT_HEARTBEAT_PASSWORD"
VIGILMON_HEARTBEAT="YOUR_HEARTBEAT_ID"

# Step 1: Authenticate
AUTH_RESPONSE=$(curl -s -X POST \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"${YACHT_USER}\",\"password\":\"${YACHT_PASS}\"}" \
  "${YACHT_URL}/api/auth/login")

TOKEN=$(echo "$AUTH_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('access_token',''))" 2>/dev/null)

if [ -z "$TOKEN" ]; then
  echo "[yacht-hb] Authentication failed"
  exit 1
fi

# Step 2: List containers (verifies Docker socket)
CONTAINERS=$(curl -s -w "\n%{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  "${YACHT_URL}/api/containers/")

HTTP_STATUS=$(echo "$CONTAINERS" | tail -1)
if [ "$HTTP_STATUS" -ne 200 ]; then
  echo "[yacht-hb] Container list returned $HTTP_STATUS (Docker socket may be disconnected)"
  exit 1
fi

# Step 3: List templates (verifies template registry fetch path)
TEMPLATES_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  "${YACHT_URL}/api/templates/")

if [ "$TEMPLATES_STATUS" -ne 200 ]; then
  echo "[yacht-hb] Template list returned $TEMPLATES_STATUS"
  exit 1
fi

echo "[yacht-hb] Dashboard, Docker socket, and templates all healthy"

# Step 4: Signal Vigilmon
curl -s "https://heartbeat.vigilmon.online/$VIGILMON_HEARTBEAT"

Add to cron:

# /etc/cron.d/yacht-heartbeat
0 * * * * root /opt/yacht/yacht-heartbeat.sh >> /var/log/yacht-heartbeat.log 2>&1

In Vigilmon:

  • Type: Heartbeat
  • Name: Yacht - Container Management Pipeline
  • Expected interval: 1 hour
  • Grace period: 10 minutes

Alert Configuration

| Monitor | Type | Interval | Alert Channel | |---------|------|----------|---------------| | Web dashboard | HTTP | 1 min | Slack + Email | | API health (401 check) | HTTP | 2 min | Slack | | Docker socket connectivity | HTTP | 2 min | PagerDuty + Slack | | SSL certificate | HTTP | 1 hour | Email (21-day lead) | | Container management pipeline | Heartbeat | 1 hour | PagerDuty + Email |

Use PagerDuty or phone alerts for the Docker socket and heartbeat monitors. A disconnected Docker socket means containers are running blind — crashes and restarts are invisible until someone manually SSHes into the host.

Status Page

  1. Status Pages → New Page → name it "Yacht Container Management"
  2. Add all monitors above
  3. Share with your infrastructure and DevOps team

When a developer reports that containers appear stuck or the dashboard is loading stale data, they can check this page before escalating to infrastructure.

Summary

Yacht is the management surface for Docker containers on its host. Vigilmon keeps it healthy:

  • HTTP monitors for dashboard availability, API health, and Docker socket connectivity
  • SSL certificate monitoring with a 21-day lead time for reverse-proxied deployments
  • Hourly heartbeat that authenticates, lists containers, and verifies the template API — catching Docker socket disconnections and auth failures that the cached UI may hide

Get started at vigilmon.online.

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