Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ekso.dev/llms.txt

Use this file to discover all available pages before exploring further.

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 Quickstart 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: Postgres example: 
    "Database": {
    "Provider": "Postgres",
    "PostgresTransactConnection": "Host=postgres.internal;Port=5432;Database=ekso;Username=ekso;Password=••••",
    "PostgresMartConnection":     "Host=postgres.internal;Port=5432;Database=ekso;Username=ekso;Password=••••",
    "PostgresAutoPrepare": false,
    "SqlServerTransactConnection": "",
    "SqlServerMartConnection": ""
}
    SQL Server example: 
    "Database": {
    "Provider": "SqlServer",
    "SqlServerTransactConnection": "Server=sql.internal,1433;Database=ekso;User Id=ekso;Password=••••;Encrypt=True;TrustServerCertificate=False;",
    "SqlServerMartConnection":     "Server=sql.internal,1433;Database=ekso;User Id=ekso;Password=••••;Encrypt=True;TrustServerCertificate=False;",
    "PostgresTransactConnection": "",
    "PostgresMartConnection": ""
}
    Leave the unused engine’s slots empty — Ekso only reads the pair matching Provider.
  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

Two containers:
ServiceImageRole
appeksoapp/appREST API + UI on port 6050
workereksoapp/workerBackground jobs
Storage for attachments and uploads is in a Docker volume mounted at /var/ekso/storage. If you want attachments on networked storage, edit the volume in docker-compose.yml to point at your mount.

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

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