Quickstart with Docker Compose

This tutorial starts the integrated OpsKnight runtime and PostgreSQL on one Docker host. Use it for an evaluation or small test environment. For production, start with Choose a deployment.

Before you begin

Install Git, Docker Engine, and Docker Compose v2. Ports 3000 and 5432 must be free unless you change APP_PORT and POSTGRES_PORT. Choose an explicit 2.0 image tag or immutable digest; do not rely on the Compose compatibility default or a moving latest tag.

1. Prepare the configuration

git clone https://github.com/opsknight-labs/opsknight.git
cd opsknight
cp env.example .env

Edit .env and set at least:

OPSKNIGHT_IMAGE=ghcr.io/opsknight-labs/opsknight:2.0.0
POSTGRES_PASSWORD=<unique-database-password>
NEXTAUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXTAUTH_SECRET=<random-base64-secret>
ENCRYPTION_KEY=<64-hex-character-key>

Generate the application secrets with openssl rand -base64 32 and openssl rand -hex 32. Use the externally reachable HTTPS origin for both URL values behind a proxy. Keep ENCRYPTION_KEY stable and backed up; losing it makes encrypted integration credentials unrecoverable.

2. Start and verify OpsKnight

docker compose -f deploy/compose/docker-compose.yml pull
docker compose -f deploy/compose/docker-compose.yml up -d --wait
docker compose -f deploy/compose/docker-compose.yml ps
curl --fail --show-error 'http://localhost:3000/api/health?mode=readiness'

Both opsknight-db and opsknight-app should be running and healthy. Readiness must return HTTP 200 with a healthy status. If startup fails, inspect both services:

docker compose -f deploy/compose/docker-compose.yml logs --tail=200 opsknight-db opsknight-app

3. Create the first administrator

Open http://localhost:3000/setup. Verify the Application URL before selecting Create administrator. For a production hostname, follow the complete initial setup guide; a wrong value can make normal access return HTTP 421.

Generate a one-time bootstrap code inside the configured application container:

docker compose -f deploy/compose/docker-compose.yml exec -T opsknight-app \
  node scripts/create-bootstrap-code.mjs

Do not run the Node command directly on the Docker host: the host quickstart does not install application dependencies or configure its database connection. Enter the printed code with your display name, administrator email, Application URL, and a strong unique password. A configured SETUP_SECRET or BOOTSTRAP_SECRET remains a compatibility alternative. Select Create administrator.

OpsKnight creates exactly one first user as an active Admin. Once any user exists, /setup redirects to /login. For a trusted-host alternative, use the command-line reference; do not put passwords in shell history.

4. Confirm the installation

Sign in and:

1. Open Settings → Health Center and confirm runtime and database health.
2. Create your first service.
3. Configure on-call.
4. Complete the first incident journey.

The quickstart is complete when an alert creates an incident and the intended responder can acknowledge it.

Stop or remove the evaluation

docker compose -f deploy/compose/docker-compose.yml down preserves PostgreSQL data. Adding --volumes permanently deletes the evaluation database.

Troubleshooting

Setup is unavailable: check application logs for database or migration errors and confirm the database is healthy.

Sign-in returns to the wrong host: make both URL settings the externally reachable origin and restart the application.

A 2.0 feature is absent: run docker compose config and confirm opsknight-app.image resolves to your explicit 2.0 tag or digest.