Docker Compose
The repository ships a ready-to-run stack at infra/docker/compose.yaml. It's the quickest way to get a working instance on a single host.
Services
| Service | What it is | Ports |
|---|---|---|
| db | PostgreSQL 16 — the default control and diagram plane | internal |
| app | The server: tRPC API + REST /api/v1 + the Hocuspocus websocket | HTTP 8787, WS 8788 |
| web | The SPA, served behind nginx | http://localhost:8080 |
Quick start
docker compose -f infra/docker/compose.yaml up
Open http://localhost:8080 and you have a fully working single-host EntityFlow, with both planes living in the bundled PostgreSQL.
Repointing the diagram plane
To store diagrams in your own database, set EF_DIAGRAM_DB_URL. When the diagram plane is not PostgreSQL, you must also set EF_CONTROL_DB_URL to a PostgreSQL instance for the control plane:
# Diagram plane on your own Postgres (control plane shares it)
export EF_DIAGRAM_DB_URL="postgres://user:pass@db.internal:5432/entityflow"
# Diagram plane on MySQL — control plane must still be Postgres
export EF_DIAGRAM_DB_URL="mysql://user:pass@mysql.internal:3306/entityflow"
export EF_CONTROL_DB_URL="postgres://user:pass@pg.internal:5432/ef_control"
docker compose -f infra/docker/compose.yaml up
See Bring your own database for the full list of supported engines and connection-string schemes.
Production essentials
For anything beyond local evaluation, set a strong auth secret:
export EF_AUTH_SECRET="$(openssl rand -base64 48)"
docker compose -f infra/docker/compose.yaml up -d
EF_AUTH_SECRET (32+ characters) must be set for any non-local deployment. Without it, sessions are insecure.
Sign-in is passwordless, so people can only sign in once the instance can send email — point it at your SMTP server (or Resend or Mailjet):
export EF_MAIL_FROM="entityflow@acme.com"
export EF_SMTP_HOST="smtp.acme.com"
export EF_SMTP_USER="entityflow"
export EF_SMTP_PASSWORD="<smtp-password>"
See Configuration → Email for every email variable. On a local evaluation instance, EF_MAIL_PROVIDER=log writes sign-in codes to the server log instead — never use it in production.
For the complete list of tunables — networking, auth, email, realtime, observability, and more — see the Configuration reference.