Merge pull request #3776 from bluewave-labs/chore/simplify-deployment

chore: simplify deployment
This commit is contained in:
Alexander Holliday authored and GitHub committed 2026-07-13 09:57:13 -07:00
commit fe703199f5
98 files changed
+556 -2333

No files matched your search

-2
View File
@@ -19,8 +19,6 @@ If you need to monitor internal HTTPS endpoints with certificates from private C
### Example Configurations
The `docker/dev/` directory contains example configurations:
- `docker-compose.custom-ca-example.yaml` - Example Docker Compose with custom CA
- `server-custom-ca.Dockerfile` - Example Dockerfile for OS-level CA trust
- `export-smallstep-ca.sh` - Helper script for Smallstep CA export
## Contributing to Documentation
+18 -33
View File
@@ -18,8 +18,8 @@ Add a volume mount for your CA certificate and set the environment variable:
```yaml
services:
server:
image: uptime_server:latest
checkmate:
image: ghcr.io/bluewave-labs/checkmate:latest
restart: always
ports:
- "52345:52345"
@@ -30,7 +30,6 @@ services:
volumes:
- ./certs:/certs:ro
depends_on:
- redis
- mongodb
```
@@ -52,67 +51,53 @@ For more comprehensive trust configuration, you can create a derived Dockerfile
### Custom Dockerfile
Create `docker/dev/server-custom-ca.Dockerfile`:
Create `checkmate-custom-ca.Dockerfile`:
```dockerfile
FROM node:20-alpine
FROM ghcr.io/bluewave-labs/checkmate:latest
# Install ca-certificates for Alpine
RUN apk add --no-cache ca-certificates
USER root
WORKDIR /app
RUN apt-get update \
&& apt-get install -y ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY ./server/package*.json ./
RUN npm install
COPY ./server/ ./
# Copy your custom CA certificate
# Copy your custom CA certificate (must have a .crt extension)
COPY ./certs/custom-ca.crt /usr/local/share/ca-certificates/
# Update CA certificates
RUN update-ca-certificates
EXPOSE 52345
USER node
CMD ["node", "src/index.js"]
# Node uses its bundled CA store by default; make it read the system store
ENV NODE_OPTIONS="--use-system-ca"
```
### Docker Compose Override
Create `docker/dev/docker-compose.custom-ca.yaml`:
Create `docker-compose.custom-ca.yaml`:
```yaml
services:
server:
checkmate:
build:
context: .
dockerfile: server-custom-ca.Dockerfile
dockerfile: checkmate-custom-ca.Dockerfile
restart: always
ports:
- "52345:52345"
env_file:
- server.env
depends_on:
- redis
- mongodb
```
Run with: `docker-compose -f docker-compose.yaml -f docker-compose.custom-ca.yaml up`
Run with: `docker compose -f docker-compose.yaml -f docker-compose.custom-ca.yaml up`
## Alpine Linux Considerations
## Base Image Considerations
Since Checkmate uses Alpine Linux as the base image, you need to install the `ca-certificates` package:
```dockerfile
# Install ca-certificates for Alpine
RUN apk add --no-cache ca-certificates
# Copy and update CA certificates
COPY ./certs/custom-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates
```
The Checkmate image is Debian-based (`node:22-slim`), which does not ship the `ca-certificates` package — install it before running `update-ca-certificates` (see the Dockerfile above). Certificates dropped into `/usr/local/share/ca-certificates/` must have a `.crt` extension, and Node only consults the system store when started with `--use-system-ca`. For most setups the `NODE_EXTRA_CA_CERTS` compose approach is simpler.
## Smallstep CA Configuration
+56
View File
@@ -0,0 +1,56 @@
# checkmate.so hosting (demo + staging)
Config for BlueWave's hosted instances at `demo.checkmate.so` and
`staging.checkmate.so`: one host, one nginx gateway terminating TLS, two
independent Checkmate stacks running the mono image
(`ghcr.io/bluewave-labs/checkmate`), plus a shared
[Capture](https://github.com/bluewave-labs/capture) agent. It replaces the old
`docker/unified/` setup (nginx client images + separate backend images + a
republished Mongo image) and doubles as a worked example of running the mono
image behind a TLS reverse proxy.
## How deploys work
`.github/workflows/build-image.yml` builds and pushes the image, then SSHes in
and runs `docker compose pull <service> && docker compose up -d <service>` in
this directory:
- merge to `develop` → image tagged `:develop` → `checkmate-staging` recreated
- merge to `master` → image tagged `:master` → `checkmate-demo` (prod) recreated
The host keeps a git checkout of this repo (on `develop`); the deploy does
`git pull` first so compose changes land with the code. Note the deploy only
recreates the checkmate service — changes to `gateway/nginx.conf` or the mongo
services need a manual `docker compose up -d` / gateway restart on the host.
## Host-local files (not committed)
Kept next to this compose file on the host:
- `server-prod.env` / `server-staging.env` — Checkmate server env
(`DB_CONNECTION_STRING`, `JWT_SECRET`, `CLIENT_HOST=https://demo.checkmate.so`
etc.). The old `UPTIME_APP_*` client vars are no-ops now and can be removed;
if a client override is ever needed, use the `CLIENT_CONFIG_*` vars (see the
Configuration section of the root README).
- `mongo-prod.env` / `mongo-staging.env` — Mongo credentials.
- `mongo/data-prod` / `mongo/data-staging` — Mongo data directories.
TLS certs live in `/etc/letsencrypt` (see `certbot-compose.yaml`; certbot
answers ACME challenges on port 8080 behind the gateway).
## One-time migration from docker/unified
1. `cd ~/checkmate && git pull` (must be on a branch containing this directory).
2. Stop the old stack: `cd docker/unified && docker compose down`.
3. Move host-local files here:
`mv docker/unified/{server-prod.env,server-staging.env,mongo-prod.env,mongo-staging.env} docs/hosting/checkmate-so/`
`mv docker/unified/mongo docs/hosting/checkmate-so/mongo`
4. **Check the Mongo data version before first start.** The old
`checkmate:mongo-*` images were built `FROM mongo` (floating latest), so the
data files follow whatever version was current at their last image build. Run
`db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })`
against the old container first and make the compose's `mongo:` tag match
(checked 2026-07-09: both stacks report FCV 8.2, hence the `mongo:8.2` pin
here). A lower pin than the data's FCV will refuse to start; a higher one
should step up one release at a time.
5. `cd docs/hosting/checkmate-so && docker compose up -d`.
+19
View File
@@ -0,0 +1,19 @@
version: "3"
services:
webserver:
image: nginx:latest
ports:
- 80:80
- 443:443
restart: always
volumes:
- ./nginx/conf.d/:/etc/nginx/conf.d/:ro
- ./certbot/www/:/var/www/certbot/:ro
certbot:
image: certbot/certbot:latest
volumes:
- ./certbot/www/:/var/www/certbot/:rw
- ./certbot/conf/:/etc/letsencrypt/:rw
depends_on:
- webserver
@@ -0,0 +1,122 @@
# BlueWave's hosted demo + staging instances: one nginx gateway terminating TLS
# in front of two independent Checkmate stacks, both running the mono image
# (ghcr.io/bluewave-labs/checkmate). Doubles as a worked example of putting a
# TLS proxy in front of the image.
#
# Deployed by .github/workflows/build-image.yml (deploy-staging / deploy-demo
# jobs). Env files (server-prod.env, server-staging.env, mongo-prod.env,
# mongo-staging.env) live on the host next to this file and are not committed.
services:
# Gateway (single entry point)
gateway:
image: nginx:1.27.1-alpine
container_name: checkmate-gateway
restart: always
ports:
- "80:80"
- "443:443"
volumes:
- /etc/letsencrypt:/etc/nginx/ssl:ro
- ./gateway/nginx.conf:/etc/nginx/conf.d/default.conf:ro
# Prod: demo.checkmate.so -----
checkmate-demo:
image: ghcr.io/bluewave-labs/checkmate:master
container_name: checkmate-demo
restart: always
env_file:
- server-prod.env
stop_grace_period: 60s
healthcheck:
test:
[
"CMD",
"node",
"-e",
"require('http').get('http://localhost:52346/livez',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))",
]
interval: 15s
timeout: 3s
start_period: 60s
start_interval: 2s
retries: 3
depends_on:
mongodb-prod:
condition: service_healthy
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
mongodb-prod:
image: mongo:8.2
container_name: mongodb-prod
restart: always
command: ["mongod", "--quiet", "--bind_ip_all"]
volumes:
- ./mongo/data-prod:/data/db
env_file:
- mongo-prod.env
healthcheck:
test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')", "--quiet"]
interval: 5s
timeout: 30s
start_period: 0s
start_interval: 1s
retries: 30
# Staging: staging.checkmate.so -----
checkmate-staging:
image: ghcr.io/bluewave-labs/checkmate:develop
container_name: checkmate-staging
restart: always
env_file:
- server-staging.env
stop_grace_period: 60s
healthcheck:
test:
[
"CMD",
"node",
"-e",
"require('http').get('http://localhost:52346/livez',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))",
]
interval: 15s
timeout: 3s
start_period: 60s
start_interval: 2s
retries: 3
depends_on:
mongodb-staging:
condition: service_healthy
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
mongodb-staging:
image: mongo:8.2
container_name: mongodb-staging
restart: always
command: ["mongod", "--quiet", "--bind_ip_all"]
volumes:
- ./mongo/data-staging:/data/db
env_file:
- mongo-staging.env
healthcheck:
test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')", "--quiet"]
interval: 5s
timeout: 30s
start_period: 0s
start_interval: 1s
retries: 30
# Shared utils
capture:
image: ghcr.io/bluewave-labs/capture:latest
container_name: capture
restart: unless-stopped
ports:
- "59232:59232"
environment:
- API_SECRET=my_secret
- GIN_MODE=release
volumes:
- /etc/os-release:/etc/os-release:ro
@@ -0,0 +1,54 @@
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
server {
listen 80;
server_name demo.checkmate.so staging.checkmate.so;
location /.well-known/acme-challenge/ {
# Forward the challenge to Certbot listening on 8080
proxy_pass http://172.17.0.1:8080;
}
location / {
return 301 https://$host$request_uri;
}
}
# --- DEMO: demo.checkmate.so ---
server {
listen 443 ssl;
server_name demo.checkmate.so;
ssl_certificate /etc/nginx/ssl/live/demo.checkmate.so/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/live/demo.checkmate.so/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
location / {
# The mono image serves both the SPA and the API
proxy_pass http://checkmate-demo:52345;
}
}
# --- STAGING: staging.checkmate.so ---
server {
listen 443 ssl;
server_name staging.checkmate.so;
ssl_certificate /etc/nginx/ssl/live/staging.checkmate.so/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/live/staging.checkmate.so/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
location / {
# The mono image serves both the SPA and the API
proxy_pass http://checkmate-staging:52345;
}
}