Monitoring Portainer with Vigilmon: Health Endpoint, Web UI Availability, SSL Certificates & Agent Port TCP Check

Portainer is the control plane for your Docker and Kubernetes environments — it gives teams a visual interface to manage containers, stacks, networks, volumes, and registries across multiple hosts. When Portainer goes down, operators lose the ability to inspect container status, deploy new stacks, and restart failed services through the UI. When the Portainer Agent port becomes unreachable, Portainer loses its connection to remote Docker hosts entirely. Vigilmon gives you external visibility into every layer of Portainer's availability: the system status API, web UI, SSL certificate, and agent port TCP connectivity.

What You'll Build

• A monitor on Portainer's /api/system/status health endpoint
• A web UI availability check to confirm the dashboard is accessible
• SSL certificate monitoring for your Portainer domain
• A TCP monitor on the Portainer Agent port to catch remote host connectivity failures
• An alerting setup that distinguishes API failures from UI and agent connectivity issues

Prerequisites

• A running Portainer CE or EE 2.x+ instance accessible over HTTPS
• Your Portainer domain with a valid SSL certificate (e.g., https://portainer.example.com)
• Portainer Agent deployed on remote Docker hosts (optional but recommended)
• A free account at vigilmon.online

Step 1: Verify Portainer's System Status Endpoint

Portainer exposes a public system status endpoint at /api/system/status that returns information about the running instance without requiring authentication:

curl https://portainer.example.com/api/system/status

A healthy Portainer instance returns JSON like:

{
  "Version": "2.19.4",
  "InstanceID": "abc123...",
  "EdgeAgents": 0,
  "Agents": 1
}

The endpoint returns 200 OK when Portainer's API server is functional. A crash, OOM kill, or failed startup will result in a connection error or 502/503 from the reverse proxy. Use this as your primary health monitor because it validates the Portainer API process is alive and responding.

Authentication: This endpoint is intentionally public. It does not expose sensitive information and is designed for monitoring and discovery purposes.

Step 2: Create a Vigilmon HTTP Monitor for the System Status Endpoint

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://portainer.example.com/api/system/status.
3. Check interval: 60 seconds.
4. Response timeout: 10 seconds.
5. Expected status: 200.
6. Keyword: Version (always present in a healthy Portainer status response).
7. Click Save.

This monitor catches:

• Portainer process crashes or container restarts
• OOM kills on the Portainer container
• Database corruption causing Portainer to fail on startup
• Reverse proxy failures (NGINX, Traefik, Caddy) that block access to Portainer
• Failed Portainer upgrades that leave the API unresponsive

Alert sensitivity: Set to trigger after 1 consecutive failure. When Portainer is down, operators have no visibility into container health and cannot respond to incidents through the UI.

Step 3: Monitor the Portainer Web UI

The Portainer web UI is what operators use daily to manage containers, stacks, and environments. The API can be healthy while the web UI returns errors — for example, if the static asset serving is broken after an upgrade or a reverse proxy misconfiguration strips required headers:

curl -L https://portainer.example.com
# Returns HTML containing "Portainer"

1. Add Monitor → HTTP.
2. URL: https://portainer.example.com.
3. Check interval: 2 minutes.
4. Response timeout: 15 seconds.
5. Expected status: 200.
6. Keyword: Portainer (appears in the page title and UI content).
7. Label: Portainer web UI.
8. Click Save.

When the web UI monitor fires but the /api/system/status monitor stays green, the issue is typically in static asset serving, a CDN misconfiguration, or a reverse proxy that handles API routes differently from the root path. This layer separation helps isolate frontend from backend failures.

Step 4: Monitor SSL Certificates

Portainer manages production container infrastructure — operators rely on it during incidents when time pressure is highest. A certificate expiry at that moment is a critical blocker. Set up SSL monitoring with multi-stage alerts:

openssl s_client -connect portainer.example.com:443 2>/dev/null | openssl x509 -noout -dates

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

Portainer with self-signed certificates: If you run Portainer with a self-signed certificate on an internal network, monitor the domain anyway — Vigilmon can reach internal endpoints via your exposed hostname. If Portainer is purely internal (no external DNS), set up a TCP port monitor on 443 instead to confirm the HTTPS listener is up.

Step 5: Monitor the Portainer Agent Port via TCP Check

Portainer Agent runs on remote Docker hosts and listens on TCP port 9001 by default. Portainer's API server connects to this port to manage remote environments. When the agent port becomes unreachable — due to a firewall rule change, Docker network reconfiguration, or the agent container crashing — Portainer loses the ability to manage that environment:

nc -zv docker-host.example.com 9001

Add a TCP monitor for each remote Docker host running the Portainer Agent:

1. Add Monitor → TCP.
2. Host: docker-host.example.com (your remote Docker host).
3. Port: 9001 (default Portainer Agent port).
4. Check interval: 2 minutes.
5. Label: Portainer Agent: docker-host.
6. Click Save.

Repeat for every remote Docker host in your Portainer environments. When the agent port monitor fires while Portainer itself is healthy, the issue is isolated to the remote host — a firewall change, agent container restart, or network partition between Portainer and the remote host.

Portainer Edge Agent: If you use the Edge Agent (for environments without direct inbound connectivity), the agent initiates outbound connections to Portainer's Edge tunnel server on port 8000. Monitor that port instead: portainer.example.com:8000.

Step 6: Configure Alerting

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

| Monitor | Trigger | Action | |---|---|---| | /api/system/status | Non-200 or Version missing | Restart Portainer container; check Docker logs with docker logs portainer | | Web UI | Non-200 or keyword missing | Check reverse proxy config; verify static assets served correctly | | SSL certificate | < 30 days to expiry | Renew certificate; check ACME automation in Caddy/Traefik/cert-manager | | Agent port TCP | Connection refused | Check agent container status on remote host; verify firewall rules on port 9001 |

Alert after: 1 consecutive failure for the status API and agent port monitors. 2 consecutive failures for UI and SSL monitors.

Common Portainer Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Portainer container OOM killed | /api/system/status unreachable; alert within 60 s | | Reverse proxy misconfiguration | Both API and UI monitors fire; TCP on 9443 may still succeed | | SSL certificate expires | SSL monitor alerts at 30-day threshold; browser access breaks | | Agent container crashed on remote host | Agent TCP monitor fires; Portainer UI shows environment as "down" | | Firewall rule blocks agent port 9001 | Agent TCP monitor fires while Portainer API stays green | | Portainer upgrade breaks UI | UI keyword monitor fires while API status monitor stays green | | Database (BoltDB/PostgreSQL) corruption | API status may return 200 but environment list calls fail | | DNS misconfiguration | All monitors fire simultaneously | | Docker socket permissions revoked | Portainer API returns 500 on environment operations |

Portainer is the operational hub for Docker environments — when it fails, teams lose visibility into container health and the ability to respond to incidents. When agent connections break, entire remote environments go dark. Vigilmon gives you external monitoring of every critical path: the system status API, web UI, SSL certificates, and agent port TCP connectivity, so you know the moment something breaks and can restore container management before an incident escalates.

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