Architecture

How NervesHub is built: the web and device endpoints, PostgreSQL and object storage, the optional ClickHouse database, and the distributed cluster.

Written By Josh Kalderimis

Last updated About 2 months ago

NervesHub is an Elixir/Phoenix application backed by a small set of infrastructure. This page explains the moving parts, which is useful background for self-hosting and for understanding how updates flow at scale.

The pieces

Component

Role

Application server

The Elixir/Phoenix app. Serves the web UI and HTTP API, and terminates device websocket connections.

PostgreSQL

The primary database: orgs, products, devices, firmware records, deployments, audit logs.

Object storage (S3-compatible)

Stores firmware and archive files.

ClickHouse (optional)

Stores device logs and powers analytics/Insights. Omit it and everything else runs the same.

Two endpoints

The application exposes two separate HTTP/websocket endpoints:

  • Web endpoint: for people. The web UI and the HTTP API.

  • Device endpoint: for hardware. The long-lived websocket that devices connect to, typically secured with mutual TLS for certificate-based authentication.

Keeping them separate means device traffic and human traffic can be scaled, secured, and hosted independently. On NervesCloud they're devices.nervescloud.com and manage.nervescloud.com.

How a device connects

  1. A device opens a websocket to the device endpoint and authenticates (shared secret or certificate). See Device authentication & mTLS.

  2. It joins a channel and reports its presence, firmware version, and (if enabled) health and geo data.

  3. NervesHub tracks the connection and, when a deployment group offers a newer release, sends the device a signed firmware download URL.

  4. The device downloads, verifies the signature, applies the update, and reboots.

Non-critical features (health, geo, local shell) run as extensions over the same socket, kept separate so they never interfere with firmware updates.

Running as a cluster

NervesHub is designed to run across multiple nodes, and nodes can take on different roles:

  • Device nodes handle device websocket connections.

  • Web nodes serve the UI and API and run the deployment orchestrators.

The deployment orchestrators are distributed and globally coordinated so that exactly one runs per active deployment group, regardless of how many nodes you have. This is how rollouts stay within their concurrency and failure limits across the whole cluster. See Deployment orchestration.

Background work (firmware processing, delta generation, cleanup) runs as jobs, and internal messaging between processes and nodes uses Phoenix PubSub.

Optional analytics

Device logs and richer Insights are backed by ClickHouse. It's entirely optional: if you don't configure it, log capture and analytics are unavailable and the rest of the platform is unaffected. This keeps a minimal deployment lean while letting larger operators opt into deeper observability.

Related