E2E tests (requires build)

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

Docker (recommended)

docker run -p 3000:3000 ghcr.io/libredb/libredb-studio:latest

or with Node.js 24+ (no Docker)

npx @libredb/studio ```

Then open http://localhost:3000. On first run, the admin password is printed to the log (zero-config).

Need Helm, Homebrew, Snap, winget, or deb/rpm? See all install options.

---

Getting Started

Install

| Channel | Command | Notes | | :--- | :--- | :--- | | Docker | docker run -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/Windows, Node 24+ (24 LTS is the reference runtime); downloads the release server archive | | 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 | | winget (Windows) | winget install LibreDB.Studio | Portable zip with a bundled Node.js runtime; run libredb-studio — listed in the winget community repository | | Chocolatey (Windows) | choco install libredb-studio | Same standalone zip — listed in the Chocolatey community repository; the first push (0.9.59) cleared moderation on 2026-08-24, and every release publishes automatically since (#114) | | Portable zip (Windows) | .\libredb-studio.exe | Download from GitHub Releases; bundled Node runtime, no package manager needed | | Desktop app (Linux, AppImage) | chmod +x libredb-studio-desktop-<version>-linux-x64.AppImage && ./libredb-studio-desktop-<version>-linux-x64.AppImage | Native window, no browser tab and no login prompt; the server runs as a local sidecar. For a sandboxed build, use the Flatpak row below (#232) | | Desktop app (Debian/Ubuntu) | sudo apt install ./libredb-studio-desktop-<version>_amd64.deb | Same desktop app, installed into the menu; needs no FUSE and takes WebKitGTK from the distribution. Not the server package — that one is libredb-studio_<version>_<arch>.deb | | Desktop app (Flatpak) | flatpak --user remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo<br>flatpak --user install flatpark org.libredb.Studio | Sandboxed desktop app from the FlatPark remote — no filesystem access at all; databases are reached over TCP. Developer-approved listing (#241) |

Homebrew, deb/rpm, Snap, the Windows portable zip, winget/Chocolatey, the desktop AppImage and Debian package, 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. Channel coverage scorecard (live / pending, by platform and category) — docs/CHANNELS.md.

Quick Start (Docker)

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

docker run \
  --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.

IPv6: the container picks its own bind address at startup and prefers ::, which serves IPv4 and IPv6 through one socket — so an IPv6-only host needs no flags. It falls back to 0.0.0.0 where the namespace has no usable IPv6, and logs which it chose. Add -e HOSTNAME=0.0.0.0 to pin it to IPv4 — details, and the Kubernetes equivalent, in docs/DISTRIBUTION.md.

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

A JWT_SECRET you set yourself must be at least 32 characters. A shorter one is a hard error at startup: the server prints what is wrong and exits with code 1, instead of booting into a state where the health check reports healthy but every login returns 503. Unset the variable to let the first run generate a strong secret for you.

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 DigitalOcean, Koyeb, Render, Railway, Sealos, CapRover, or Dokploy:

DigitalOcean: the Marketplace listing creates a preconfigured Droplet. Unique admin credentials are generated on first boot; the welcome message (MOTD) tells you where to find them. CapRover: open your CapRover dashboard → Apps → One-Click Apps/Databases, search for LibreDB Studio, and deploy. Koyeb: set a strong JWT_SECRET (at least 32 characters — openssl rand -base64 32) and credentials before deploying (Koyeb cannot auto-generate secrets); the prefilled values are placeholders, and a secret under 32 characters makes the app exit at startup. 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/. Fly.io: the repo ships a ready fly.toml — full steps (app name, volume, secrets) in docs/FLY.md. 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/. Dokploy: install in one click from the Dokploy template catalog — in your Dokploy dashboard, Create Service → Template, search for LibreDB Studio, and deploy. Dokploy auto-generates ADMIN_PASSWORD, USER_PASSWORD, and JWT_SECRET, and persists connections on a SQLite volume behind Traefik. See deploy/dokploy/.

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

Quick Start

Run a full Database Editor in one command, no clone, no build:

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

---

(or the Broker on 8082 - the same endpoint, no different configuration).

docker compose -f database-compose.yml --profile druid up -d

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-compo

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

bun run test