docs: clarify Docker installation and add VPS deployment guide by Glazzze · Pull Request #3828 · bluewave-labs/Checkmate

Glazzze · 2026-08-07T15:32:21Z

Describe your changes

Clarified that the deprecated docker/dist-mono, docker/dist, and docker/dist-arm directories must not be used.
Documented the current single-image Checkmate deployment, including the separate MongoDB requirement.
Documented that legacy UPTIME_APP_* variables are ignored.
Added a VPS-focused Docker Compose example with Caddy automatic HTTPS.
Kept port 52345 internal for the VPS stack; only Caddy exposes ports 80 and 443.

Write your issue number after "Fixes "

Fixes #3823

Validation

Ran docker compose --env-file <test-env> -f docker/docker-compose.vps.yaml config.
Ran git diff --check.
Performed a self-review of the documentation and Compose configuration.

Checklist

I deployed the application locally.
I have performed a self-reviewing and testing of my code.
I have included the issue # in the PR.
N/A — this documentation-only change adds no application UI strings.
I have not included unrelated files or dependency changes.
N/A — no application UI styling or application configuration values were added.
My PR is granular and targeted to one issue.
I ran npm run format in server and client directories.
N/A — there is no UI change, so no screenshot or video is needed.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

ajhollid

Looks good for the most part. The old Docker directories/compose files no longer exist so the warning there isn't really relevant anymore and can be removed safely. Thanks for the contribution!

ajhollid · 2026-08-07T16:33:48Z

 ```

-Then open http://localhost:52345. If the app is reached at another origin (domain or LAN IP), set `CLIENT_HOST` accordingly. To build the image yourself, run `docker build -f docker/Dockerfile -t checkmate .` from a checkout. For TLS, put any reverse proxy (Caddy, Traefik, nginx) in front of port 52345.
+Then open http://localhost:52345. This is the only current Compose file for a direct HTTP installation; the retired `docker/dist-mono/`, `docker/dist/`, and `docker/dist-arm/` directories must not be used. If the app is reached at another origin (domain or LAN IP), set `CLIENT_HOST` accordingly. To build the image yourself, run `docker build -f docker/Dockerfile -t checkmate .` from a checkout.


These docker files/directories no longer exist, this warning isn't needed anymore I don't think

ajhollid · 2026-08-07T16:35:40Z

+      interval: 15s
+      timeout: 3s
+      start_period: 60s
+      retries: 3


Any reason why start_interval was removed here?

ajhollid · 2026-08-07T16:36:41Z

-The quickest way to run Checkmate is the reference Docker Compose file, which runs the all-in-one image (`ghcr.io/bluewave-labs/checkmate`) plus MongoDB:
+The quickest way to run Checkmate is the reference Docker Compose file. It starts two services: the all-in-one Checkmate application image (`ghcr.io/bluewave-labs/checkmate`) and a separate MongoDB service.
+
+> **What “all-in-one” means:** the Checkmate application is packaged in a single image; MongoDB is not embedded in that image and remains required. The reference Compose file starts MongoDB for you. For custom deployments, configure `DB_CONNECTION_STRING` to use an external MongoDB instance.


This content is already merged from your other PR, suggest you rebase this PR so its diff is accurate

Signed-off-by: Glazzze <2050408913@qq.com>

Glazzze · 2026-08-08T02:17:20Z

Rebased onto the latest develop, so the already-merged README change is no longer included in this PR. I also restored the existing healthcheck start_interval values (2s for Checkmate and 1s for MongoDB).

Signed-off-by: Glazzze <2050408913@qq.com>

Glazzze · 2026-08-09T01:45:15Z

Thanks for the review! I’ve removed the obsolete warning about the old Docker directories/compose files in d94347e. All formatting, build, and server-test checks are passing now. Could you please take another look when you have a chance?

gorkem-bwl · 2026-08-11T23:33:26Z

@ajhollid everything you asked for is in 👍

ajhollid

I think most of the issues are resolved, one thing that apppears to b emissing is the NODE_ENV var though 🤔 If the application runs in dev mode rate limiting is disabled, so it should probably be set.

Other than that, I'm not a devops guy, but won't all requests forwarded from Caddy share the same IP? If you have multiple users they'll run into the rate limit very quicky.

Signed-off-by: Glazzze <2050408913@qq.com>

Glazzze · 2026-08-12T03:04:07Z

Addressed in a43c3cc.

Set NODE_ENV=production in the VPS Compose example so production rate limiting is enabled.
Configured Express to trust the single Caddy proxy hop, allowing the rate limiter to use the client IP forwarded by Caddy.

Validation: git diff --check and Docker Compose config expansion (using a temporary compatibility copy because the local Compose v2.10.2 does not support the existing start_interval field).

ajhollid

Thanks for making the requested changes.

The addition of trust proxy should be configurable and false by default however, as we don't want to make assumptions about what kind of deployment a user has.

ajhollid · 2026-08-17T17:10:17Z

 }) => {
 	const allowedOrigin = envSettings.clientHost;
 	const app = express();
+	app.set("trust proxy", 1);


This shouldn't be set by default as it makes an assumption about deployment. This should default to false by default and be handled by an env var that is validated by the env var validation schema.

Signed-off-by: Glazzze <2050408913@qq.com>

Glazzze · 2026-08-18T03:26:26Z

Addressed in 895f4c8. TRUST_PROXY is now validated, defaults to false, and is explicitly enabled only for the VPS Compose deployment.

Copilot AI lite review requested due to automatic review settings August 7, 2026 15:32

Glazzze requested review from Br0wnHammer, ajhollid and karenvicent as code owners August 7, 2026 15:32

Copilot AI reviewed Aug 7, 2026

ajhollid requested changes Aug 7, 2026

View reviewed changes

Glazzze added 2 commits August 8, 2026 10:10

docs(readme): document secure VPS deployment

a60f2cc

fix(compose): restore healthcheck start intervals

6a6c6f0

Signed-off-by: Glazzze <2050408913@qq.com>

Glazzze force-pushed the docs/complete-installation-3823 branch from b3f7cd9 to 6a6c6f0 Compare August 8, 2026 02:14

docs(readme): remove obsolete Docker directory warning

d94347e

Signed-off-by: Glazzze <2050408913@qq.com>

ajhollid requested changes Aug 12, 2026

View reviewed changes

fix(vps): enable production proxy settings

a43c3cc

Signed-off-by: Glazzze <2050408913@qq.com>

ajhollid requested changes Aug 17, 2026

View reviewed changes

fix(server): make trust proxy configurable

895f4c8

Signed-off-by: Glazzze <2050408913@qq.com>

Uh oh!

Uh oh!

Conversation

Glazzze commented Aug 7, 2026

Describe your changes

Write your issue number after "Fixes "

Validation

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

ajhollid left a comment

Choose a reason for hiding this comment

Uh oh!

ajhollid Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

ajhollid Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

ajhollid Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Glazzze commented Aug 8, 2026

Uh oh!

Glazzze commented Aug 9, 2026

Uh oh!

gorkem-bwl commented Aug 11, 2026

Uh oh!

ajhollid left a comment

Choose a reason for hiding this comment

Uh oh!

Glazzze commented Aug 12, 2026

Uh oh!

ajhollid left a comment

Choose a reason for hiding this comment

Uh oh!

ajhollid Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

Glazzze commented Aug 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants