tutorial

Uptime monitoring for Swarmpit Docker Swarm management UI

Swarmpit is a lightweight Docker Swarm management web UI built in Clojure. It provides a visual interface for deploying services, managing stacks, and monito...

Swarmpit is a lightweight Docker Swarm management web UI built in Clojure. It provides a visual interface for deploying services, managing stacks, and monitoring containers across your Swarm cluster. Swarmpit sits in front of the Docker Swarm API and stores its state in CouchDB — making it a multi-layer system where failures can occur in the web interface, the CouchDB backend, the Docker Swarm API connection, or the service deployment pipeline.

This tutorial covers production-grade uptime monitoring for Swarmpit using Vigilmon. We will walk through:

  • Monitoring the Swarmpit web interface availability
  • Monitoring Docker Swarm API connectivity
  • Monitoring CouchDB database health
  • Monitoring the service deployment pipeline
  • Monitoring the stack management API
  • Monitoring real-time log streaming service

Prerequisites

  • Swarmpit running on port 888 with CouchDB (Docker Swarm)
  • A free account at vigilmon.online

Part 1: Monitor the Swarmpit web interface

Swarmpit serves its management UI on port 888 by default. Monitoring the root URL confirms the Clojure web server is running and the frontend is being served correctly.

Deploy Swarmpit on Docker Swarm

# docker-compose.yml (deploy with docker stack deploy)
version: "3.8"

services:
  app:
    image: swarmpit/swarmpit:latest
    environment:
      - SWARMPIT_DB=http://db:5984
      - SWARMPIT_AGENT_API_VERSION=1.3
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "888:8080"
    deploy:
      placement:
        constraints:
          - node.role == manager

  db:
    image: couchdb:2.3.0
    volumes:
      - db-data:/opt/couchdb/data
    deploy:
      placement:
        constraints:
          - node.role == manager

  influxdb:
    image: influxdb:1.7
    volumes:
      - influx-data:/var/lib/influxdb
    deploy:
      placement:
        constraints:
          - node.role == manager

  agent:
    image: swarmpit/agent:latest
    environment:
      - DOCKER_API_VERSION=1.35
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    deploy:
      mode: global

volumes:
  db-data:
  influx-data:

Verify the web interface

curl -s -o /dev/null -w "%{http_code}" http://localhost:888/
# Expected: 200

Vigilmon setup for the Swarmpit web interface

  1. Log in to vigilmon.online and click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-swarmpit-host:888/
  4. Set interval to 1 minute.
  5. Add a keyword check: must contain Swarmpit (present in the app HTML title).
  6. Name it Swarmpit Web UI.
  7. Click Save.

A DOWN event here means no one can access the Swarm management UI — service deployments, stack updates, and container inspections are all blocked.

Part 2: Monitor Docker Swarm API connectivity

Swarmpit reads the Docker Swarm API through the Docker socket on the manager node. If the socket is unavailable, the daemon restarts, or the Swarmpit container loses access to the socket, the UI shows stale data or errors on every page.

Check Docker Swarm API access through Swarmpit

# Swarmpit exposes a REST API for its own operations
# The /api/v1/services endpoint lists all Swarm services
curl -s -u admin:password http://localhost:888/api/v1/services | head -c 200
# Expected: JSON array of services

Test Docker socket access directly

On the manager node, verify the Docker socket is accessible:

docker node ls
# Expected: list of all Swarm nodes with their status

Vigilmon setup for Swarm API connectivity

  1. Click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-swarmpit-host:888/api/v1/nodes
  4. Set interval to 2 minutes.
  5. Under Custom headers, add: Authorization: Basic base64(admin:password) (replace with your Swarmpit credentials base64-encoded).
  6. Expected status code: 200.
  7. Add a keyword check: must contain [ (valid JSON array start).
  8. Name it Swarmpit Swarm API.
  9. Click Save.

Part 3: Monitor CouchDB database health

Swarmpit stores user accounts, service configurations, and application state in CouchDB. If CouchDB goes down, Swarmpit cannot authenticate users or save service changes — even if the UI itself is still serving pages.

Check CouchDB health

CouchDB exposes its own health endpoint at port 5984:

curl -s http://localhost:5984/

Expected response:

{
  "couchdb": "Welcome",
  "version": "2.3.0",
  "git_sha": "07ea0c7",
  "uuid": "...",
  "features": ["scheduler"],
  "vendor": { "name": "The Apache Software Foundation" }
}

Check the Swarmpit database specifically

curl -s http://localhost:5984/swarmpit | jq .db_name
# Expected: "swarmpit"

Vigilmon setup for CouchDB health

CouchDB's default port 5984 may not be exposed externally. You have two options:

Option A — expose CouchDB health through Swarmpit's network:

Monitor the Swarmpit API endpoint that depends on CouchDB (login or user list):

  1. Click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-swarmpit-host:888/api/v1/account
  4. Set interval to 2 minutes.
  5. Add authorization header with your credentials.
  6. Expected status codes: 200.
  7. Name it Swarmpit CouchDB Health.
  8. Click Save.

Option B — expose CouchDB on a restricted port:

If CouchDB is accessible from outside the Docker network:

  1. Click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-swarmpit-host:5984/
  4. Set interval to 2 minutes.
  5. Add a keyword check: must contain "couchdb":"Welcome".
  6. Name it Swarmpit CouchDB.
  7. Click Save.

Part 4: Monitor the service deployment pipeline

The service deployment pipeline — creating or updating Docker Swarm services — depends on both the Docker socket and CouchDB being healthy. A failed deployment is often invisible from the Swarmpit UI (the service entry exists but the container never starts).

Monitor the services API endpoint

# List services — this exercises the full stack: UI → Docker socket → Docker Swarm
curl -s -u admin:password http://localhost:888/api/v1/services
# Expected: JSON array; may be empty for a fresh cluster

Vigilmon setup for deployment pipeline

  1. Click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-swarmpit-host:888/api/v1/services
  4. Set interval to 3 minutes.
  5. Add authorization header.
  6. Expected status code: 200.
  7. Name it Swarmpit Deployment Pipeline.
  8. Click Save.

A DOWN or 5xx from this endpoint means deployment operations will fail even if the web UI appears to load.

Part 5: Monitor the stack management API

Docker Swarm stacks are multi-service deployments defined by compose files. Swarmpit's stack management API is used to deploy, update, and remove stacks. If this endpoint fails, teams lose the ability to do coordinated stack deployments through the UI.

Check the stacks API

curl -s -u admin:password http://localhost:888/api/v1/stacks | jq '.[0].name'
# Expected: name of the first stack, or null for an empty cluster

Vigilmon setup for stack management

  1. Click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-swarmpit-host:888/api/v1/stacks
  4. Set interval to 5 minutes.
  5. Add authorization header.
  6. Expected status codes: 200.
  7. Name it Swarmpit Stack API.
  8. Click Save.

Part 6: Monitor real-time log streaming service

Swarmpit provides real-time log streaming for services and tasks via WebSocket. The log streaming service requires both the Docker socket (to tail container logs) and the Swarmpit web server (to relay them). If the streaming endpoint breaks, operators lose visibility into live container output.

Check the log streaming endpoint availability

The log streaming endpoint is a WebSocket upgrade path. You can monitor its HTTP availability (before the WebSocket handshake) as a proxy for whether the endpoint is functional:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Upgrade: websocket" \
  -H "Connection: Upgrade" \
  http://localhost:888/events
# Expected: 101 (Switching Protocols) or 400 (Bad Request — still means the endpoint is alive)

Vigilmon setup for log streaming

  1. Click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: http://your-swarmpit-host:888/
  4. Set interval to 2 minutes.
  5. Expected status codes: 200.
  6. Add a keyword check: must contain swarmpit (confirms the app is running, which backs the WebSocket endpoint).
  7. Name it Swarmpit Log Streaming.
  8. Click Save.

Part 7: SSL certificate monitoring

If Swarmpit is exposed through a reverse proxy with TLS, monitor the certificate:

  1. In Vigilmon, click Add Monitor.
  2. Choose SSL monitor.
  3. Enter: swarmpit.example.com
  4. Set alert threshold to 14 days before expiry.
  5. Add your alert channel.
  6. Click Save.

Part 8: Webhook alerts

Configure Vigilmon webhooks to notify your DevOps team when Swarmpit has a problem:

// webhook-receiver.ts
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook/vigilmon', (req, res) => {
  const { monitor_name, status, url, response_code, checked_at } = req.body;

  if (status === 'down') {
    console.error('[VIGILMON] Swarmpit monitor DOWN', {
      monitor: monitor_name,
      url,
      code: response_code,
      at: checked_at,
    });

    // Alert DevOps team, disable automated deployments, etc.
    notifyDevOps({ monitor: monitor_name, url });
  } else if (status === 'up') {
    console.info('[VIGILMON] Swarmpit recovered', { monitor: monitor_name });
  }

  res.sendStatus(204);
});

Vigilmon sends this payload on DOWN and UP transitions:

{
  "monitor_id": "mon_jkl012",
  "monitor_name": "Swarmpit Web UI",
  "status": "down",
  "url": "http://your-swarmpit-host:888/",
  "checked_at": "2026-06-30T11:00:00Z",
  "response_code": 502,
  "response_time_ms": 3200
}

Summary

Your Swarmpit deployment now has five layers of monitoring:

  1. Web UI — confirms the Clojure web server is serving the Swarmpit management interface.
  2. Docker Swarm API — verifies Swarmpit can reach the Docker socket and list Swarm resources.
  3. CouchDB Health — catches database failures that prevent authentication and state persistence.
  4. Deployment Pipeline — validates the full stack from UI to Docker Swarm is functional for service operations.
  5. Stack Management — confirms multi-service stack deployments can be listed and managed.

Vigilmon handles check scheduling, multi-region polling, alert routing, and uptime history. Your team gets notified within 60 seconds of any failure in your Swarmpit or Docker Swarm stack.

Monitor your Swarmpit deployment free at vigilmon.online

#swarmpit #docker #swarm #devops #monitoring

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