Docker - BYOD

Install Ekso against your existing Postgres or SQL Server. The BYOD bundle ships app + worker only; you provide the database.

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

1. Download the bundle (ekso-docker-byod.zip) from your welcome email.

2. Unzip somewhere persistent. The zip contains docker-compose.yml, ekso.json, and a README.md.

3. 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;"
   }
   

4. 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.

5. 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.