Skip to main content

Deploy with Docker

OpenDBAPI is one image, ghcr.io/egret-data/opendbapi, that serves the management UI, the management API and the published endpoints on port 8520. It stores everything in one PostgreSQL database.

Prepare PostgreSQL​

OpenDBAPI needs PostgreSQL 14 or later for its own data (users, workspaces, endpoints, activity). This is separate from the databases your endpoints query. Create the database and two roles: an owner that runs the schema migrations, and an app role that the server uses at run time, subject to row-level security.

CREATE ROLE opendbapi_owner LOGIN PASSWORD 'change-me-owner';
CREATE ROLE opendbapi_app LOGIN PASSWORD 'change-me-app' NOBYPASSRLS;
CREATE DATABASE opendbapi OWNER opendbapi_owner;

OpenDBAPI creates and upgrades its schema (opendbapi) on start, as the owner.

Generate a master key​

The master key encrypts stored secrets: datasource passwords, signing keys, identity provider secrets.

openssl rand -base64 32
warning

Keep the master key safe and stable. Secrets stored with one key cannot be read with another, and anyone with the key and a database backup can read them.

Run​

docker run -d --name opendbapi -p 8520:8520 \
-e OPENDBAPI_DB_URL=jdbc:postgresql://db.example.com:5432/opendbapi \
-e OPENDBAPI_DB_PASSWORD=change-me-app \
-e OPENDBAPI_DB_OWNER_PASSWORD=change-me-owner \
-e OPENDBAPI_MASTER_KEY=... \
-e OPENDBAPI_BOOTSTRAP_ADMIN_PASSWORD=... \
ghcr.io/egret-data/opendbapi:0.3.1
VariableMeaning
OPENDBAPI_DB_URLJDBC URL of OpenDBAPI's own database
OPENDBAPI_DB_USER / OPENDBAPI_DB_PASSWORDThe app role (default user opendbapi_app)
OPENDBAPI_DB_OWNER / OPENDBAPI_DB_OWNER_PASSWORDThe owner role (default user opendbapi_owner)
OPENDBAPI_MASTER_KEYBase64 of 32 random bytes
OPENDBAPI_BOOTSTRAP_ADMIN_PASSWORDPassword of the admin user created on first start. When unset, a random one is printed once in the log
OPENDBAPI_SECURE_COOKIEStrue in the image: session cookies need HTTPS. Set false only for plain-HTTP trials

Every other setting can be given as an environment variable too; see Configuration.

Put it behind HTTPS​

Run OpenDBAPI behind a reverse proxy or load balancer that terminates TLS. Tell it which proxies to trust, so it reads the caller's address from X-Forwarded-For, and the public address to show in endpoint URLs:

-e OPENDBAPI_SERVING_TRUSTED_PROXIES=10.0.0.0/8
-e OPENDBAPI_SERVING_URL_BASE=https://opendbapi.example.com

When url-base is empty, OpenDBAPI derives the address from each request.

Health and metrics​

PathUse
/actuator/health/livenessLiveness probe
/actuator/health/readinessReadiness probe (the image's HEALTHCHECK uses it)
/actuator/prometheusPrometheus metrics; see Operations

The image runs as the non-root user 10001 and can run with a read-only root filesystem.