opengeos · giswqs · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -127,6 +127,14 @@ Desktop filesystem dialogs, local MBTiles, local raster file reads, project save
 
 ### Run with Docker
 
+!!! tip "Private deployments"
+    If you are deploying GeoLibre so a team can work with data that must stay on
+    your own infrastructure, read
+    [Self-Hosting & Private Data](self-hosting.md) alongside this section: it
+    covers hosting the data (with [GeoLens](https://getgeolens.com)), putting
+    both behind one sign-on layer, and why serving them from the same origin
+    removes the CORS and cookie problems.
+
 The repository includes a Dockerfile for the browser version of GeoLibre. It builds the Vite app and serves the production files with nginx:
 
 ```bash
@@ -245,7 +253,9 @@ manager.
 
 Basic Auth is a single shared credential, not per-user accounts, and sends
 credentials with every request. For multi-user or SSO needs, put an auth proxy
-such as `oauth2-proxy` or Authelia in front of the unmodified image instead.
+such as `oauth2-proxy` or Authelia in front of the unmodified image instead (see
+[Self-Hosting & Private Data](self-hosting.md#putting-both-behind-one-auth-layer)
+for a worked example that also covers the data behind it).
 Also see the note in
 [`docker/nginx.conf`](https://github.com/opengeos/GeoLibre/blob/main/docker/nginx.conf)
 about dropping the `localhost` CSP allowances before exposing the image

diff --git a/docs/index.md b/docs/index.md
@@ -135,6 +135,8 @@ GeoLibre Web is the full browser version of the GeoLibre app, ready to use with
 !!! note "Hosted on GitHub Pages, private by design"
     GeoLibre Web is a static site deployed on GitHub Pages and runs entirely in your browser. It has no analytics and no server account, and the data you load is processed client-side in your browser session. Data leaves your browser only when you choose to add a remote URL or explicitly share a project.
 
+    If your data cannot be public at all, run the same web build on your own server next to your data. See [Self-Hosting & Private Data](self-hosting.md).
+
 Open a project by passing a public `.geolibre.json` URL with the `url` query parameter:
 
 ```text

diff --git a/docs/self-hosting.md b/docs/self-hosting.md
diff --git a/docs/user-guide/data-integrations.md b/docs/user-guide/data-integrations.md
@@ -16,6 +16,30 @@ Beyond the [Add Data](adding-data.md) menu, GeoLibre connects to several hosted
 !!! note "Credentials"
     Earth Engine requires authentication, and some providers expect an API key or token. Set these in **Settings → Environment Variables**. See [Settings & Preferences](settings.md).
 
+## Self-hosted catalogs
+
+| Integration | Where | What it does |
+| --- | --- | --- |
+| **GeoLens** | Plugins menu | Connect to a self-hosted [GeoLens](https://getgeolens.com) catalog, search its datasets, and add them as signed vector tiles, OGC API Features GeoJSON, or server-rendered raster tiles. |
+
+GeoLens is an open-source spatial catalog (FastAPI + PostGIS) that you run on
+your own infrastructure, which makes it the recommended way to keep private data
+private while still working with it in GeoLibre. In the plugin panel, enter your
+server's base URL (for example `https://maps.example.org`) and, for private
+datasets, a GeoLens API key. Each result links back to its metadata page, vector
+tile tokens are refreshed automatically before they expire, and a dataset loaded
+as GeoJSON can be edited and written back to GeoLens feature by feature when the
+server allows it.
+
+The API key is kept in memory for the session only: it is never written to the
+project file or to browser storage, so a saved project records just the server
+URL and dataset id. Layers from public datasets restore automatically; layers
+from private ones stay blank until the recipient reconnects with their own key.
+
+See [Self-Hosting & Private Data](../self-hosting.md) for the full deployment
+guide, including how to serve GeoLibre and GeoLens from one origin behind a
+single sign-on layer.
+
 ## Federal Web Services
 
 The **Web Services** submenu of the [Plugins menu](plugins.md) bundles four United States federal data sources:

diff --git a/docs/user-guide/embedding.md b/docs/user-guide/embedding.md
@@ -34,6 +34,14 @@ A chrome-free `maponly` embed shows only the map, as in this shared 3D Tiles pro
 | `theme`      | `theme=dark`                                               | Sets the initial color theme, overriding the OS preference. Accepts `dark` or `light`; the in-app toggle still works afterward.       |
 | `tool`       | `tool=adaptive_filter`                                     | Opens the Processing (Whitebox toolbox) dialog on a specific tool by its id. Unknown ids open the dialog without preselecting a tool. |
 
+!!! note "Private projects and data"
+    `url=` and `data=` are fetched by the browser with same-origin credentials,
+    so a project or dataset gated by a session cookie loads only when GeoLibre is
+    served from that same origin. Passing a login-protected URL to the hosted
+    viewer at `web.geolibre.app` fails, because the cookie is not sent
+    cross-origin. Serve the app from your own host, or use a signed, expiring
+    URL. See [Self-Hosting & Private Data](../self-hosting.md).
+
 Parameters combine. For a narrow, chrome-free, dark embed of a shared project:
 
 ```text

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -81,6 +81,7 @@ nav:
       - Source Code Deep Dive (中文): tutorials/source-code-deep-dive-zh.md
   - Reference:
       - Architecture: architecture.md
+      - Self-Hosting: self-hosting.md
       - Android: android.md
       - iOS: ios.md
       - Mac App Store: mac-app-store.md

diff --git a/packages/plugins/src/plugins/geolens-api.ts b/packages/plugins/src/plugins/geolens-api.ts
@@ -90,12 +90,11 @@ export interface GeoLensVectorTiles {
  * dataset renders anonymously; a private one renders when the browser carries a
  * GeoLens session cookie or embed token for the same origin.
  *
- * Known limitation: an API-key-only private raster cannot render, because
- * MapLibre issues the tile image requests and does not attach the `X-Api-Key`
- * header, and GeoLens does not (yet) return a URL-signed raster template the
- * way it does for vector tiles. Rendering those would need a signed raster URL
- * from GeoLens or an authenticated tile proxy — a server-side change beyond
- * this client. Public and session/embed-authorized rasters are unaffected.
+ * An API-key-only private raster also renders: MapLibre issues the tile image
+ * requests itself, so the key cannot ride along the way it does on this
+ * module's fetch calls, and `maplibre-geolens.ts` instead attaches `X-Api-Key`
+ * through MapLibre's `transformRequest` hook, scoped to exactly that raster's
+ * tile-URL prefix (see `registerRasterApiKey` there).
  */
 export interface GeoLensRasterTiles {
   /** Absolute `{z}/{x}/{y}.png` XYZ template. */