feat: add LibreDB Studio as a CapRover one-click app (#57)

cevheri · claude · web-flow · commit 5a33376ecb55 · 2026-06-14T01:55:01.000+03:00
* feat(deploy): add CapRover one-click-app template

Add the source-of-truth CapRover one-click-app definition under
deploy/caprover/ so LibreDB Studio can be installed on CapRover in one
click. The same files feed both the official caprover/one-click-apps PR
and a LibreDB-owned 3rd-party repo.

- deploy/caprover/libredb-studio.yml: captainVersion 4 template. Single
  service on container port 3000, pinned ghcr.io image (no :latest),
  SQLite persistence on a persistent volume, auto-generated JWT secret
  and admin/user passwords echoed back in instructions.end, optional
  AI/LLM fields. Passes CapRover validate_apps + prettier unchanged.
- deploy/caprover/libredb-studio.png: 256x256 logo from public/logo.svg.
- deploy/caprover/README.md: install + maintenance docs.
- docs/superpowers/specs: approved design doc.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

* docs(caprover): record live 3rd-party repo URL and mark spec criteria done

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

* feat(caprover): add examples to install-wizard field descriptions

Enrich each one-click variable description with concrete examples and
expand instructions.start into a short annotated guide (mirrors the
detail level of docker-compose.example.yml), so the CapRover install
screen is self-explanatory. Still passes validate_apps + prettier.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/deploy/caprover/README.md b/deploy/caprover/README.md
@@ -0,0 +1,70 @@
+# LibreDB Studio — CapRover One-Click App
+
+This folder is the **source of truth** for deploying LibreDB Studio on
+[CapRover](https://caprover.com) as a one-click app.
+
+| File | Purpose |
+|------|---------|
+| `libredb-studio.yml` | CapRover `captainVersion: 4` template (Docker-Compose + `caproverOneClickApp` block). |
+| `libredb-studio.png` | 256×256 app logo used by the CapRover one-click UI. |
+
+The same two files are published to two places:
+
+1. **Official repo** — submitted as a PR to
+   [`caprover/one-click-apps`](https://github.com/caprover/one-click-apps)
+   (`public/v4/apps/libredb-studio.yml` + `public/v4/logos/libredb-studio.png`).
+2. **LibreDB 3rd-party repo** — hosted by LibreDB so users can install
+   immediately, independent of the official repo's review queue.
+
+## Install (official repo, once merged)
+
+CapRover dashboard → **Apps → One-Click Apps/Databases** → search **LibreDB Studio**.
+
+## Install (LibreDB 3rd-party repo, available now)
+
+CapRover dashboard → **Apps → One-Click Apps/Databases** → scroll to
+**3rd party repositories** → paste the URL below → **Connect New Repository** →
+search **LibreDB Studio**:
+
+```
+https://libredb.org/caprover-one-click-apps
+```
+
+Source for that repo: <https://github.com/libredb/caprover-one-click-apps>.
+
+## Install (manual template — works today, no repo needed)
+
+CapRover dashboard → **Apps → One-Click Apps/Databases** → select
+**`>> TEMPLATE <<`** at the bottom of the dropdown → paste the contents of
+`libredb-studio.yml` → **Next**.
+
+## What the template does
+
+- Runs `ghcr.io/libredb/libredb-studio` (pinned version, never `:latest`) on
+  container HTTP port `3000`.
+- Generates a strong `JWT_SECRET` and admin/user passwords automatically and
+  echoes the login credentials on the final install screen.
+- Persists saved connections & settings with **SQLite** on a CapRover
+  persistent volume (`$$cap_appname-data` → `/app/data`), surviving restarts
+  and redeploys.
+- Exposes optional AI/LLM fields (Gemini, OpenAI, Ollama, custom) — leave blank
+  to disable.
+
+## Post-install options
+
+Set these under the app's **App Configs** tab 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** (multi-node) — `STORAGE_PROVIDER=postgres`,
+  `STORAGE_POSTGRES_URL=...`.
+
+## Maintaining this template
+
+When a new Studio version is released, bump the `defaultValue` of
+`$$cap_version` in `libredb-studio.yml` and re-publish to both repos. Validate
+locally with the CapRover repo's tooling:
+
+```bash
+npm ci && npm run validate_apps && npm run formatter
+```
diff --git a/deploy/caprover/libredb-studio.png b/deploy/caprover/libredb-studio.png
diff --git a/deploy/caprover/libredb-studio.yml b/deploy/caprover/libredb-studio.yml
@@ -0,0 +1,114 @@
+captainVersion: 4
+services:
+    $$cap_appname:
+        image: ghcr.io/libredb/libredb-studio:$$cap_version
+        restart: always
+        environment:
+            # --- Authentication (auto-generated, shown after install) ---
+            JWT_SECRET: $$cap_gen_random_hex(48)
+            ADMIN_EMAIL: $$cap_admin_email
+            ADMIN_PASSWORD: $$cap_admin_password
+            USER_EMAIL: $$cap_user_email
+            USER_PASSWORD: $$cap_user_password
+            NEXT_PUBLIC_AUTH_PROVIDER: local
+            # --- Storage: SQLite file on the persistent volume below ---
+            STORAGE_PROVIDER: sqlite
+            STORAGE_SQLITE_PATH: /app/data/libredb-storage.db
+            # --- AI / LLM (optional) — leave blank to disable AI features ---
+            LLM_PROVIDER: $$cap_llm_provider
+            LLM_API_KEY: $$cap_llm_api_key
+            LLM_MODEL: $$cap_llm_model
+            LLM_API_URL: $$cap_llm_api_url
+        volumes:
+            - $$cap_appname-data:/app/data
+        caproverExtra:
+            containerHttpPort: '3000'
+caproverOneClickApp:
+    variables:
+        - id: $$cap_version
+          label: LibreDB Studio Version
+          defaultValue: '0.9.14'
+          description: Image tag to deploy. Always pin a fixed version, never "latest". Example - 0.9.14. Browse all valid tags at https://github.com/libredb/libredb-studio/pkgs/container/libredb-studio
+          validRegex: '/^([^\s^\/])+$/'
+        - id: $$cap_admin_email
+          label: Admin Email
+          defaultValue: admin@libredb.org
+          description: Login email for the ADMIN account - full access, including query execution plus maintenance/admin tools. Example - admin@yourcompany.com
+          validRegex: '/^.+@.+\..+$/'
+        - id: $$cap_admin_password
+          label: Admin Password
+          defaultValue: $$cap_gen_random_hex(16)
+          description: Password for the admin login. A strong random one is pre-filled - keep it or type your own (min 8 chars). Shown only once on the final screen, so save it. Example - MyStr0ng-AdminPass
+          validRegex: '/.{8,}/'
+        - id: $$cap_user_email
+          label: User Email
+          defaultValue: user@libredb.org
+          description: Login email for the STANDARD account - query execution only, no admin tools. Example - analyst@yourcompany.com
+          validRegex: '/^.+@.+\..+$/'
+        - id: $$cap_user_password
+          label: User Password
+          defaultValue: $$cap_gen_random_hex(16)
+          description: Password for the standard login. A strong random one is pre-filled - keep it or type your own (min 8 chars). Shown only once on the final screen. Example - An0ther-StrongPass
+          validRegex: '/.{8,}/'
+        - id: $$cap_llm_provider
+          label: AI Provider (optional)
+          defaultValue: ''
+          description: OPTIONAL - turns on AI query help (natural-language to SQL, explain, fix). One of - gemini | openai | ollama | custom. Leave blank to keep AI off. Example - gemini
+        - id: $$cap_llm_api_key
+          label: AI API Key (optional)
+          defaultValue: ''
+          description: OPTIONAL - API key for the chosen provider. Needed for gemini/openai, not for a local ollama. Examples - Gemini AIza... , OpenAI sk-... . Leave blank if AI is off.
+        - id: $$cap_llm_model
+          label: AI Model (optional)
+          defaultValue: ''
+          description: OPTIONAL - model name for the provider. Leave blank to use the provider default. Examples - gemini-2.5-flash , gpt-4o-mini , llama3.1
+        - id: $$cap_llm_api_url
+          label: AI API URL (optional)
+          defaultValue: ''
+          description: OPTIONAL - base URL for ollama/custom providers only (not for gemini/openai). Example for an Ollama app on this same CapRover - http://srv-captain--ollama:11434/v1
+    instructions:
+        start: |-
+            LibreDB Studio is a modern, open-source, web-based SQL IDE for the cloud era.
+            Query PostgreSQL, MySQL, SQLite, Oracle, SQL Server, MongoDB and Redis from
+            your browser - with AI-powered query assistance, an ERD viewer, schema diff
+            and more.
+
+            What you can set below (defaults are sensible - you can usually just click Deploy):
+              - Version: the image tag to deploy (a tested fixed version by default).
+              - Admin login: full access, including maintenance/admin tools.
+              - User login: query execution only.
+                Both passwords are pre-generated; change them if you like. They are
+                shown only once on the final screen - save them then.
+              - AI (optional): fill these to enable query assistance with Gemini,
+                OpenAI, Ollama or a custom provider. Leave blank to keep AI disabled.
+
+            Your saved connections and settings are persisted with SQLite on a CapRover
+            volume, so they survive restarts and redeploys.
+
+            More details and docs: https://github.com/libredb/libredb-studio
+        end: |-
+            LibreDB Studio has been deployed! 🚀
+
+            Open it at: http://$$cap_appname.$$cap_root_domain
+            (Enable HTTPS from the CapRover dashboard for production use.)
+
+            Log in with the admin account:
+              Email:    $$cap_admin_email
+              Password: $$cap_admin_password
+
+            A standard query-only user was also created:
+              Email:    $$cap_user_email
+              Password: $$cap_user_password
+
+            ⚠️  Save these credentials now — the passwords are not shown again.
+
+            Your data (saved connections & settings) is stored in SQLite on the
+            persistent volume "$$cap_appname-data" and survives restarts and redeploys.
+
+            To enable SSO (Auth0/Keycloak/Okta/Azure AD) or change AI settings later,
+            add the OIDC_* / LLM_* environment variables under the app's
+            "App Configs" tab. See https://github.com/libredb/libredb-studio
+    displayName: LibreDB Studio
+    isOfficial: false
+    description: Open-source web-based SQL IDE. Query PostgreSQL, MySQL, SQLite, Oracle, SQL Server, MongoDB & Redis from your browser, with AI-powered query assistance.
+    documentation: Image and docs - https://github.com/libredb/libredb-studio . Uses ghcr.io/libredb/libredb-studio. Deploys with SQLite persistence; supports OIDC SSO and multiple AI providers via extra env vars.
diff --git a/docs/superpowers/specs/2026-06-14-caprover-one-click-app-design.md b/docs/superpowers/specs/2026-06-14-caprover-one-click-app-design.md
@@ -0,0 +1,109 @@
+# LibreDB Studio → CapRover One-Click App — Design
+
+**Date:** 2026-06-14
+**Status:** Approved
+**Branch:** `feat/caprover-one-click-app`
+
+## Goal
+
+Make LibreDB Studio installable on [CapRover](https://caprover.com) in one click,
+as the first step of a broader strategy to integrate Studio into cloud
+providers / PaaS platforms. CapRover is the beachhead because it has a simple,
+well-documented one-click-app format and a self-serve 3rd-party repository
+mechanism.
+
+## Strategy (decided)
+
+**Official PR + LibreDB-owned 3rd-party repo.** CapRover's official repo
+(`caprover/one-click-apps`) gatekeeps on popularity ("apps with thousands of
+stars"), so the official PR may stall regardless of quality. To guarantee
+availability we ship two channels:
+
+1. **Official PR** to `caprover/one-click-apps` — maximum discoverability.
+2. **LibreDB 3rd-party repo** (GitHub Pages) — instant availability, no
+   dependency on the upstream merge decision.
+
+Both channels are fed from a single **source of truth** committed to the Studio
+repo at `deploy/caprover/`.
+
+## Deliverables
+
+### A. `libredb-studio` repo
+- **GitHub Issue** (English) tracking the integration with rationale and
+  acceptance criteria.
+- **Feature branch** `feat/caprover-one-click-app`.
+- **`deploy/caprover/`** folder — source of truth:
+  - `libredb-studio.yml` — the CapRover template.
+  - `libredb-studio.png` — 256×256 logo (rendered from `public/logo.svg`).
+  - `README.md` — install + maintenance docs.
+- **Spec doc** (this file).
+
+### B. `caprover/one-click-apps` (upstream) — the PR
+- Fork → branch → add `public/v4/apps/libredb-studio.yml` and
+  `public/v4/logos/libredb-studio.png` → run `validate_apps` + `formatter` →
+  open PR using their template (self-check boxes ticked).
+
+### C. LibreDB 3rd-party CapRover repo
+- A repo structured like `caprover/one-click-apps`, published via GitHub Pages,
+  so users can add it under **3rd party repositories** in CapRover.
+- *Note:* creating a brand-new repo + enabling GitHub Pages may require manual
+  steps / org permissions; the spec documents the structure and the publish
+  flow, and flags what needs a human hand.
+
+## The template (`libredb-studio.yml`)
+
+`captainVersion: 4`, a single service named `$$cap_appname`:
+
+- **Image:** `ghcr.io/libredb/libredb-studio:$$cap_version` — pinned, default
+  `0.9.14`. Never `:latest` (CapRover forbids it; tag is enforced by their
+  validator/PR checklist).
+- **Port:** `caproverExtra.containerHttpPort: '3000'`.
+- **Persistence:** named volume `$$cap_appname-data` → `/app/data`, with
+  `STORAGE_PROVIDER=sqlite` and `STORAGE_SQLITE_PATH=/app/data/libredb-storage.db`.
+- **Auth (auto-generated):**
+  - `JWT_SECRET: $$cap_gen_random_hex(48)` (≥32 chars guaranteed).
+  - `ADMIN_PASSWORD` / `USER_PASSWORD` are **variables** defaulting to
+    `$$cap_gen_random_hex(16)` so the generated values can be echoed back in
+    `instructions.end`. (Inlining the generator in `environment` would produce a
+    different value than any shown to the user — hence variables.)
+  - `ADMIN_EMAIL` / `USER_EMAIL` are variables with sensible defaults so the
+    end screen shows the exact login email.
+- **AI/LLM (optional):** `$$cap_llm_provider/api_key/model/api_url` variables,
+  empty by default — power users fill them, everyone else ignores.
+- **`instructions.end`** echoes the login email + generated passwords and warns
+  the user to save them, then explains where data lives and how to enable
+  OIDC/Postgres later.
+
+### Decisions & rationale
+
+| Decision | Why |
+|----------|-----|
+| SQLite + persistent volume as default | Single container, survives restarts, no extra DB password/service. Simplest reliable persistence for a one-click DB tool. (localStorage loses data; bundled Postgres is heavier and more failure-prone on first install.) |
+| Auto-generate + echo credentials | Zero-effort install while still secure; user can log in immediately from the final screen. |
+| AI optional & blank | Studio works fully without AI; avoids forcing API keys at install. |
+| OIDC/Postgres documented post-install, not in wizard | Keeps the install wizard short; advanced setups are env-var additions in App Configs. |
+| `isOfficial: false` | Images are LibreDB's own (not a universally-recognized official source); honest per the repo's guidance. |
+| Source of truth in `deploy/caprover/` | One place to maintain; both the upstream PR and the 3rd-party repo copy from it. |
+
+## Validation
+
+The template passes CapRover's own tooling with no changes:
+
+```bash
+npm ci && npm run validate_apps   # "Validated libredb-studio"
+npm run formatter                 # "All matched files use Prettier code style!"
+```
+
+## Acceptance criteria
+
+- [x] `deploy/caprover/` committed on the feature branch (yml + png + README).
+- [x] Spec committed.
+- [x] GitHub Issue opened on `libredb/libredb-studio` (English) — [#56](https://github.com/libredb/libredb-studio/issues/56).
+- [x] PR opened on `caprover/one-click-apps` with passing validator + formatter — [#1303](https://github.com/caprover/one-click-apps/pull/1303).
+- [x] LibreDB 3rd-party repo live — [libredb/caprover-one-click-apps](https://github.com/libredb/caprover-one-click-apps), published at <https://libredb.org/caprover-one-click-apps> (verified serving `/v4/list`).
+
+## Maintenance
+
+On each Studio release, bump `$$cap_version` `defaultValue` and re-publish to
+both channels. CI in the 3rd-party repo can mirror the official repo's
+`validate_apps` + `formatter` + GitHub Pages build.
