Running Checkmate behind Pangolin. Architectural limitation

[txwgnd]

Hello everyone,

I'm sorry for opening an issue for this type of error again but here we are.

My core problem is that I cannot use Checkmate because there is always an error that the Client cannot reach the server.

My status quo:
I'm running my homelab on a server in my flat. To access it I'm using Pangolin as my reverse proxy, hosted on a vps in a remote datacenter. In Pangolin I created a ressource (reverse proxy entry) to route all the traffic from monitor.my-domain.com to my Checkmate instance running on 10.0.0.45:52345 in my homelab. The vps only accepts traffic on port 80 and 443. Everything else is dropped by the firewall.

When I run Checkmate with this Docker-Compose file I can access the webinterface but after clicking login or register it shows the error "Server not reachable".:

services:
server:
image: ghcr.io/bluewave-labs/checkmate-backend-mono:latest
pull_policy: always
restart: always
ports:
- 52345:52345
environment:
- UPTIME_APP_API_BASE_URL=http://10.0.0.45:52345/api/v1
- UPTIME_APP_CLIENT_HOST=https://monitor.my-domain.com
- DB_CONNECTION_STRING=mongodb://mongodb:27017/uptime_db
- CLIENT_HOST=http://10.0.0.45
- JWT_SECRET="my_secret"
depends_on:
- mongodb
mongodb:
image: ghcr.io/bluewave-labs/checkmate-mongo:latest
restart: always
command:
- mongod
- --quiet
- --bind_ip_all
volumes:
- /mnt/Main/Docker/Checkmate/MongoDB/data:/data/db
healthcheck:
test:
- CMD
- mongosh
- --eval
- db.adminCommand('ping')
- --quiet
interval: 5s
timeout: 30s
start_period: 0s
start_interval: 1s
retries: 30
networks: {}

When I change UPTIME_APP_CLIENT_HOST=https://monitor.my-domain.com to be UPTIME_APP_CLIENT_HOST=http://10.0.0.45 and then access it through 10.0.0.45:52345 locally in my network Checkmate is working completely fine. I can register new accounts and use the software as intended.

I read every other issue or discussion about this but it is not clear to me what to do in this case. I tried several different settings of the 3 environment variables UPTIME_APP_API_BASE_URL, UPTIME_APP_CLIENT_HOST, CLIENT_HOST but none of them seemed to work.

Hopefully we can figure this out because I think a lot of users are struggeling with this issue too!

Cheers

[Karlken28]

Hello,

Ran into the same problem and managed to solve it after quite a bit of trial and error.

---

The Issue

When Checkmate is behind a reverse proxy (in my case Pangolin, but the same applies to Traefik, Nginx, etc.), the app UI loads fine, but login/register fails with "Server not reachable".
The reason is that Checkmate needs its environment variables to point consistently to the final public URL, otherwise the backend rejects the client requests.

---

My Working Configuration

services:
  server:
    image: ghcr.io/bluewave-labs/checkmate-backend-mono:v3.2.0
    pull_policy: always
    restart: always
    ports:
      - "52345:52345"
    environment:
      # ✅ API base URL must match your public domain
      - UPTIME_APP_API_BASE_URL=https://monitor.example.com/api/v1
      # ✅ Client host should be the raw IP + port (reachable through the tunnel)
      - UPTIME_APP_CLIENT_HOST=https://<your-remote-ip>:52345
      # ✅ Backend must also use your public domain
      - CLIENT_HOST=https://monitor.example.com
      - DB_CONNECTION_STRING=mongodb://mongodb:27017/uptime_db
      - JWT_SECRET=change_this_secret
    depends_on:
      - mongodb

  mongodb:
    image: ghcr.io/bluewave-labs/checkmate-mongo:v3.2.0
    restart: always
    command: ["mongod", "--quiet", "--bind_ip_all"]
    volumes:
      - ./mongo/data:/data/db
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')", "--quiet"]
      interval: 5s
      timeout: 30s
      start_period: 0s
      start_interval: 1s
      retries: 30

---

Key Points

1. UPTIME_APP_API_BASE_URL → Public domain
   Must match the URL you actually type in your browser (https://monitor.example.com/api/v1).
   Otherwise the frontend will call a different endpoint that the browser cannot reach.

2. CLIENT_HOST → Public domain
   This tells the backend which host is serving the client. Needs to be the same as your public domain, not your local IP.

3. UPTIME_APP_CLIENT_HOST → Raw IP + port
   This one is tricky. It should be set to the raw IP of the machine where the Checkmate container is exposed, including the port (e.g. https://<your-vps-ip>:52345).
   Without this, the client will fail to establish the initial connection.

---

Reverse Proxy Setup

In my case I have two Docker setups:

• VPS → runs Pangolin in Docker
• Raspberry Pi (Ubuntu) → runs Docker for other homelab services

I decided to run Checkmate directly on the VPS (reachable at <remote-vps-ip>).
Then, in Pangolin I created a reverse proxy entry pointing my domain to that service:

monitor.example.com → http://<remote-vps-ip>:52345

With this setup, all browser requests hit monitor.example.com → Pangolin → <remote-vps-ip>:52345 → Checkmate.
Since all environment variables now align with this flow, login and registration finally work.

---

TL;DR

• Use your public domain for UPTIME_APP_API_BASE_URL and CLIENT_HOST.
• Use the raw IP + port for UPTIME_APP_CLIENT_HOST.
• Make sure your reverse proxy points monitor.example.com to the tunneled service.

---

Hopefully this clears things up