Merge pull request #68 from libredb/dev

fix(docker): writable data volume for non-root user (0.9.22) + Railway template docs

Author: cevheri

.gitignore

@@ -103,3 +103,4 @@ npmjs-token
 .npmrc
 
 .token
+.sonar-token

Dockerfile

@@ -64,7 +64,17 @@ COPY --from=builder /usr/src/app/node_modules/file-uri-to-path ./node_modules/fi
 RUN addgroup --system --gid 1001 nodejs && \
     adduser --system --uid 1001 nextjs && \
     chown -R nextjs:nodejs /app
-USER nextjs
+
+# gosu lets the entrypoint drop from root to the app user after fixing the
+# permissions of a mounted (often root-owned) data volume.
+RUN apt-get update && apt-get install -y --no-install-recommends gosu && \
+    rm -rf /var/lib/apt/lists/*
+
+# Entrypoint makes the SQLite data dir writable by `nextjs` then drops privileges.
+# The container starts as root only long enough to chown the volume mount; the
+# app process itself runs as the non-root `nextjs` user.
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 
 # Render uses PORT env variable, default to 3000
 EXPOSE 3000/tcp
@@ -73,4 +83,5 @@ ENV HOSTNAME="0.0.0.0"
 
 # server.js is created by next build from the standalone output
 # https://nextjs.org/docs/pages/api-reference/next-config-js/output
+ENTRYPOINT ["docker-entrypoint.sh"]
 CMD ["node", "server.js"]

README.md

@@ -359,7 +359,7 @@ Deploy your own instance of LibreDB Studio with a single click on Koyeb, Render,
  [![Deploy to Koyeb](https://www.koyeb.com/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=libredb-studio&type=docker&image=ghcr.io%2Flibredb%2Flibredb-studio%3Alatest&instance_type=free&regions=fra&instances_min=0&autoscaling_sleep_idle_delay=3900&env%5BADMIN_EMAIL%5D=admin%40libredb.org&env%5BADMIN_PASSWORD%5D=LibreDB.2026&env%5BJWT_SECRET%5D=your_secure_pass%3D&env%5BLLM_API_KEY%5D=your_GEMINI_API_KEY&env%5BLLM_MODEL%5D=gemini-2.5-flash&env%5BLLM_PROVIDER%5D=gemini&env%5BNEXT_PUBLIC_AUTH_PROVIDER%5D=local&env%5BSTORAGE_PROVIDER%5D=postgres&env%5BSTORAGE_POSTGRES_URL%5D=postgresql%3A%2F%2Fdb_user%3Adb_pass%40your_host.eu-central-1.pg.koyeb.app%2Flibredb_storage&env%5BUSER_EMAIL%5D=user%40libredb.org&env%5BUSER_PASSWORD%5D=LibreDB.2026&ports=3000%3Bhttp%3B%2F&hc_protocol%5B3000%5D=tcp&hc_grace_period%5B3000%5D=5&hc_interval%5B3000%5D=30&hc_restart_limit%5B3000%5D=3&hc_timeout%5B3000%5D=5&hc_path%5B3000%5D=%2F&hc_method%5B3000%5D=get)  
 
  [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/libredb/libredb-studio)  
- [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/CODE?utm_medium=integration&utm_source=button&utm_campaign=libredb-studio)  
+ [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/libredb-studio?referralCode=bGijnc&utm_medium=integration&utm_source=template&utm_campaign=generic)  
 
 
 ### Environment Variables

deploy/railway/PUBLISH.md

@@ -1,69 +1,111 @@
 # Publishing the LibreDB Studio Railway Template
 
-A Railway **marketplace template** is built in the visual composer, not from a
-repo file. This is the exact checklist to create and publish it. The values to
-enter are in [`template.json`](./template.json).
+A Railway **marketplace template** is built in the visual template editor, not
+from a repo file. This is the exact checklist to create and publish it. The
+values to enter are in [`template.json`](./template.json).
 
-## 1. Open the composer
+## 1. Open the template editor
 
-- Go to https://railway.com/compose (or Workspace → **Templates** → **New Template**).
+- Go to your **Workspace → Templates** page: <https://railway.com/workspace/templates>
+- Click **New Template**. This opens the template editor (a canvas, like a project).
 
 ## 2. Add the Studio service
 
-- Click **Add New → Docker Image**.
-- Image: `ghcr.io/libredb/libredb-studio:0.9.19` (pinned — never `:latest`).
+- In the editor, click **+ New** (top-right), or open the command palette
+  (`⌘K` / `Ctrl+K`) → **+ New Service** → **Docker Image**.
+- Image: `ghcr.io/libredb/libredb-studio:0.9.22` (pinned — never `:latest`).
 - Rename the service to `libredb-studio`.
 
-## 3. Configure the service (match `template.json`)
-
-- **Variables** tab — add each variable from `template.json`. For the generated
-  ones, type the function literally:
-  - `JWT_SECRET` = `${{ secret(48) }}`
-  - `ADMIN_PASSWORD` = `${{ secret(16) }}`
-  - `USER_PASSWORD` = `${{ secret(16) }}`
-  - `ADMIN_EMAIL` = `admin@libredb.org`, `USER_EMAIL` = `user@libredb.org`
-  - `NEXT_PUBLIC_AUTH_PROVIDER` = `local`
-  - `STORAGE_PROVIDER` = `sqlite`, `STORAGE_SQLITE_PATH` = `/app/data/libredb-storage.db`
-  - `PORT` = `3000`
-  - `LLM_PROVIDER`, `LLM_API_KEY`, `LLM_MODEL`, `LLM_API_URL` = leave blank
-- **Settings** tab — enable **Public Networking**, target port `3000`; set
-  **Healthcheck Path** to `/api/db/health`.
-- **Volume** — select the service, open its **Volumes** section, and add a volume with mount path `/app/data`.
-
-## 4. Create the template
+## 3. Variables
+
+Fastest path: **Variables → Raw Editor → ENV**, paste the values below, **Update
+Variables**, then add a **description** to each (the publish form asks for one).
+The `${{ secret(...) }}` values are auto-generated per deploy.
+
+### Pre-configured variables (defaults — entered for the deployer)
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `JWT_SECRET` | `${{ secret(48) }}` | Secret key used to sign login session tokens. Auto-generated — keep it. |
+| `ADMIN_EMAIL` | `admin@libredb.org` | Login email for the ADMIN account (full access incl. maintenance tools). |
+| `ADMIN_PASSWORD` | `${{ secret(16) }}` | Password for the admin account. Auto-generated; find it in Variables after deploy. |
+| `USER_EMAIL` | `user@libredb.org` | Login email for the standard, query-only account. |
+| `USER_PASSWORD` | `${{ secret(16) }}` | Password for the standard user. Auto-generated; find it in Variables after deploy. |
+| `NEXT_PUBLIC_AUTH_PROVIDER` | `local` | Auth mode: 'local' (email/password). Set 'oidc' for SSO (needs the OIDC_* optional vars). |
+| `STORAGE_PROVIDER` | `sqlite` | Server-side storage for saved connections & settings: 'local' (browser only, no server persistence) \| 'sqlite' (file on the volume) \| 'postgres' (multi-node). Keep 'sqlite'. |
+| `STORAGE_SQLITE_PATH` | `/app/data/libredb-storage.db` | SQLite file path on the mounted volume (/app/data). Keep the default. |
+| `PORT` | `3000` | Port the app listens on. Must match the HTTP Proxy Port. Leave as 3000. |
+
+### Optional variables (add via "+ New Variable" and mark **Optional**)
+
+> ⚠️ Mark each of these **Optional** in the editor. A non-optional variable left
+> empty becomes a **required** field the deployer must fill, which breaks the
+> one-click flow. Optional vars let people enable AI / SSO / Postgres only if they want.
+
+| Variable | Example | Description |
+|----------|---------|-------------|
+| `LLM_PROVIDER` | `gemini` | Optional AI query assistance: gemini \| openai \| ollama \| custom. Omit to keep AI off. |
+| `LLM_API_KEY` | `AIza… / sk-…` | API key for the chosen AI provider (Gemini/OpenAI). Not needed for a local Ollama. |
+| `LLM_MODEL` | `gemini-2.5-flash` | AI model name; provider default used if empty (e.g. gpt-4o-mini, llama3.1). |
+| `LLM_API_URL` | `http://host:11434/v1` | Base URL for ollama/custom AI providers only. Not needed for gemini/openai. |
+| `OIDC_ISSUER` | `https://tenant.auth0.com` | OIDC issuer URL for SSO. Required when NEXT_PUBLIC_AUTH_PROVIDER=oidc. |
+| `OIDC_CLIENT_ID` | | OIDC application client ID (SSO). |
+| `OIDC_CLIENT_SECRET` | | OIDC application client secret (SSO). |
+| `OIDC_SCOPE` | `openid profile email` | OIDC scopes. Defaults to 'openid profile email' if empty. |
+| `OIDC_ROLE_CLAIM` | `realm_access.roles` | Claim path holding user roles, used for admin mapping. |
+| `OIDC_ADMIN_ROLES` | `admin` | Comma-separated role values mapped to admin. Defaults to 'admin'. |
+| `STORAGE_POSTGRES_URL` | `postgresql://user:pass@host:5432/db` | PostgreSQL URL for multi-node storage. Also set STORAGE_PROVIDER=postgres. |
+
+## 4. Settings (service)
+
+- **Networking** — set **HTTP Proxy Port** to `3000` (enables public HTTP access).
+- **Deploy** — set **Healthcheck Path** to `/api/db/health` (Restart Policy
+  `On Failure` is a sensible default).
+- **Volume** — NOT in the Settings panel. Close the settings modal, then on the
+  editor **canvas right-click the `libredb-studio` service → Attach Volume**, and
+  set the mount path to `/app/data`.
+
+## 5. Create the template
 
 - Click **Create Template**. Railway gives it an unlisted URL and a unique code
   (e.g. `ZweBXA`).
 
-## 5. Smoke-test before publishing
+## 6. Smoke-test before publishing
 
 - Deploy the unlisted template into a throwaway project.
 - Open the public domain; confirm `/api/db/health` is green and the login page loads.
 - Log in as `admin@libredb.org` with the generated `ADMIN_PASSWORD` (Variables tab).
 - Add a saved connection, then **Redeploy** the service and confirm the
   connection is still there (SQLite volume persistence).
 
-## 6. Publish
+## 7. Publish
 
 - Click **Publish** (or Workspace → Templates → **Publish** next to it).
-- Fill the form: display name **LibreDB Studio**, the description and tags from
-  `template.json`, the logo (`libredb-studio.png`), category Database/Developer Tools.
+- Fill the form: display name **LibreDB Studio**, a short description (≤75 chars,
+  e.g. `Open-source web SQL IDE with AI — PostgreSQL, MySQL, Mongo, Redis & more`),
+  tags from `template.json`, the logo (`libredb-studio.png`), category
+  Database/Developer Tools.
+- **Template Overview** (the long marketplace README field): paste the contents
+  of [`TEMPLATE_OVERVIEW.md`](./TEMPLATE_OVERVIEW.md).
 - Submit. The template is now in the marketplace and eligible for Railway's template kickback (revenue-share) program.
 
-## 7. Wire up the Deploy button
+## 8. Wire up the Deploy button
 
-- Copy the template code from the published URL
-  (`https://railway.com/new/template/<CODE>`).
-- Replace `CODE` in:
+- After publishing, the marketplace URL has the form
+  `https://railway.com/deploy/<template-name>?referralCode=<code>` (the
+  `referralCode` is how Railway attributes deploys/kickbacks to you).
+- Put the **Deploy on Railway** button (image `https://railway.com/button.svg`)
+  with that URL in:
   - root `README.md` (the `## ⚡ One-Click Deploy` section)
   - `deploy/railway/README.md`
-- Commit the change.
+- Current published link:
+  `https://railway.com/deploy/libredb-studio?referralCode=bGijnc&utm_medium=integration&utm_source=template&utm_campaign=generic`
 
 ## Maintaining the template
 
 On a new Studio release:
 
 1. Bump the image tag in `deploy/railway/template.json` and
    `deploy/railway/README.md`.
-2. In the composer / published template, update the image tag and re-publish
-   (Docker-image templates are **not** auto-updated by Railway).
+2. In the template editor / published template, update the image tag and
+   re-publish (Docker-image templates are **not** auto-updated by Railway).

deploy/railway/README.md

@@ -5,9 +5,10 @@ This folder is the **source of truth** for deploying LibreDB Studio on
 
 | File | Purpose |
 |------|---------|
-| `template.json` | Reviewable serialization of the composer service config (image, env vars, volume, healthcheck). Railway does not ingest it directly — see note below. |
+| `template.json` | Reviewable serialization of the template service config (image, env vars, volume, healthcheck). Railway does not ingest it directly — see note below. |
 | `README.md` | This file — install + post-install instructions. |
-| `PUBLISH.md` | Step-by-step checklist to create and publish the template in the Railway composer. |
+| `PUBLISH.md` | Step-by-step checklist to create and publish the template in Railway's template editor. |
+| `TEMPLATE_OVERVIEW.md` | Marketplace overview/README pasted into the publish form's "Template Overview" field. |
 | `libredb-studio.png` | 256×256 app logo. |
 
 > **Why no `railway.json` in the repo?** Railway config-as-code only controls how
@@ -17,18 +18,18 @@ This folder is the **source of truth** for deploying LibreDB Studio on
 > config file. A `railway.toml` would only cause a redundant rebuild of an image
 > CI already publishes.
 
-## Deploy (once published)
+## Deploy
 
-Click the button (replace `CODE` with the published template code):
+Click the button to deploy from the Railway template marketplace:
 
-[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/CODE?utm_medium=integration&utm_source=button&utm_campaign=libredb-studio)
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/libredb-studio?referralCode=bGijnc&utm_medium=integration&utm_source=template&utm_campaign=generic)
 
 Or browse the Railway template marketplace and search **LibreDB Studio**.
 
 ## Deploy (manual — works today, before publishing)
 
 Railway dashboard → **New Project**, then in the project view click **+ New → Docker Image** →
-enter `ghcr.io/libredb/libredb-studio:0.9.19`, then configure the service to
+enter `ghcr.io/libredb/libredb-studio:0.9.22`, then configure the service to
 match [`template.json`](./template.json):
 
 - **Networking:** enable a public domain, target port `3000`.

deploy/railway/TEMPLATE_OVERVIEW.md

@@ -0,0 +1,53 @@
+# Deploy and Host libredb-studio on Railway
+
+LibreDB Studio is an open-source, web-based SQL IDE for cloud-native teams. Query PostgreSQL, MySQL, SQLite, Oracle, SQL Server, MongoDB, and Redis from your browser — with AI-powered query assistance (natural-language-to-SQL, explain, and fix), an ERD viewer, schema diff, and a data profiler. No desktop client required.
+
+## About Hosting libredb-studio
+
+Hosting LibreDB Studio means running a single stateless Next.js container that serves the web IDE and proxies queries to the databases you connect to. This template runs the prebuilt `ghcr.io/libredb/libredb-studio` image on port 3000 with a healthcheck at `/api/db/health` — no build step required. Saved connections and settings are persisted with SQLite on an attached Railway volume (`/app/data`), so they survive restarts and redeploys. Authentication is JWT-based; a strong `JWT_SECRET` and admin/user passwords are auto-generated per deploy. Optional add-ons — AI providers (Gemini, OpenAI, Ollama, custom), OIDC SSO, or a PostgreSQL storage backend — are enabled later via environment variables.
+
+## Common Use Cases
+
+- Give a team a browser-based SQL console for cloud databases, with no desktop client to install or update.
+- Spin up an admin/query UI right next to a Railway PostgreSQL or MySQL database in the same project.
+- Use AI assistance to write, explain, and fix SQL across multiple database engines from one interface.
+
+## Dependencies for libredb-studio Hosting
+
+- A database to connect to — PostgreSQL, MySQL, SQLite, Oracle, SQL Server, MongoDB, or Redis (bring your own, or add a Railway database to the project).
+- A persistent volume mounted at `/app/data` for the SQLite-backed store of saved connections and settings (included in this template).
+
+### Deployment Dependencies
+
+- Source & docs: https://github.com/libredb/libredb-studio
+- Container image (GHCR): https://github.com/libredb/libredb-studio/pkgs/container/libredb-studio
+- README / configuration: https://github.com/libredb/libredb-studio#readme
+
+### Implementation Details
+
+After the service is healthy, open its public domain and log in with the **admin** account (`admin@libredb.org`) — the generated `ADMIN_PASSWORD` is shown in the service's **Variables** tab. A standard query-only user (`user@libredb.org`) is also created.
+
+To query a database hosted on Railway, add one to the project (**+ New → Database → PostgreSQL/MySQL**) and create a connection in Studio using the database's provided variables (`PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`).
+
+Optional environment variables enable extra features:
+
+```bash
+# AI query assistance
+LLM_PROVIDER=gemini          # gemini | openai | ollama | custom
+LLM_API_KEY=your_api_key
+LLM_MODEL=gemini-2.5-flash
+
+# SSO (OIDC) — Auth0, Keycloak, Okta, Azure AD
+NEXT_PUBLIC_AUTH_PROVIDER=oidc
+OIDC_ISSUER=https://your-tenant.example.com
+OIDC_CLIENT_ID=...
+OIDC_CLIENT_SECRET=...
+```
+
+## Why Deploy libredb-studio on Railway?
+
+<!-- Recommended: Keep this section as shown below -->
+Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.
+
+By deploying libredb-studio on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.
+<!-- End recommended section -->