Running Checkstack with Docker

This guide walks you through deploying Checkstack using Docker.

Prerequisites

• Docker installed and running
• PostgreSQL database (or use a managed service like Supabase, Neon, etc.)

Required Environment Variables

Checkstack requires four environment variables to run:

Variable	Description	Requirements
DATABASE_URL	PostgreSQL connection string	Valid Postgres URI
ENCRYPTION_MASTER_KEY	Encrypts secrets in the database	64 hex characters (32 bytes)
BETTER_AUTH_SECRET	Signs session cookies and OAuth states	Minimum 32 characters
BASE_URL	Exact URL used to access Checkstack in the browser	e.g. http://192.168.1.123:3000 or https://status.example.com

Generating Secrets

ENCRYPTION_MASTER_KEY

Generate a secure 32-byte key:

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Using OpenSSL
openssl rand -hex 32

This produces a 64-character hexadecimal string (e.g., a1b2c3d4e5f6...).

BETTER_AUTH_SECRET

Generate a secure random string (minimum 32 characters):

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Using OpenSSL
openssl rand -base64 32

Quick Start

# Pull the latest image
docker pull ghcr.io/enyineer/checkstack:latest

# Run with required environment variables
docker run -d \
  --name checkstack \
  -e DATABASE_URL="postgresql://user:password@host:5432/checkstack" \
  -e ENCRYPTION_MASTER_KEY="<your-64-char-hex-key>" \
  -e BETTER_AUTH_SECRET="<your-32-char-secret>" \
  -e BASE_URL="http://192.168.1.123:3000" \
  -p 3000:3000 \
  ghcr.io/enyineer/checkstack:latest

Docker Compose (Recommended)

The Checkstack repository includes a ready-to-use docker-compose.yml in the project root that runs both Checkstack and PostgreSQL:

# Clone the repository (or download just the docker-compose.yml)
git clone https://github.com/enyineer/checkstack.git
cd checkstack

# Create your .env file with required secrets
cat > .env << EOF
POSTGRES_USER=checkstack
POSTGRES_PASSWORD=checkstack
POSTGRES_DB=checkstack
ENCRYPTION_MASTER_KEY=$(openssl rand -hex 32)
BETTER_AUTH_SECRET=$(openssl rand -base64 32)
BASE_URL="http://192.168.1.123:3000" # Must match exactly how you access Checkstack!
EOF

# Start everything
docker compose up -d

Updating the Checkstack Image

To update to a newer version:

# Pull the latest image
docker compose pull

# Recreate containers with the new image
docker compose up -d

Tip

You can also pin to a specific version by editing the image: line in docker-compose.yml:

image: ghcr.io/enyineer/checkstack:<version>

Quick Start (Single Container)

If you already have a PostgreSQL database, you can run Checkstack as a single container:

docker run -d \
  --name checkstack \
  -e DATABASE_URL="postgresql://user:password@host:5432/checkstack" \
  -e ENCRYPTION_MASTER_KEY="<your-64-char-hex-key>" \
  -e BETTER_AUTH_SECRET="<your-32-char-secret>" \
  -e BASE_URL="http://192.168.1.123:3000" \
  -p 3000:3000 \
  ghcr.io/enyineer/checkstack:latest

Optional Environment Variables

Variable	Default	Description
LOG_LEVEL	info	Logging level (debug, info, warn, error)
INTERNAL_URL	(falls back to BASE_URL)	Internal RPC URL for backend-to-backend calls. Set to K8s service name (e.g., http://checkstack-service:3000) for multi-pod load balancing.

Onboarding flow

Tip

After first start, you’ll have to create your first admin user.

Upon opening the page eg. at http://localhost:3000 you’ll be greeted with a signup form.

Health Check

Verify Checkstack is running:

curl http://localhost:3000/api/health

Troubleshooting

”ENCRYPTION_MASTER_KEY must be 32 bytes (64 hex characters)”

Your encryption key is not the correct length. Generate a new one using the commands above.

”BETTER_AUTH_SECRET must be at least 32 characters”

Your auth secret is too short. Generate a longer one using the commands above.

Onboarding screen does not appear / app loads empty or very slowly

This is almost always caused by a wrong BASE_URL. When BASE_URL points to an incorrect or unreachable address, the frontend cannot reach the backend for session and onboarding checks, which causes it to silently show empty state.

Make sure BASE_URL matches the EXACT URL YOU put into the browser address bar (including possible LAN IPs or the domain):

# Example (Docker on LAN):
BASE_URL=http://192.168.1.123:3000

# Example (Production):
BASE_URL=https://status.example.com

You can verify the value your container is using by checking the config endpoint:

curl http://localhost:3000/api/config
# Expected: {"baseUrl":"http://localhost:3000"}

If baseUrl in the response points to port 5173 or any other wrong address, update BASE_URL in your .env file and recreate the container:

docker compose up -d --force-recreate

Database connection errors

• Verify your DATABASE_URL is correct and the database is reachable
• Ensure PostgreSQL is running and accepting connections
• Check firewall rules allow connections between containers

Next Steps

• Configure authentication strategies
• Set up notification channels
• Create your first health check