Troubleshooting
Common deployment and integration issues for self-hosted CONTEXUS stacks. For guided setup, start with Quickstart.
Diagnostic commands
docker-compose ps
docker-compose logs -f --tail=200 web
curl -sS http://localhost:9001/api/health | jq .
docker-compose exec postgres pg_isready -U "$POSTGRES_USER"FAQ
The website does not load on port 9001 after docker-compose up.
Run docker-compose ps and confirm the web service published 0.0.0.0:9001. Check docker-compose logs web for migration errors. Ensure nothing else binds 9001 (ss -tlnp | grep 9001). Rebuild with docker-compose up -d --build if the image is stale.
API health reports database disconnected.
Verify Postgres is healthy on localhost:5433. From the host: psql $DATABASE_URL -c 'SELECT 1'. Inside containers, DATABASE_URL must use the postgres service hostname on port 5432, not 5433. Wait for Postgres healthcheck before starting web.
BACnet discovery finds no devices.
Place the adapter on the control VLAN or configure BBMD. Docker bridge networks block broadcast — use host networking on Linux or static device IPs. See /docs/protocols/bacnet.
MQTT telemetry appears in logs but not in the UI.
Confirm topic prefix matches the tenant/site/device convention. Check payload JSON keys against the point map. Ensure site_id in the topic matches the dashboard bindings.
npm run dev cannot connect to the database.
Keep Postgres running via docker-compose on 5433 while dev runs on port 5002. Point local .env DATABASE_URL at localhost:5433.
How do I report a bug?
Use /ticket for support requests or open an issue on GitHub with requestId from API errors, docker-compose logs, and protocol capture (redact credentials).
Changelog (stub)
Formal release notes will mirror GitHub tags. Until the docs pipeline syncs automatically, track upgrades manually:
| Version | Date | Highlights |
|---|---|---|
| 2026.11-docs-mvp | 2026-11-15 | Published /docs site map, protocol guides, API stub, multi-tenancy overview. |
| 2026.09-hub | 2026-09-06 | Gallery SEO templates, licensing page, Open IoT Hub positioning refresh. |
| TBD | — | OpenAPI JSON export, automated changelog from GitLab releases. |
Escalation
Confirm module entitlements on licensing before enabling proprietary features. Compare UI expectations with gallery templates and the ROI calculator for stakeholder conversations.
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.