Skip to main content
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:
ConnectionPurposeWhen to point them differently
TransactOLTP — every live request hits thisDefault — the live-work database
MartReporting, analytics, the Insights modulePoint 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

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

​
What’s running

Three containers:
ServiceImageRole
appeksoapp/appREST API + UI on port 6050
workereksoapp/workerBackground jobs
backupalpine:3.20Daily snapshots of uploaded attachments
Your data lives in normal folders next to docker-compose.yml:
FolderWhat’s in itWhose responsibility
./data/storage/Uploaded attachmentsThe bundle
./backups/storage/Daily snapshots, retained for 14 daysThe bundle
Your external databaseAll other Ekso dataYou — 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.