Skip to content

Commit 33a45ac

Browse files
cevhericevheri
authored
docs(deploy): add Cosmos servapp deployment guide (#102)
* docs(deploy): add Cosmos servapp deployment guide and README entry LibreDB Studio is now listed in the official Cosmos servapp marketplace (azukaar/cosmos-servapps-official#218). Mirror the marketplace servapp as a documentation reference under deploy/cosmos/ and link it from the README One-Click Deploy and Deployment sections, alongside the existing Koyeb/Railway/CapRover/Kubero entries. * chore(package): bump version to 0.9.35 * docs(deploy): use Cosmos's canonical "Marketplace" naming Address Copilot review on #102: Cosmos calls its app store "Marketplace" (one word), not "Market Place". Fix all three occurrences in README.md and deploy/cosmos/README.md.
1 parent 01c8785 commit 33a45ac

3 files changed

Lines changed: 103 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -367,6 +367,8 @@ Deploy your own instance of LibreDB Studio with a single click on Koyeb, Render,
367367
> **CapRover:** open your CapRover dashboard → **Apps → One-Click Apps/Databases**, search for **LibreDB Studio**, and deploy.
368368
>
369369
> **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/`](deploy/koyeb/).
370+
>
371+
> **Cosmos:** install in one click from the [Cosmos](https://cosmos-cloud.io) 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/`](deploy/cosmos/).
370372
371373
372374
### Environment Variables
@@ -439,6 +441,19 @@ with SQLite persistence on a 5Gi volume at `/app/data`. See
439441
Railway and CapRover, Docker-image templates require a manual version bump on
440442
each release.
441443
444+
### Cosmos
445+
446+
LibreDB Studio is listed in the official
447+
[Cosmos servapp marketplace](https://github.com/azukaar/cosmos-servapps-official)
448+
([Cosmos](https://cosmos-cloud.io) is a self-hosted server manager and secure
449+
reverse proxy). From your Cosmos dashboard, open **Marketplace**, search
450+
**LibreDB Studio**, and install. Cosmos auto-generates the credentials and
451+
`JWT_SECRET`, provisions a persistent SQLite volume at `/app/data`, and serves
452+
the app behind a SmartShield-protected route. See
453+
[`deploy/cosmos/`](deploy/cosmos/) for install and post-install details. As with
454+
Railway, CapRover, and Kubero, Docker-image templates require a manual version
455+
bump on each release.
456+
442457
### Render (Recommended for cloud deployment)
443458
444459
LibreDB Studio includes a `render.yaml` Blueprint for one-click deployment:

‎deploy/cosmos/README.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# LibreDB Studio on Cosmos
2+
3+
[Cosmos](https://cosmos-cloud.io) ([azukaar/Cosmos-Server](https://github.com/azukaar/Cosmos-Server))
4+
is a self-hosted server manager and reverse proxy that bundles authentication,
5+
a built-in firewall, and an application-layer security proxy (SmartShield). It
6+
installs apps from a community "servapp" marketplace with one click.
7+
8+
LibreDB Studio is listed in the official
9+
[Cosmos servapp marketplace](https://github.com/azukaar/cosmos-servapps-official)
10+
(merged in
11+
[azukaar/cosmos-servapps-official#218](https://github.com/azukaar/cosmos-servapps-official/pull/218)).
12+
The canonical servapp definition lives in the Cosmos marketplace repo at
13+
[`servapps/LibreDB-Studio/`](https://github.com/azukaar/cosmos-servapps-official/tree/master/servapps/LibreDB-Studio);
14+
this folder is a documentation mirror, not the source of truth.
15+
16+
## Install
17+
18+
From a running Cosmos instance (see the
19+
[Cosmos install docs](https://cosmos-cloud.io/doc/1%20index/) to set one up):
20+
21+
1. **Open your Cosmos dashboard** → **Marketplace**.
22+
2. **Search** for **LibreDB Studio**.
23+
3. **Install.** Cosmos auto-generates the admin/user passwords and `JWT_SECRET`,
24+
provisions a persistent volume, and wires up a SmartShield-protected route.
25+
4. **Set the URL** for the app when prompted, then finish the install.
26+
27+
## What the servapp does
28+
29+
- Runs the prebuilt `ghcr.io/libredb/libredb-studio` image (pinned tag, never
30+
`:latest`) as a single container on HTTP port `3000`.
31+
- Persists saved connections & settings with **SQLite**
32+
(`STORAGE_PROVIDER=sqlite`, `STORAGE_SQLITE_PATH=/app/data/libredb-storage.db`)
33+
on a named volume mounted at `/app/data`, surviving restarts and redeploys —
34+
no external database required.
35+
- Auto-generates `ADMIN_PASSWORD`, `USER_PASSWORD`, and `JWT_SECRET` via Cosmos's
36+
`{Password}` template tokens, so no secrets are hard-coded.
37+
- Exposes the app through a Cosmos `SERVAPP` route with **SmartShield** enabled,
38+
bot blocking, and `cosmos-force-network-secured` — keeping the container off
39+
the public network except through the secured reverse proxy.
40+
41+
## First login
42+
43+
After install, open the app's URL and log in:
44+
45+
- **Admin** (full access incl. maintenance tools): `admin@libredb.org` + the
46+
auto-generated `ADMIN_PASSWORD`.
47+
- **User** (query execution only): `user@libredb.org` + the auto-generated
48+
`USER_PASSWORD`.
49+
50+
Retrieve the generated passwords from the Cosmos dashboard under the servapp's
51+
environment variables if you did not note them at install time.
52+
53+
## Environment variables
54+
55+
See the [main README environment table](../../README.md#environment-variables)
56+
for the full list. The servapp ships with:
57+
58+
| Variable | Notes |
59+
|----------|-------|
60+
| `ADMIN_EMAIL` / `ADMIN_PASSWORD` | admin login (password auto-generated) |
61+
| `USER_EMAIL` / `USER_PASSWORD` | standard user login (password auto-generated) |
62+
| `JWT_SECRET` | auto-generated by Cosmos |
63+
| `STORAGE_PROVIDER` | `sqlite` (default here); `postgres` for an external backend |
64+
| `STORAGE_SQLITE_PATH` | `/app/data/libredb-storage.db` (on the persistent volume) |
65+
66+
## Post-install options
67+
68+
Add these variables to the servapp (Cosmos dashboard → the app → **Environment
69+
variables**) to extend the deployment:
70+
71+
- **SSO / OIDC** — `NEXT_PUBLIC_AUTH_PROVIDER=oidc`, `OIDC_ISSUER`,
72+
`OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_ROLE_CLAIM`, `OIDC_ADMIN_ROLES`.
73+
- **PostgreSQL storage backend** — `STORAGE_PROVIDER=postgres`,
74+
`STORAGE_POSTGRES_URL=...`.
75+
- **AI** — `LLM_PROVIDER` (`gemini` | `openai` | `ollama` | `custom`),
76+
`LLM_API_KEY`, `LLM_MODEL`, `LLM_API_URL`.
77+
78+
## Version bumps
79+
80+
The servapp's `cosmos-compose.json` pins a specific image tag. On each release,
81+
bump the tag in the Cosmos marketplace repo's
82+
`servapps/LibreDB-Studio/cosmos-compose.json` (same manual-bump caveat as the
83+
Railway, CapRover, and Kubero Docker-image templates). The servapp sets
84+
`cosmos-auto-update`, so Cosmos keeps the pinned tag's digest fresh, but moving
85+
to a new version still requires updating the pinned tag upstream.
86+
87+
More details and docs: https://github.com/libredb/libredb-studio

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@libredb/studio",
3-
"version": "0.9.34",
3+
"version": "0.9.35",
44
"private": false,
55
"publishConfig": {
66
"access": "public"

0 commit comments

Comments
 (0)