E2E tests (requires build)

bun run test:e2e # Playwright browser tests (32 cases)

Getting Started

Install

| Channel | Command | Notes | | :--- | :--- | :--- | | Docker | docker run -d -p 3000:3000 ghcr.io/libredb/libredb-studio:latest | Zero-config: the admin password is printed to the log on first run | | Helm (Kubernetes) | helm install libredb oci://ghcr.io/libredb/charts/libredb-studio | Zero-config: first-run admin credentials are printed to the pod log | | npx | npx @libredb/studio | Linux/macOS, Node 20.9+ (Node 24 LTS recommended); downloads the release server tarball | | Homebrew | brew trust libredb/tap && brew install libredb/tap/libredb-studio | brew trust is required once (Homebrew 6+; run brew update if unknown) | | deb / rpm | sudo dpkg -i libredb-studio_<version>_amd64.deb | Attached to each GitHub release; systemd service included | | Snap | sudo snap install libredb-studio | Zero-config: the admin password is printed to sudo snap logs libredb-studio on first run — Snap Store listing |

Homebrew, deb/rpm, Snap, and the npx launcher consume standalone artifacts attached to each GitHub release. Full per-channel guide — commands, configuration, systemd usage, and the Docker image tag model — in docs/DISTRIBUTION.md.

Quick Start (Docker)

Run LibreDB Studio with a single command — no clone, no install, no build:

docker run -d \
  --name libredb-studio \
  -p 3000:3000 \
  -e ADMIN_EMAIL=admin@libredb.org \
  -e ADMIN_PASSWORD=LibreDB.2026 \
  -e USER_EMAIL=user@libredb.org \
  -e USER_PASSWORD=LibreDB.2026 \
  -e JWT_SECRET=change-me-to-a-random-32-char-string \
  ghcr.io/libredb/libredb-studio:latest

Registry: ghcr.io/libredb/libredb-studio is the primary image (no pull rate limits — preferred for Kubernetes/CI). The same image is also mirrored to Docker Hub as libredb/libredb-studio for convenience.

Open http://localhost:3000 and login with admin@libredb.org / LibreDB.2026.

Auth env vars (local provider): ADMIN_PASSWORD and JWT_SECRET are only required when AUTH_BOOTSTRAP=off; otherwise both are generated on first start (see Zero-config first run below). USER_EMAIL / USER_PASSWORD are optional; omit them to run admin-only (no default user password is ever assumed). ADMIN_EMAIL defaults to admin@libredb.org. Using OIDC (NEXT_PUBLIC_AUTH_PROVIDER=oidc)? None of these are needed.

Tip: Add -e LLM_PROVIDER=gemini -e LLM_API_KEY=your_key -e LLM_MODEL=gemini-2.5-flash to enable AI features.

Zero-config first run

Starting the server without JWT_SECRET / ADMIN_PASSWORD works out of the box: the missing values are generated on first start, stored in <data dir>/auth-bootstrap.json (file mode 0600), and the admin password is printed once to the server log. Explicitly set environment variables always take precedence. Set AUTH_BOOTSTRAP=off to require explicit configuration instead (recommended for production deployments).

Linux packages (.deb / .rpm)

Native packages for Debian/Ubuntu and RHEL/Fedora (amd64 and arm64) are attached to every GitHub release. They bundle the standalone server together with a private Node.js runtime (nothing else to install) and register a systemd service:

```bash

One-Click Deploy

Deploy your own instance of LibreDB Studio with a single click on Koyeb, Render, Railway, or CapRover:

CapRover: open your CapRover dashboard → Apps → One-Click Apps/Databases, search for LibreDB Studio, and deploy. Koyeb: set a strong JWT_SECRET and credentials before deploying (Koyeb cannot auto-generate secrets). The button uses STORAGE_PROVIDER=local — connection metadata lives in the browser, which suits Koyeb's ephemeral filesystem. For persistence across redeploys, switch to STORAGE_PROVIDER=postgres and point STORAGE_POSTGRES_URL at a Koyeb managed Postgres or Neon database. See deploy/koyeb/. Cosmos: install in one click from the Cosmos Marketplace — search for LibreDB Studio. Cosmos auto-generates secrets, provisions a persistent SQLite volume, and serves the app behind its SmartShield reverse proxy. See deploy/cosmos/.

Deployment (DevOps)

Maintainers: every distribution channel is inventoried in distribution/channels.yaml; bun run distribution:check reports version drift across all of them (see docs/DISTRIBUTION.md).

Render (Recommended for cloud deployment)

LibreDB Studio includes a render.yaml Blueprint for one-click deployment:

1. Fork this repository
2. Connect to Render: dashboard.render.com → New → Blueprint
3. Select your forked repo and Render will auto-detect render.yaml
4. Set Environment Variables in Render Dashboard:
5. Deploy!

Docker Compose (Self-Hosted)

Use the ready-to-use docker-compose.example.yml — it pulls the published image (ghcr.io/libredb/libredb-studio:latest), so no source build is needed. It documents every supported environment variable (auth, OIDC, storage, LLM, seed connections), with the less-common ones commented out.

```bash

Start PostgreSQL with sample e-commerce data

docker compose -f docker/postgres.yml up -d

PostgreSQL Sample Data

The docker/postgres.yml setup includes a pre-loaded e-commerce schema:

Sample tables: app.customers, app.products, app.orders, app.order_items, app.product_reviews, app.categories, app.coupons, app.audit_log

This setup is ideal for testing the Monitoring Dashboard features with real pg_stat_statements data.

---

Environment Variables

Tip: Copy .env.example to .env.local for local development.

---

2. Create your .env (set at least JWT_SECRET / ADMIN_PASSWORD / USER_PASSWORD)

cp .env.example .env

Seed Connections (Pre-Configured Databases)

Pre-configure database connections via a YAML config file so users see them immediately after login. Ideal for Platform/SaaS deployments where admins provision databases for teams.

Features: - Role-based access control (admin, user, * wildcard) - Hybrid model: managed: true (read-only, admin-controlled) or managed: false (editable copy for user) - Credentials injected via ${ENV_VAR} syntax — never stored in config file - Hot-reload: config changes apply within 60s without restart - Works with Docker, docker-compose, and Kubernetes (Helm)

1. Create a config file (seed-connections.yaml):

version: "1"

defaults:
  managed: true
  environment: production

connections:
  - id: "prod-analytics"
    name: "Production Analytics"
    type: postgres
    host: analytics-db.internal
    port: 5432
    database: analytics
    user: "readonly_user"
    password: "${ANALYTICS_DB_PASSWORD}"
    roles: ["admin"]
    color: "#10B981"

  - id: "dev-sandbox"
    name: "Dev Sandbox"
    type: mysql
    host: dev-mysql.internal
    port: 3306
    database: sandbox
    user: "dev_user"
    password: "${DEV_DB_PASSWORD}"
    roles: ["*"]
    managed: false

2. Mount and configure:

<details> <summary><strong>Docker</strong></summary>

docker run -v ./seed-connections.yaml:/app/config/seed-connections.yaml:ro \
  -e SEED_CONFIG_PATH=/app/config/seed-connections.yaml \
  -e ANALYTICS_DB_PASSWORD=secret \
  -e DEV_DB_PASSWORD=devsecret \
  ghcr.io/libredb/libredb-studio:latest

<details> <summary><strong>Docker Compose</strong></summary>

services:
  app:
    image: ghcr.io/libredb/libredb-studio:latest
    volumes:
      - ./seed-connections.yaml:/app/config/seed-connections.yaml:ro
    environment:
      SEED_CONFIG_PATH: /app/config/seed-connections.yaml
      ANALYTICS_DB_PASSWORD: ${ANALYTICS_DB_PASSWORD}
      DEV_DB_PASSWORD: ${DEV_DB_PASSWORD}

<details> <summary><strong>Kubernetes (Helm)</strong></summary>

```yaml

Run all tests (unit + API + integration + hooks + components)

bun run test