Environments and URLs
Staging
| Service | URL |
|---|---|
| Web application | https://web.linter-iot-stg.icent.digital |
| REST API | https://api.linter-iot-stg.icent.digital |
| Ingestion (health) | https://ingest.linter-iot-stg.icent.digital |
| MQTT broker | mqtts://mqtt.linter-iot-stg.icent.digital:8883 |
| This documentation | https://docs.linter-iot-stg.icent.digital |
Local development
The services run on the developer’s machine (pnpm dev:api, pnpm dev:web,
the ingest with uvicorn) against the infrastructure started with
pnpm infra:up (MongoDB, Mosquitto, Mongo Express and Azurite).
| Service | URL |
|---|---|
| Web | http://localhost:5173 |
| API | http://localhost:3010 |
| Ingestion | http://localhost:8000 |
| MQTT | mqtts://localhost:8883 |
| This documentation | http://localhost:4321 (pnpm dev:docs) |
Self-hosted with Docker
The whole platform can also run in containers on a single Linux machine
(./scripts/stack.sh init, up, seed); see
Self-hosted with Docker. STACK_HOST is the
address users and devices open, and every port can be changed in
infra/.env:
| Service | Default URL |
|---|---|
| Web | http://<STACK_HOST>:8080 |
| API | http://<STACK_HOST>:3010 |
| MQTT | mqtts://<STACK_HOST>:8883 |
| Ingestion | http://127.0.0.1:8000 |
| Mongo Express | http://127.0.0.1:8081 |
With the infra/.env made by init, the ingestion service, MongoDB and
Mongo Express listen only on the machine itself (ADMIN_BIND, see
Ports and firewall). The web
container writes the API URL into /config.js when it starts, so the same
image serves any address. The documentation is not part of the stack: the
web links to the public site unless PUBLIC_DOCS_URL is set.
Health checks
| Service | Endpoint | Response |
|---|---|---|
| API | GET /v1/health | { status, mongo, uptime } |
| Ingestion | GET /health | { status, mongo, mqtt_worker, mqtt_connected, commands_dispatcher } |
On the ingest, mqtt_worker says that the MQTT loop is running,
mqtt_connected that it has a session with the broker right now (the loop
retries for ever), and commands_dispatcher that
device commands are being dispatched (also true when
they are disabled on purpose).
Versioning
Every endpoint lives under the /v1 prefix. Breaking changes will be
published under a new prefix; /v1 stays stable for the duration of the
pilot.
OpenAPI specification
The specification is generated from the service code itself and is available at:
GET https://api.linter-iot-stg.icent.digital/docs/jsonThe interactive reference in this documentation is fed from that URL, so it always reflects what is deployed.