Custom CA trust

If you monitor HTTPS endpoints whose certificates are signed by a private CA (e.g. Smallstep, an internal PKI), Checkmate will mark them down with a TLS error until it trusts the CA. The server process needs the CA certificate in PEM format, available either to Node.js or to the OS trust store.

Option 1: NODE_EXTRA_CA_CERTS (simplest)

Mount your CA certificate into the server container and point Node.js at it:

services:
  server:
    environment:
      NODE_EXTRA_CA_CERTS: /certs/custom-ca.pem
    volumes:
      - ./certs:/certs:ro

Place custom-ca.pem in a local certs/ directory next to your compose file and restart the server. Node appends the file to its built-in CA bundle.

Option 2: OS-level trust

For cases where other libraries (not just Node) need to see the CA, build a derived image that installs the certificate in the system store. The Checkmate server image is Alpine-based, so use ca-certificates:

FROM ghcr.io/bluewave-labs/checkmate-backend:latest
USER root
RUN apk add --no-cache ca-certificates
COPY ./certs/custom-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

Reference this Dockerfile from a compose override and rebuild.

Exporting a Smallstep root CA

step certificate inspect --format pem $(step path)/certs/root_ca.crt > custom-ca.pem

Drop the resulting custom-ca.pem into the mount path and restart.

Verify trust

Exec into the running server container and confirm the certificate is where Node expects it:

docker exec -it <server_container> sh
ls /certs
node -e "require('tls').rootCertificates.length"

Security notes

Only trust CAs you operate. A rogue CA in the trust store lets any certificate it issues appear valid to Checkmate. Keep the certificate file read-only and avoid shipping it in images you publish.

See also

• Installing Checkmate
• SSL/TLS monitoring