Uptime Kuma — Monitor Setup Guide¶

Configure Uptime Kuma to monitor all 13 Forma3D.Connect staging containers

Quick Start: Setup Script (Recommended)¶

The fastest way to configure all monitors is to run the setup script, which uses Uptime Kuma's Socket.IO API.

Note: The Backup import feature in Uptime Kuma is deprecated and unreliable. Use the script approach instead.

Step 1: Run the Setup Script¶

From the project root:

node deployment/monitoring/setup-uptime-kuma.mjs

The script will prompt for your Uptime Kuma username and password, then create all 16 entries (3 groups + 13 monitors).

Step 2: Verify¶

After the script completes, you should see 3 groups with 13 monitors total:

Note: pgAdmin is an on-demand container managed via the Developer Tools settings page. It is not monitored by Uptime Kuma since it is intentionally stopped most of the time.

All monitors should turn green within 1–2 minutes if the containers are healthy.

Monitor Overview¶

Public Endpoints (HTTPS — through Traefik)¶

These monitors verify the full request path: DNS → Traefik → TLS → Container → Health endpoint.

Backend Services (HTTP — internal Docker network)¶

These monitors check services directly inside the Docker network, bypassing Traefik. If a public endpoint is down but the internal monitor is up, the issue is in Traefik routing.

Note: Internal URLs like http://order-service:3001 work because Uptime Kuma is on the same forma3d-network Docker network as all other containers.

Infrastructure (TCP + HTTP — internal)¶

Alternative: Manual Setup¶

If the backup import doesn't work (e.g., version mismatch), add monitors manually.

Add a Group¶

1. Click + Add New Monitor
2. Monitor Type: Group
3. Friendly Name: e.g., Public Endpoints
4. Click Save

Add an HTTP Monitor (example: Gateway)¶

1. Click + Add New Monitor
2. Monitor Type: HTTP(s)
3. Friendly Name: Gateway (API)
4. URL: https://staging-connect-api.forma3d.be/health/live
5. Heartbeat Interval: 60 seconds
6. Retries: 3
7. Heartbeat Retry Interval: 30 seconds
8. Under Advanced, set:
9. Accepted Status Codes: 200-299
10. Max. Redirects: 10
11. Under Monitor Group, select the parent group
12. Click Save

Add a TCP Port Monitor (Redis)¶

1. Click + Add New Monitor
2. Monitor Type: TCP Port
3. Friendly Name: Redis
4. Hostname: redis
5. Port: 6379
6. Heartbeat Interval: 60 seconds
7. Click Save

Complete Monitor List for Manual Entry¶

Copy-paste these values when adding monitors manually:

GROUP: Public Endpoints
├── Gateway (API)        | HTTP(s) | https://staging-connect-api.forma3d.be/health/live  | 60s
├── Web App              | HTTP(s) | https://staging-connect.forma3d.be/health/live      | 60s
├── Docs Site            | HTTP(s) | https://staging-connect-docs.forma3d.be/health/live | 60s
├── Event Catalog        | HTTP(s) | https://staging-connect-eventcatalog.forma3d.be      | 120s
├── Status Page (Self)   | HTTP(s) | https://staging-connect-status.forma3d.be            | 120s
└── Log Viewer (Dozzle)  | HTTP(s) | https://staging-connect-logs.forma3d.be              | 120s

GROUP: Backend Services
├── Order Service        | HTTP(s) | http://order-service:3001/health                    | 60s
├── Print Service        | HTTP(s) | http://print-service:3002/health                    | 60s
├── Shipping Service     | HTTP(s) | http://shipping-service:3003/health                 | 60s
├── GridFlock Service    | HTTP(s) | http://gridflock-service:3004/health                | 60s
└── Slicer               | HTTP(s) | http://slicer:3010/health                           | 60s

GROUP: Infrastructure
├── Redis                | TCP     | redis:6379                                          | 60s
└── Traefik              | HTTP(s) | http://traefik:8080/ping                            | 60s

Status Page Setup¶

Two public status pages are created — one customer-facing, one for the team.

Automated Setup (Recommended)¶

node deployment/monitoring/setup-uptime-kuma-status-pages.mjs

This creates both pages in one go. You'll be prompted for your credentials.

Status Pages Overview¶

Both pages are public — no login required to view.

Full URLs:

• https://staging-connect-status.forma3d.be/status/forma3d
• https://staging-connect-status.forma3d.be/status/ops

Public Page Sections¶

Operations Page Sections¶

Manual Setup (Alternative)¶

1. Navigate to Status Pages (top nav bar)
2. Click + New Status Page
3. Name: Forma3D Connect — Status, Slug: forma3d
4. Click Next
5. Add sections and drag monitors from the list
6. Uncheck Show Powered By (optional)
7. Click Save

Repeat for the Operations page with slug ops.

Notifications (Optional)¶

To receive alerts when a service goes down:

Email Notification¶

1. Go to Settings > Notifications
2. Click Setup Notification
3. Notification Type: Email (SMTP)
4. Configure your SMTP settings
5. Click Test then Save

Apply to All Monitors¶

After creating a notification channel:

1. Edit each monitor (or use the group settings)
2. Under Notifications, check the notification channel
3. Click Save

Troubleshooting¶

Internal monitors show "down" but public endpoints are "up"¶

This means Uptime Kuma cannot resolve the Docker service names. Verify that Uptime Kuma is on the forma3d-network:

docker inspect forma3d-uptime-kuma --format='{{json .NetworkSettings.Networks}}' | jq

Traefik monitor (port 8080) shows "down"¶

Traefik's API/ping endpoint runs on port 8080 by default. If the Traefik configuration doesn't expose port 8080 internally, switch to monitoring via a public URL:

• Change the Traefik monitor URL to: https://staging-connect-api.forma3d.be/health/live
• This verifies Traefik is routing correctly (same as Gateway, but serves as an implicit Traefik check)

Redis TCP monitor shows "down"¶

Verify Redis is reachable from within the Docker network:

docker exec forma3d-uptime-kuma sh -c "nc -z redis 6379 && echo OK || echo FAIL"

All monitors show "Pending"¶

Monitors take up to one interval period (60s) to perform the first check. Wait 1-2 minutes after import.

Script Location¶

The setup scripts are stored in the repository:

deployment/monitoring/setup-uptime-kuma.mjs               # Monitor setup (run first)
deployment/monitoring/setup-uptime-kuma-status-pages.mjs   # Status page setup (run second)
deployment/monitoring/uptime-kuma-backup.json               # Reference only (backup import is deprecated)

Update the scripts whenever you add or modify containers in the stack.

Document Version: 1.0 Last Updated: 2026-02-16 Maintainer: AI-generated, review before production use