Docker - BYOD - Ekso Documentation

The BYOD bundle is for shops that already operate Postgres or SQL Server and want Ekso to share it. The zip ships only the app and worker containers — no embedded database — and an ekso.json with placeholder connection strings for you to fill in. Pick this if you have a managed Postgres on AWS RDS / Azure Database / Supabase / Neon, a SQL Server estate with spare capacity, or strict policy that data lives in your existing instance. For a clean-slate install with no external dependencies, see Docker - full stack instead.

Prerequisites

Docker Engine 20+ on Linux, Docker Desktop on macOS or Windows
An empty database on Postgres 16+ or SQL Server 2025, plus credentials with CREATE rights so Ekso can apply its schema on first boot
pgvector installed on Postgres (one-time per database):
CREATE EXTENSION IF NOT EXISTS vector;
A free license — fetch one at ekso.app/get-started

SQL Server 2025 is the minimum because Ekso uses native vector search. Earlier versions don’t have the required types and DiskANN index support.

Install

Download the bundle (ekso-docker-byod.zip) from your welcome email.
Unzip somewhere persistent. The zip contains docker-compose.yml, ekso.json, and a README.md.

Edit ekso.json — fill in the connection strings for your database. The full schema is documented in the configuration reference; the relevant fields are under Database. The same two fields (TransactConnection + MartConnection) take connection strings in the dialect implied by Provider: Postgres example:

"Database": {
    "Provider": "Postgres",
    "TransactConnection": "Host=postgres.internal;Port=5432;Database=ekso;Username=ekso;Password=••••",
    "MartConnection":     "Host=postgres.internal;Port=5432;Database=ekso;Username=ekso;Password=••••"
}

SQL Server example:

"Database": {
    "Provider": "SqlServer",
    "TransactConnection": "Server=sql.internal,1433;Database=ekso;User Id=ekso;Password=••••;Encrypt=True;TrustServerCertificate=False;",
    "MartConnection":     "Server=sql.internal,1433;Database=ekso;User Id=ekso;Password=••••;Encrypt=True;TrustServerCertificate=False;"
}

Bring it up:
docker compose up -d
The API auto-applies the schema on first boot. Allow 30–60 seconds for that plus image pulls.
Open the install URL to land in the first-run wizard:
http://localhost:6050/startup

Transact vs Mart connections

Ekso splits database access into two connection strings:

Connection	Purpose	When to point them differently
`Transact`	OLTP — every live request hits this	Default — the live-work database
`Mart`	Reporting, analytics, the Insights module	Point at a read replica when reporting load is heavy enough to bother the OLTP path

For most installs, both connection strings point at the same database. Separating them onto a read replica is an optimization for reporting-heavy workloads — not a starting requirement.

Connection-string gotchas

Symptom	Likely cause
`connection refused` from `app` container	Database hostname resolves correctly inside Docker? Use the host’s network address, not `localhost`.
`permission denied` on first boot	The Ekso user doesn’t have `CREATE` rights — schema apply fails. Grant `CREATE ON DATABASE`.
`extension "vector" does not exist`	pgvector wasn’t installed before first boot. Run `CREATE EXTENSION IF NOT EXISTS vector;` and restart `app`.
TLS handshake errors against managed Postgres	Cloud providers usually require `Ssl Mode=Require;Trust Server Certificate=true` in the connection string.

What’s running

Three containers:

Service	Image	Role
`app`	`eksoapp/app`	REST API + UI on port 6050
`worker`	`eksoapp/worker`	Background jobs
`backup`	`alpine:3.20`	Daily snapshots of uploaded attachments

Your data lives in normal folders next to docker-compose.yml:

Folder	What’s in it	Whose responsibility
`./data/storage/`	Uploaded attachments	The bundle
`./backups/storage/`	Daily snapshots, retained for 14 days	The bundle
Your external database	All other Ekso data	You — back up with your existing DB tooling

For the full data model — automatic backups, restore commands, and the docker compose down -v reassurance — see Data management.

Updating

docker compose pull
docker compose up -d

Schema migrations apply automatically on startup against your existing database — same migration system as Quickstart, just pointed at the database you provided. Your ./data/ and ./backups/ folders are untouched, and the bundle never touches your external DB. See Upgrading for release cadence, version pinning, and the rollback procedure.

Switching providers

Don’t switch Database.Provider on a populated install. Ekso emits the schema for whichever provider you pick on first boot — the on-disk schemas aren’t interchangeable. To migrate, back up tenant data, point at a fresh database in the new engine, restore.

Getting started

Install

Manage

Core concepts

Work management

Process & workflow

Planning & delivery

Time & finance

Help desk

Knowledge & AI

Integrations

Administration

API

Docker - BYOD

Prerequisites

Install

Transact vs Mart connections

Connection-string gotchas

What’s running

Updating

Switching providers

​Prerequisites

​Install

​Transact vs Mart connections

​Connection-string gotchas

​What’s running

​Updating

​Switching providers

Prerequisites

Install

Transact vs Mart connections

Connection-string gotchas

What’s running

Updating

Switching providers