Configuration

DBO Studio is configured with environment variables. The same names work for local web, Docker, and the desktop app. You do not need a separate config file.

Start from a small block and change only what you need:

bash
APP_ENV=local
APP_CLIENT=web
APP_PORT=8080

Note: Optional .env files in the API, UI, and e2e packages repeat a subset of this page. When a value disagrees, this guide is the source of truth.

Deployment modes

DBO decides where to store data and whether to show login from APP_ENV and APP_CLIENT.

Local web

Use this on your machine when the API and UI run as two processes:

bash
APP_ENV=local
APP_CLIENT=web
APP_PORT=8080

If no users exist, DBO mints an anonymous session so you can open the UI without logging in.

Warning: Do not expose this mode on a network. Anyone who can reach the port owns the instance.

Desktop

The desktop app sets APP_CLIENT=desktop for you. There is no login screen; the owner is always the person at the keyboard.

bash
APP_ENV=local
APP_CLIENT=desktop

Docker

The published image defaults to Docker mode and listens on port 9000:

bash
APP_ENV=docker
APP_PORT=9000

App metadata and secrets live under the container data directory. Mount a volume there — see Docker.

Public server

Treat a reverse-proxied host as untrusted. Require login, set the public origin, and restrict CORS:

bash
APP_ENV=docker
APP_CLIENT=web
APP_PORT=9000
APP_PUBLIC_URL=https://dbo.example.com
[email protected]
APP_ADMIN_PASSWORD=ChangeMe1
APP_ALLOWED_ORIGINS=https://dbo.example.com

Auth mode becomes local as soon as those admin variables create the first user. Pair this with TLS at the proxy. Details are in Security.

Authentication

After the app database boots, DBO is in one of two auth modes: none or local. The desktop app never shows login.

Mode none

No admin environment is set, and no users exist. DBO issues an anonymous owner session to whichever client connects. That is convenient on localhost and unsafe anywhere else.

Mode local

Mode becomes local when users already exist, or when both APP_ADMIN_EMAIL and APP_ADMIN_PASSWORD are set on a fresh database.

Clients sign in with email and password. The API sets an HttpOnly dbo_session cookie. Data APIs require that session.

Bootstrap an admin

  1. Set APP_ADMIN_EMAIL and APP_ADMIN_PASSWORD, then restart.
  2. Sign in and change the password when prompted. The bootstrap password must be 8–40 characters and include a letter and a number.
  3. Invite other people from Settings → Administration → Users.

The bootstrap environment is ignored after users exist. A factory reset of app tables re-runs bootstrap: if the admin variables are still set, mode is local again; otherwise it returns to none.

Backend variables

These APP_* values configure the API process.

APP_PORT

HTTP listen port. Defaults to 8080 locally and 9000 in the Docker image.

APP_ENV

Controls default data paths:

ValueApp databaseTypical use
localOS app-data directoryDesktop and go run
dockerdata/dbo.db in the container workdirOfficial image
testingdata/testing_dbo.dbAutomated runs

On macOS the local tree is ~/Library/Application Support/dbo/. Windows uses %APPDATA%/dbo/. Linux follows XDG.

Override any path with APP_DATABASE_PATH, APP_LOG_PATH, or APP_SECRET_KEY_PATH instead of relying on the defaults.

APP_CLIENT

web (default) or desktop. Desktop skips the login UI and keeps a single local owner.

APP_PUBLIC_URL

Public origin with no trailing slash. MCP and generated API URLs use this value. Defaults to http://127.0.0.1:<port>.

Behind a proxy, set it to the HTTPS origin users type in the browser:

bash
APP_PUBLIC_URL=https://dbo.example.com

APP_MCP_PUBLIC_URL

Optional override for the MCP endpoint. When unset, DBO uses <APP_PUBLIC_URL>/api/mcp.

APP_ADMIN_EMAIL / APP_ADMIN_PASSWORD

Create the first admin on an empty database. See Bootstrap an admin.

APP_ALLOWED_ORIGINS

Comma-separated CORS allowlist. Required when auth mode is local. Localhost is not trusted automatically in that mode.

bash
APP_ALLOWED_ORIGINS=https://dbo.example.com

In mode none and on desktop, localhost origins are allowed for credentialed requests.

Frontend variables

The Vite dev server reads:

VariableDefaultPurpose
VITE_PUBLIC_SERVER_URL/apiAPI base URL
VITE_PORT3000Dev server port

npm run dev sets VITE_PUBLIC_SERVER_URL=http://localhost:8080/api when you leave it unset. Open http://localhost:3000.

Desktop builds inject their own TAURI_ENV_* values. Do not set those by hand.

Docker Compose

Production

The default Compose file runs one dbo service from ghcr.io/dbo-studio/dbo/dbo:latest.

SettingDefault
Host port9000:9000
Volume./docker/dbo:/backend/data
APP_PORT9000
APP_ENVdocker

Pass public settings at deploy time:

bash
APP_PUBLIC_URL=https://dbo.example.com \
[email protected] \
APP_ADMIN_PASSWORD='ChangeMe1' \
APP_ALLOWED_ORIGINS=https://dbo.example.com \
docker compose up -d

TLS, upgrades, and volume layout are covered in Docker.

Development

The development Compose file is for hot-reload API + UI plus optional sample databases. It is not a production topology.

bash
docker compose -f docker-compose.dev.yml up -d
ServiceDefault URL
Frontendhttp://localhost:3000
APIhttp://localhost:8080/api
Sample Postgreslocalhost:5432
Sample MySQLlocalhost:3307
Sample Postgres (TLS)localhost:5433

Host-only port overrides, useful when 5432 is already taken:

bash
DB_TEST_PORT=15432 MYSQL_TEST_PORT=13307 \
docker compose -f docker-compose.dev.yml up -d sample-pgsql sample-mysql
VariableDefaultContainer
DB_TEST_PORT5432sample Postgres
MYSQL_TEST_PORT3307sample MySQL
PGSQL_SSL_TEST_PORT5433sample Postgres with TLS

Sample Postgres and MySQL both use database default, user default, password secret.

End-to-end tests

The Playwright harness boots its own API and UI on random ports. The variables below only point at optional sample databases on the host — they are not the main app config.

Defaults assume Compose-published ports on 127.0.0.1: Postgres 5432, MySQL 3307, TLS Postgres 5433. How to run the suite is in Testing.

Previous

Testing

Next

Docker