Install with Docker Compose

The Compose stack runs the public images on one host: the API, the SPA, and a bundled Postgres. It's the fastest way to a working evaluation.

Evaluating? The quick-start bundles add a bundled identity provider, an MQTT broker, and a device simulator to this stack, so you get live sample data immediately — no broker of your own required. Use the Keycloak bundle for a one-command, self-contained demo. The steps below are the lean production-leaning stack you point at your own broker and identity provider.

1. Get the compose files

The customer compose lives at deploy/compose/ in the edgentia-core repository (docker-compose.yml + .env.example). Copy that directory to your host.

2. Configure `.env`

bash

cp .env.example .env

Fill in the required values:

dotenv

# Image version to run — pin a released tag for reproducible installs.
EDGENTIA_VERSION=0.1.2
 
# Public URL where you expose the SPA (used for email deep-links + CORS).
APP_BASE_URL=https://edgentia.acme.com
# Host port the SPA listens on (put your TLS reverse proxy in front).
FRONTEND_PORT=3000
 
# Secret protection at rest (REQUIRED): openssl rand -base64 32
SECURITY_ENCRYPTION_KEY=
 
# Bundled Postgres
POSTGRES_USER=edgentia
POSTGRES_PASSWORD=
POSTGRES_DB=edgentia
 
# User-management level seed (1 = directory + verified members; 2 = + invites, Keycloak only)
AUTH_MANAGEMENT_LEVEL=1

Then fill one authentication block:

dotenv

# Option A — Microsoft Entra ID
AUTH_MODE=Entra
ENTRA_TENANT_ID=<tenant guid>
ENTRA_CLIENT_ID=<client guid>
# ENTRA_CLIENT_SECRET=   # optional — only for the directory "add member" picker
 
# Option B — Keycloak (leave AUTH_MODE empty)
KEYCLOAK_AUTHORITY=https://kc.acme.com/realms/edgentia
KEYCLOAK_ADMIN_CLIENT_SECRET=<edgentia-api client secret>

See Microsoft Entra ID and Keycloak for how to obtain these, and Environment variables for the full list.

3. Run

bash

docker compose up -d
docker compose ps          # api, frontend, postgres should be healthy

The API waits for Postgres to be healthy, then creates its schema on first boot.

4. Expose it

The SPA listens on FRONTEND_PORT (default 3000) and proxies /v1 and /health to the API internally — so it is the single entry point. Put your TLS reverse proxy (Caddy, nginx, Traefik, a cloud LB) in front of that port and point it at APP_BASE_URL.

TLS is your responsibility. edgentia serves plain HTTP inside the host; the public HTTPS URL is terminated by your proxy. Keep APP_BASE_URL in sync with the public URL or email links and CORS will be wrong.

Open your public URL, sign in (Entra or your Keycloak owner), then install the license in Settings → License.

To seed a license at startup instead (air-gapped), set EDGENTIA_LICENSE in .env.

Upgrading

Bump EDGENTIA_VERSION to a newer released tag and docker compose up -d. Pin a version rather than using latest so upgrades are deliberate. The Postgres volume persists across upgrades.

A note on secrets

.env holds plaintext secrets — keep it off version control and restrict its file permissions. For stronger handling, inject these as host environment variables from your secret manager instead of a file.