Docs and docker-compose for different use cases

[alexdelprete]

Hi,

wanted to test checkmate for my homelab, but the provided compose example doesn't work in my case: I have central instances of all databases (mongodb, redis, mariadb, postgresql, etc.).

So all my homelab services needing to point to a db/service is configured to use the central instances.

I never had an issue with other services, but I'm not able to bring up checkmate to test it.

In the client env vars docs I read this:

in the compose file the vars are UPTIME_ not VITE_. Apart from that, I first tried to use the docker hostname of the backend server. Then I read in a discussion that docker hostnames don't work because the connection is from the user browser. If that's true, it means that if I'm using a reverse proxy (I use Traefik) I should create a specific entry for the backend. But it's a little bit weird if it works like that. I mean, the frontend instance should connect directly to the backend, why is the user browser involved? I hope I misunderstood the discussion. :)

In the server env var docs I read that a lot of vars are REQUIRED. Is that correct?

Could you clarify (in the docs mainly) what are the JWT tokens, refresh token, etc. and how to create them the first time? A little bit of context would be required to understand the purpose of those.

The main thing for me is the DB_CONNECTION_STRING: the provided example is for a compose file with mongodb, but I'm not using it since I already have it installed, and it requires authentication. So I used this connection string:

DB_CONNECTION_STRING: mongodb://user:[email protected]:27017/checkmate

On startup, the backend (I believe it's the backend at least), throws these errors:

(node:1) [MONGOOSE] Warning: Duplicate schema index on {"teamId":1} found. This is often due to declaring an index using both "index: true" and "schema.index()". Please remove the duplicate index definition.
(Use `node --trace-warnings ...` to show where the warning was created)
(node:1) [MONGOOSE] Warning: `errors` is a reserved schema pathname and may break some functionality. You are allowed to use it, but use at your own risk. To disable this warning pass `suppressReservedKeysWarning` as a schema option.
2025-04-19T16:30:56.860Z error:(connect) Authentication failed.
2025-04-19T16:30:56.862Z error: [Server](startApp) Authentication failed.
(node:1) [MONGOOSE] Warning: Duplicate schema index on {"teamId":1} found. This is often due to declaring an index using both "index: true" and "schema.index()". Please remove the duplicate index definition.
(Use `node --trace-warnings ...` to show where the warning was created)
(node:1) [MONGOOSE] Warning: `errors` is a reserved schema pathname and may break some functionality. You are allowed to use it, but use at your own risk. To disable this warning pass `suppressReservedKeysWarning` as a schema option.
2025-04-19T16:30:59.533Z error:(connect) Authentication failed.
2025-04-19T16:30:59.536Z error: [Server](startApp) Authentication failed.

This is the docker-compose file content:

Notes:

• the urls with domain.dom are the default lan domain
• the urls with domain.net are managed by Traefik

services:
  checkmate-frontend:
    image: bluewaveuptime/uptime_client:latest
    container_name: checkmate-frontend
    hostname: checkmate-frontend
    restart: unless-stopped
    labels:
      - wud.watch=false
      - com.centurylinklabs.watchtower.enable=true
    environment:
      UPTIME_APP_API_BASE_URL: "https://checkmate-backend.domain.net/api/v1"
      UPTIME_APP_LOG_LEVEL: "debug"
    ports:
      - "5173:5173"
    depends_on:
      - checkmate-backend
    networks:
      - proxy

  checkmate-backend:
    image: bluewaveuptime/uptime_server:latest
    container_name: checkmate-backend
    hostname: checkmate-backend
    restart: unless-stopped
    labels:
      - wud.watch=false
      - com.centurylinklabs.watchtower.enable=true
    environment:
      CLIENT_HOST: "https://checkmate.domain.net"
      JWT_SECRET: "aaaaaaaaaaaaaaaaaaaaaa"
      DB_TYPE: "MongoDB"
      DB_CONNECTION_STRING: mongodb://user:[email protected]:27017/checkmate
      REDIS_HOST: "redis.domain.dom"
      REDIS_PORT: 6379
      TOKEN_TTL: "99d"
      PAGESPEED_API_KEY: "ffffffffffffffffffffffffffff"
      SYSTEM_EMAIL_HOST: "smtp.domain.dom"
      SYSTEM_EMAIL_PORT: 2500
      SYSTEM_EMAIL_ADDRESS: "[email protected]"
      SYSTEM_EMAIL_PASSWORD: ""
      REFRESH_TOKEN_SECRET: "bbbbbbbbbbbbbbbbbbb"
      REFRESH_TOKEN_TTL: "99d"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "5000:5000"
    networks:
      - proxy

networks:
  proxy:
    external: true

[ajhollid]

Hi @alexdelprete ,

The frontend and the backend are two separate and distinct applications.

The backend is a RESTful API and is accessible via the port that you expose in your docker compose file.

The frontend is a React single page application that runs in your browser. This is the way single page applications work, they are bundled as JavaScript and sent to your browser where they are run.

So yes, the frotnend is not part of your docker network and you should provide the external address of your backend, not the internal docker address.

As for the env vars being prefixed with UPTIME_ in the docker compose file, this is intentional. The issue is that vars prefixed with VITE_ are interpolated at build time, not run time. If you want to set vars after build time, as is the case when you want to set variables with docker compose, you need to go through the built code and replace the VITE_ prefixed vars with the ones you want. You don't need to do anything RE this, it is handled by a script.

The reason the VITE_ prefixed vars are listed in the client env vars seciton is those are the vars you need when building the frontend, as is the case for anyone building and running the dev branch.

Finally, with respect to the Mongo issue, I can't really help troubleshoot this one as it's a very specific issue to your particular setup, but the connection is very simple and looks like this:

const connectionString =
	process.env.DB_CONNECTION_STRING || "mongodb://localhost:27017/uptime_db";
await mongoose.connect(connectionString);

The connection string is passed directly to Mongoose without any processing on our end, so I suggest taking a look at the Mongoose connection docs and seeing if there's anything there that will help you get connected.

Hope that helps!

[alexdelprete]

Thanks for your kind reply.

So yes, the frotnend is not part of your docker network and you should provide the external address of your backend, not the internal docker address.

As you can see from my compose file, I have provided the external address.

The connection string is passed directly to Mongoose without any processing on our end, so I suggest taking a look at the Mongoose connection docs and seeing if there's anything there that will help you get connected.

I had already checked it, that's why I provided user:password in the connection string.

I would expect everything you explained to be in the docs, just to cover the different user environments.

Anyhow, this is the log of the backend: I don't know what those authentication errors refer to, the app, the db...any hint?

(node:1) [MONGOOSE] Warning: Duplicate schema index on {"teamId":1} found. This is often due to declaring an index using both "index: true" and "schema.index()". Please remove the duplicate index definition.
(Use `node --trace-warnings ...` to show where the warning was created)
(node:1) [MONGOOSE] Warning: `errors` is a reserved schema pathname and may break some functionality. You are allowed to use it, but use at your own risk. To disable this warning pass `suppressReservedKeysWarning` as a schema option.
2025-04-21T22:18:17.221Z error:(connect) Authentication failed.
2025-04-21T22:18:17.229Z error: [Server](startApp) Authentication failed.
(node:1) [MONGOOSE] Warning: Duplicate schema index on {"teamId":1} found. This is often due to declaring an index using both "index: true" and "schema.index()". Please remove the duplicate index definition.
(Use `node --trace-warnings ...` to show where the warning was created)
(node:1) [MONGOOSE] Warning: `errors` is a reserved schema pathname and may break some functionality. You are allowed to use it, but use at your own risk. To disable this warning pass `suppressReservedKeysWarning` as a schema option.
2025-04-21T22:18:25.761Z error:(connect) Authentication failed.
2025-04-21T22:18:25.765Z error: [Server](startApp) Authentication failed.

And this is the log from the frontend: don't know what host not found means there. Any hint?

/docker-entrypoint.sh: Sourcing /docker-entrypoint.d/15-local-resolvers.envsh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/env.sh
UPTIME_APP_LOG_LEVEL=debug
UPTIME_APP_API_BASE_URL=https://checkmate-backend.domain.net/api/v1
/docker-entrypoint.sh: Configuration complete; ready for start up
2025/04/21 22:26:23 [emerg] 1#1: host not found in upstream "server" in /etc/nginx/conf.d/default.conf:19
nginx: [emerg] host not found in upstream "server" in /etc/nginx/conf.d/default.conf:19

[akhilrs]

@alexdelprete You need to pass authSource in the connection string when authenticating with user and pass.

So your connection string should looks something like this
mongodb://user:[email protected]:27017/checkmate?authSource=admin