Getting started

What you will run

Probara is a multi-service monitoring platform. The preferred development commands start PostgreSQL and NATS, migrate the database, run the backend services, and launch the Next.js application.

API

Owns authentication, tenant-scoped CRUD, monitor administration, imports, dashboard data, passive check ingestion, and administrative APIs.

Scheduler and workers

The scheduler claims due monitors and publishes jobs; workers perform active checks and return results through NATS.

Alerter

Evaluates stored state, opens and resolves alerts, dispatches delayed notifications, and manages incidents.

Status-page service

Renders public status pages and serves their data and server-sent event streams.

Web application

The separate Next.js interface used to configure and operate the platform.

Prerequisites

• Docker with Docker Compose v2 for PostgreSQL, NATS, and the Docker-backed workflow.
• Go 1.26-compatible tooling. Both Go modules currently declare Go 1.26 and a Go 1.26.5 toolchain.
• A current Node.js LTS release and npm for the web application.
• GNU Make and a Bash-compatible shell for the repository scripts. On Windows, run the Make targets from an environment that provides these tools.

git clone <your-repository-url>
cd probara
cp .env.example .env

Never commit .env or generated credentials. Set both ADMIN_JWT_SECRET (a random value of 32 or more characters is recommended) and PUBLIC_BASE_URL in .env before either startup workflow. Docker Compose ships an insecure hardcoded default secret and the local script falls back to an insecure placeholder when the value is unset, so override it explicitly for anything beyond throwaway local development. The configuration reference documents every environment variable.

Start the local-process workflow

This is the fastest path for backend development because only PostgreSQL and NATS run in containers.

make start-all-local

1. Starts PostgreSQL and NATS with Docker Compose.
2. Bootstraps local database access and validates the Go toolchain.
3. Runs the database migrations with go run ./cmd/migrate.
4. Builds the installable collector artifacts and starts the Go services as local processes.
5. Launches the Next.js web application.

If the local startup script runs with ADMIN_JWT_SECRET unset, it falls back to a hardcoded development placeholder value. That fallback is an implementation convenience, not a substitute for populating .env with a real secret.

make stop-all-local
make restart-all-local

Start the Docker-backed workflow

Use this workflow when you want the backend service images and Compose topology to match a packaged deployment more closely.

ADMIN_JWT_SECRET=replace-with-a-random-secret-at-least-32-characters
PUBLIC_BASE_URL=http://localhost:8080

make start-all
make stop-all
make restart-all

Do not mix the stop targets. make stop-all-local cleans up local Go processes, while make stop-all stops the Docker-backed application services.

Default local endpoints

Backend services also expose /healthz and /readyz. A healthy process is not necessarily ready: readiness includes dependencies the service needs to perform work.

Create the first administrator

A new installation exposes a one-time bootstrap flow. The first active account becomes the platform superadministrator.

1. Open the web application at http://localhost:3000.
2. Follow the bootstrap prompt and create the initial account.
3. Use a username of 3–64 characters containing letters, numbers, ., _, or -.
4. Use a password between 12 and 128 characters.
5. Sign in and select the initial tenant context.

An empty installation configured for OIDC can also bootstrap through the first successful just-in-time OIDC login. Subsequent user and tenant access is governed by platform roles and tenant memberships.

Create and run the first monitor

1. Open Monitors and choose a new HTTP monitor.
2. Enter a public http:// or https:// URL, a check interval, and a timeout shorter than that interval.
3. Use Test to perform a compute-only check before saving. A test result is returned immediately and is not added to monitor history.
4. Save the monitor, then choose Run now to enqueue a real check. This result is persisted and participates in state and alert evaluation.
5. Review the current state, result history, timings, and analytics after the worker reports.

Test

Executes an ephemeral check and returns its result without saving history or triggering alerts.

Run now

Publishes a normal job. The result is stored, changes monitor state, and can open or resolve alerts.

Scheduled run

The scheduler claims a due monitor, fans it out to its selected locations when applicable, and advances next_run_at.

Verify the installation and troubleshoot startup

make test
make lint

cd web
npm run lint
npm run build

• If the UI loads but API calls fail, verify that PUBLIC_BASE_URL names the API origin, not the UI or status-page origin.
• If agents or remote workers cannot connect, confirm that the advertised URL is reachable from their network and that proxy/TLS settings preserve the intended scheme.
• If an active check is rejected before connecting, review the destination-safety policy and location-specific CIDR allowlists.
• If PostgreSQL authentication fails after older local experiments, the repository-scoped Docker volume may contain incompatible credentials.