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
.envfile withDATABASE_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 psExpected mapping:
http://localhost:9001— CONTEXUS website + Open IoT Hub UIlocalhost:5433— PostgreSQL (host → container5432)
Verify health
curl -sS http://localhost:9001/api/health | jq .
docker-compose logs -f --tail=100A 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 productionConnect a first device
- Open
http://localhost:9001(or the hosted live demo for a read-only walkthrough). - Create a site and data source — choose a protocol guide (MQTT is fastest for synthetic telemetry).
- Publish a test payload and confirm the point appears in the device tree.
- 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 -vLocal 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.