Skip to main content

Quickstart

This guide assumes you are on the CONTEXUS monorepo root with Docker installed. It mirrors the production compose layout used for demos and partner sandboxes. For product context see Open IoT Hub.

Prerequisites

  • Docker Engine 24+ and Docker Compose v2
  • Ports 9001 (web) and 5433 (PostgreSQL) available on the host
  • A .env file with DATABASE_URL, SESSION_SECRET, and optional protocol credentials

Start the stack

From the repository root, build and detach containers:

docker-compose up -d --build
docker-compose ps

Expected mapping:

  • http://localhost:9001 — CONTEXUS website + Open IoT Hub UI
  • localhost:5433 — PostgreSQL (host → container 5432)

Verify health

curl -sS http://localhost:9001/api/health | jq .
docker-compose logs -f --tail=100

A healthy response includes database connectivity. If Postgres is still initialising, wait for the health check to pass before running migrations.

Database connection string

When connecting from the host (psql, Drizzle Studio, backup tools):

export DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:5433/${POSTGRES_DB}"
psql "$DATABASE_URL" -c 'SELECT 1'

Inside the application container, use the internal service hostname from compose (typically postgres:5432), not 5433.

Apply schema

For local development against the compose database:

npm install
npm run db:push   # development only; use drizzle migrations in production

Connect a first device

  1. Open http://localhost:9001 (or the hosted live demo for a read-only walkthrough).
  2. Create a site and data source — choose a protocol guide (MQTT is fastest for synthetic telemetry).
  3. Publish a test payload and confirm the point appears in the device tree.
  4. Clone a dashboard template from the gallery and bind widgets to your points.

Stop and reset

docker-compose down
# Remove volumes only when you intend to wipe data:
docker-compose down -v

Local dev server (optional)

Engineers editing this Next.js site often run npm run dev on port 5002 while keeping Postgres on 5433 via compose. Production-like previews still use 9001.

Next steps

Explore a running stack, review the open source repositories, estimate ROI for a deployment, or talk with the CONTEXUS team about integration and licensing.

Module licensing details are summarised on /licensing. Browse reference dashboards in the gallery.