docs: add guide and tooling for custom CA trust in Dockerized Checkmate (Fixes #2747)

This commit is contained in:
Tafadzwa Chiwozva committed 2025-08-13 17:50:30 -04:00
1 parent f2e2d5c2ed
commit f381b0ce4a
11 files changed
+1002

No files matched your search

+38
View File
@@ -0,0 +1,38 @@
# Checkmate Documentation
Welcome to the Checkmate documentation. This directory contains guides and references for various aspects of Checkmate deployment and configuration.
## Available Documentation
### Deployment & Configuration
- **[Custom CA Trust Guide](./custom-ca-trust.md)** - Configure Checkmate to trust custom Certificate Authorities
- **[Custom CA Quick Reference](./custom-ca-quick-reference.md)** - Quick setup guide for custom CA trust
## Docker Configuration
### Custom CA Trust
If you need to monitor internal HTTPS endpoints with certificates from private Certificate Authorities (like Smallstep), see our custom CA trust documentation:
- **Full Guide**: [Custom CA Trust Guide](./custom-ca-trust.md)
- **Quick Reference**: [Custom CA Quick Reference](./custom-ca-quick-reference.md)
### 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
If you find issues or want to improve the documentation:
1. Check existing issues and discussions
2. Submit a pull request with your changes
3. Follow the same markdown formatting style
4. Include practical examples and code snippets
## Getting Help
- [GitHub Discussions](https://github.com/bluewave-labs/checkmate/discussions)
- [Discord Channel](https://discord.gg/NAb6H3UTjK)
- [Documentation Portal](https://docs.checkmate.so/)
+60
View File
@@ -0,0 +1,60 @@
# Custom CA Trust - Quick Reference
## Fast Setup (Node-level)
1. **Export your CA certificate:**
```bash
# For Smallstep
step certificate inspect --format pem step-ca/root_ca.crt > docker/dev/certs/custom-ca.pem
```
2. **Use the provided example override:**
```bash
docker-compose -f docker-compose.yaml -f docker-compose.custom-ca-example.yaml up -d
```
3. **Or manually update docker-compose.yaml:**
```yaml
services:
server:
environment:
NODE_EXTRA_CA_CERTS: /certs/custom-ca.pem
volumes:
- ./certs:/certs:ro
```
## Alternative Setup (OS-level)
1. **Use custom Dockerfile:**
```bash
docker-compose -f docker-compose.yaml -f docker-compose.custom-ca.yaml up
```
## File Structure
```
docker/dev/
├── docker-compose.yaml
├── docker-compose.custom-ca-example.yaml # Example config
├── certs/
│ ├── README.md
│ └── custom-ca.pem # Your CA certificate
└── export-smallstep-ca.sh # Helper script
```
## Environment Variables
- `NODE_EXTRA_CA_CERTS=/certs/custom-ca.pem` - Node.js trust
- Mount `./certs:/certs:ro` - Volume mount
## Security
- ✅ Only trust CAs you control
- ✅ Use read-only volume mounts
- ✅ Keep certificates out of version control
- ❌ Never trust untrusted CAs
## Troubleshooting
- Check container logs: `docker-compose logs server`
- Verify certificate: `docker exec -it <container> ls -la /certs/`
- Test connection: `docker exec -it <container> wget --ca-certificate=/certs/custom-ca.pem https://your-internal-site.com`
## Full Documentation
See [Custom CA Trust Guide](./custom-ca-trust.md) for detailed instructions.
+234
View File
@@ -0,0 +1,234 @@
# Custom Certificate Authority Trust
This guide explains how to configure Checkmate to trust custom Certificate Authorities (CAs) when running in Docker, particularly useful for internal/private CAs like Smallstep.
## Understanding Certificate Authorities
Certificate Authorities (CAs) are entities that issue and manage digital certificates. While public CAs (like Let's Encrypt, DigiCert) are trusted by default in most systems, private or internal CAs (like those issued by Smallstep, internal PKI systems) require explicit trust configuration.
When Checkmate monitors HTTPS endpoints with certificates from private CAs, it may show them as "DOWN" due to certificate validation failures, even if the service is actually accessible.
## Node-level Trust Approach
The simplest approach is to mount your custom CA certificate and configure Node.js to trust it using the `NODE_EXTRA_CA_CERTS` environment variable.
### Docker Compose Configuration
Add a volume mount for your CA certificate and set the environment variable:
```yaml
services:
server:
image: uptime_server:latest
restart: always
ports:
- "52345:52345"
env_file:
- server.env
environment:
NODE_EXTRA_CA_CERTS: /certs/custom-ca.pem
volumes:
- ./certs:/certs:ro
depends_on:
- redis
- mongodb
```
### Directory Structure
Create a `certs` directory in your Docker Compose project root:
```
docker/dev/
├── docker-compose.yaml
├── certs/
│ └── custom-ca.pem
└── ...
```
## OS-level Trust Approach (Debian-based)
For more comprehensive trust configuration, you can create a derived Dockerfile that installs your CA at the OS level.
### Custom Dockerfile
Create `docker/dev/server-custom-ca.Dockerfile`:
```dockerfile
FROM node:20-alpine
# Install ca-certificates for Alpine
RUN apk add --no-cache ca-certificates
WORKDIR /app
COPY ./server/package*.json ./
RUN npm install
COPY ./server/ ./
# Copy your custom CA certificate
COPY ./certs/custom-ca.crt /usr/local/share/ca-certificates/
# Update CA certificates
RUN update-ca-certificates
EXPOSE 52345
CMD ["node", "src/index.js"]
```
### Docker Compose Override
Create `docker/dev/docker-compose.custom-ca.yaml`:
```yaml
services:
server:
build:
context: .
dockerfile: server-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`
## Alpine Linux 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
```
## Smallstep CA Configuration
If you're using Smallstep as your internal CA, you can export the root CA certificate:
### Export Smallstep Root CA
```bash
# Export the root CA certificate
step certificate inspect --format pem step-ca/root_ca.crt > custom-ca.pem
# Or if you have the CA URL configured
step certificate inspect --format pem $(step path)/certs/root_ca.crt > custom-ca.pem
```
### Using the Exported Certificate
1. Copy the exported `custom-ca.pem` to your `docker/dev/certs/` directory
2. Use either the Node-level or OS-level approach above
3. Restart your Checkmate server container
## Security Considerations
⚠️ **Important Security Warning**: Only trust CAs that you control or explicitly trust. Adding untrusted CAs can compromise the security of your monitoring system.
- **Private CAs**: Only trust CAs from your organization's PKI infrastructure
- **Self-signed certificates**: Consider using proper CA infrastructure instead
- **Certificate validation**: Ensure your CA certificates are valid and not expired
- **Access control**: Limit access to the CA certificate files in production
## Troubleshooting
### Verify CA Trust
Test if your CA is trusted by the container:
```bash
# Enter the running container
docker exec -it <container_name> sh
# Check if the CA is in the trust store
ls -la /usr/local/share/ca-certificates/
cat /etc/ssl/certs/ca-certificates.crt | grep -A 5 -B 5 "YOUR_CA_NAME"
```
### Common Issues
1. **Permission denied**: Ensure the CA certificate file has proper read permissions
2. **Certificate format**: Use PEM format (.pem, .crt) for best compatibility
3. **Container restart**: Always restart the container after adding new CA certificates
4. **Path issues**: Verify the certificate path in your volume mounts
## Example: Complete Working Setup
Here's a complete example for a Smallstep CA setup. This demonstrates both the baseline failure (expected) and the custom CA success:
### Baseline Test (Should Fail)
1. **Start Checkmate without custom CA trust:**
```bash
cd docker/dev
docker-compose up -d
```
2. **Test connection to internal HTTPS endpoint:**
```bash
# This should fail with TLS error (unknown CA)
docker-compose exec server node -e "
const https = require('https');
https.get('https://your-internal-site.com', res => {
console.log('STATUS:', res.statusCode);
}).on('error', e => {
console.error('ERR:', e.message);
});
"
```
**Expected result**: TLS error due to unknown CA
### Custom CA Test (Should Succeed)
1. **Export Smallstep Root CA:**
```bash
step certificate inspect --format pem step-ca/root_ca.crt > docker/dev/certs/smallstep-root-ca.pem
```
2. **Update docker-compose.yaml with custom CA trust:**
```yaml
services:
server:
environment:
NODE_EXTRA_CA_CERTS: /certs/smallstep-root-ca.pem
volumes:
- ./certs:/certs:ro
```
3. **Restart with custom CA:**
```bash
docker-compose down
docker-compose -f docker-compose.yaml -f docker-compose.custom-ca-example.yaml up -d
```
4. **Test the same connection:**
```bash
# This should now succeed
docker-compose exec server node -e "
const https = require('https');
https.get('https://your-internal-site.com', res => {
console.log('STATUS:', res.statusCode);
}).on('error', e => {
console.error('ERR:', e.message);
});
"
```
**Expected result**: HTTP 200 OK
### Verification
- **Baseline**: TLS failure proves default behavior (unknown CA)
- **Custom CA**: TLS success proves custom CA trust is working
- **Both tests must pass** to confirm the feature works correctly
Your Checkmate server should now trust certificates issued by your Smallstep CA, allowing you to monitor internal HTTPS endpoints without disabling SSL validation.