LibreDB Studio on Cosmos

July 8, 2026 · View on GitHub

Cosmos (azukaar/Cosmos-Server) is a self-hosted server manager and reverse proxy that bundles authentication, a built-in firewall, and an application-layer security proxy (SmartShield). It installs apps from a community "servapp" marketplace with one click.

LibreDB Studio is listed in the official Cosmos servapp marketplace (merged in azukaar/cosmos-servapps-official#218). The canonical servapp definition lives in the Cosmos marketplace repo at servapps/LibreDB-Studio/; this folder is a documentation mirror, not the source of truth.

Tracking issue: libredb-studio#172

Install

From a running Cosmos instance (see the Cosmos install docs to set one up):

  1. Open your Cosmos dashboard → Marketplace.
  2. Search for LibreDB Studio.
  3. Install. Cosmos auto-generates the admin/user passwords and JWT_SECRET, provisions a persistent volume, and wires up a SmartShield-protected route.
  4. Set the URL for the app when prompted, then finish the install.

What the servapp does

  • Runs the prebuilt ghcr.io/libredb/libredb-studio image (pinned tag, never :latest) as a single container on HTTP port 3000.
  • Persists saved connections & settings with SQLite (STORAGE_PROVIDER=sqlite, STORAGE_SQLITE_PATH=/app/data/libredb-storage.db) on a named volume mounted at /app/data, surviving restarts and redeploys — no external database required.
  • Auto-generates ADMIN_PASSWORD, USER_PASSWORD, and JWT_SECRET via Cosmos's {Password} template tokens, so no secrets are hard-coded.
  • Exposes the app through a Cosmos SERVAPP route with SmartShield enabled, bot blocking, and cosmos-force-network-secured — keeping the container off the public network except through the secured reverse proxy.

First login

After install, open the app's URL and log in:

  • Admin (full access incl. maintenance tools): admin@libredb.org + the auto-generated ADMIN_PASSWORD.
  • User (query execution only): user@libredb.org + the auto-generated USER_PASSWORD.

Retrieve the generated passwords from the Cosmos dashboard under the servapp's environment variables if you did not note them at install time.

Environment variables

See the main README environment table for the full list. The servapp ships with:

VariableNotes
ADMIN_EMAIL / ADMIN_PASSWORDadmin login (password auto-generated)
USER_EMAIL / USER_PASSWORDstandard user login (password auto-generated)
JWT_SECRETauto-generated by Cosmos
STORAGE_PROVIDERsqlite (default here); postgres for an external backend
STORAGE_SQLITE_PATH/app/data/libredb-storage.db (on the persistent volume)

Post-install options

Add these variables to the servapp (Cosmos dashboard → the app → Environment variables) to extend the deployment:

  • SSO / OIDC — NEXT_PUBLIC_AUTH_PROVIDER=oidc, OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ROLE_CLAIM, OIDC_ADMIN_ROLES.
  • PostgreSQL storage backend — STORAGE_PROVIDER=postgres, STORAGE_POSTGRES_URL=....
  • AI — LLM_PROVIDER (gemini | openai | ollama | custom), LLM_API_KEY, LLM_MODEL, LLM_API_URL.

Version bumps

The servapp's cosmos-compose.json pins a specific image tag. On each release, bump the tag in the Cosmos marketplace repo's servapps/LibreDB-Studio/cosmos-compose.json (same manual-bump caveat as the Railway, CapRover, and Kubero Docker-image templates). The servapp sets cosmos-auto-update, so Cosmos keeps the pinned tag's digest fresh, but moving to a new version still requires updating the pinned tag upstream.

More details and docs: https://github.com/libredb/libredb-studio