Documentation

• Engineers running industrial, agricultural, energy or building deployments where data flows from many sensors into a single database.
• Teams that want to own their data plane — no SaaS account, no egress to a third party, no telemetry.
• Anyone tired of writing custom Python scripts to validate payloads and forward them to InfluxDB.

• A REST API (Actix-web) for managing every pipeline resource.
• An actor-based runtime (Actix on Tokio) that runs the pipelines, with N replicas per pipeline.
• A Next.js web UI for the entire CRUD + lifecycle.
• JWT auth with first-run admin onboarding.
• OpenAPI / Swagger UI at /swagger-ui/.

• Rust toolchain (stable, edition 2024). Install via rustup.rs.
• Node 20+ and pnpm for the web UI: npm i -g pnpm.
• A message broker the pipeline can consume from (any of RabbitMQ, MQTT, Kafka).
• Optional: an InfluxDB instance, or use LOCAL_LOG while you experiment.

Migrations are bundled into the binary; on first start it applies any pending migration to the SQLite database automatically. If you want to apply them manually:

$ cargo install sqlx-cli --features sqlite
$ sqlx migrate run --database-url sqlite://data/iot-bee.db

$ JWT_SECRET=change-me-to-a-long-random-string make run
# equivalent to: cargo fmt && cargo check && RUST_LOG=info cargo run

The HTTP server starts at http://127.0.0.1:8080. Swagger UI lives at /swagger-ui/.

$ cd web
$ cp .env.local.example .env.local
$ pnpm install
$ pnpm dev   # http://localhost:3000

Open http://localhost:3000. The first visit to /login on a fresh database will offer to create the admin account.

Visit /login. If the database has no users, the form shows create admin account. Fill email + name + password (≥ 8 chars), submit. You land on /app with an HttpOnly session cookie.

The top bar has six tabs:

• overview — global stats and live status of all pipelines.
• pipelines — list, create, start/stop.
• sources, stores, schemas, groups — full CRUD for each resource.

On mobile the tabs collapse into a full-screen navigation overlay. Your user badge sits in the top-right with a dropdown showing email, role and sign-out.

⌘K (or Ctrl+K) opens a command palette to navigate or create resources without touching the menu. On mobile, the command bar collapses to a floating ⌘ button at the bottom-right.

The schema editor is a raw-JSON editor with a live preview panel. The load example button bootstraps a working three-field schema you can adapt. Click save; the preview updates as you type.

All endpoints (except /auth/* and /swagger-ui/*) require an HS256 JWT in the Authorization header.

$ curl -X POST http://127.0.0.1:8080/auth/login \
    -H "Content-Type: application/json" \
    -d '{"email":"admin@iot-bee.dev","password":"iotbee2026"}'

# response:
{
  "user": { "id": 1, "email": "...", "name": "...", "role": "admin" },
  "token": "eyJ0eXAi..."
}

$ curl http://127.0.0.1:8080/data-sources \
    -H "Authorization: Bearer eyJ0eXAi..."

Failures return JSON of the shape { "error": "<message>" } with the appropriate HTTP status (400, 401, 403, 404, 409, 500).

If a single replica crashes, only that replica is restarted — the rest of the pipeline keeps streaming. Pipelines are isolated from each other; a runaway pipeline cannot take down the others or the HTTP server.

Browser
  └─ Next.js (Vercel)            ← serves landing, login, app, /api/proxy
        └─ HTTP                    ← server-to-server, with Bearer
              └─ iot-bee backend  ← Rust binary on YOUR server

The browser never calls the backend directly. All API calls go through a thin Next route handler at /api/proxy/[...path] that translates the HttpOnly session cookie into an Authorization: Bearer header. Three consequences:

• The JWT never reaches client-side JavaScript (immune to XSS token theft).
• No CORS headers are required for the normal flow — the only cross-origin call is server-to-server.
• You can put the backend on a private network and expose only the Vercel frontend publicly, as long as Vercel functions can reach the backend.

Build a release binary on the target machine (or in a CI pipeline) and run it under a process supervisor of your choice (systemd, supervisord, fly.io machines, etc.).

# on the server
$ cargo build --release
$ ./target/release/iot-bee   # listens on $API_HOST:$API_PORT

Required env on the backend:

The web/ directory is a standard Next.js 15 project — no vercel.json required.

1. 01
   Connect the repo

   Import the repository on Vercel and set the root directory to web. Framework auto-detects.
2. 02
   Set environment variables

   In the Vercel project settings → Environment Variables, add the four below. Mark INTERNAL_API_URL and NEXT_PUBLIC_API_URL as required for both Production and Preview environments.
3. 03
   Allow the frontend in the backend's CORS

   On the backend, add the Vercel deployment URL to CORS_ORIGINS (e.g. https://iotbees.com). Restart the backend so the new value takes effect.
4. 04
   Deploy

   Push to the configured branch. Vercel builds and serves; the first request to /login on a fresh backend will offer to create the admin account.

1. Visit https://<vercel-url>/auth/has-users via the Next proxy isn't public — instead curl your backend directly and check it responds with { "has_users": false }.
2. Open /login and create the admin. The redirect to /app proves the cookie + proxy chain works end-to-end.
3. Open the backend status indicator in the top-right of the app — it should show Backend ONLINE.

The backend fails fast if JWT_SECRET is missing. Set it in your shell or in .env:

$ export JWT_SECRET="$(openssl rand -hex 32)"

This means the backend reports zero users. If you registered successfully and you still see the create-admin form, refresh; the page calls GET /auth/has-users on mount. If the form keeps appearing, your database is empty — check that the backend is talking to the same DATABASE_URL you registered against.

Add the front-end origin to CORS_ORIGINS on the backend and restart. In dev the default already includes http://localhost:3000.

Most often this means the broker connection failed or the schema doesn't parse the incoming payload. Tail the backend logs with RUST_LOG=iot_bee=debug to see the exact reason; the actor reports the error to the supervisor before transitioning state.

Open an issue at github.com/manuelmj/iot-bee/issues with the relevant log snippet, your config (redact secrets!), and the steps to reproduce.