From 0952c1abc989b6b79ceea7f8f1dcccd1b2496348 Mon Sep 17 00:00:00 2001
From: bea <hello@beatrice.wtf>
Date: Sun, 22 Mar 2026 14:16:40 +0100
Subject: [PATCH] docs: document VITE_API_BASE_URL and VITE_BASE_URL runtime
 configuration

- Add VITE_BASE_URL to frame-cms environment in docker-compose.yml (default /)
- Add inline comments explaining both CMS env vars
- Expand README with a runtime environment variables table and
  a subpath deployment example (e.g. serving CMS at /admin)
---
 README.md          | 40 +++++++++++++++++++++++++++++++---------
 docker-compose.yml |  5 +++++
 2 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index c0e1597..df05b64 100644
--- a/README.md
+++ b/README.md
@@ -33,12 +33,6 @@ Edit `backend.env` and at minimum set:
 | `FRONTEND_BASE_URL` | Same URL (used in email links) |
 | `SMTP_*` | Optional — needed for email verification |
 
-`VITE_API_BASE_URL` for frame-cms defaults to `http://localhost:8080`. Override it in `docker-compose.yml` or via env:
-
-```bash
-VITE_API_BASE_URL=https://api.example.com docker compose up -d
-```
-
 ### 3. Pull images and start
 
 ```bash
@@ -51,13 +45,41 @@ Services will be available at:
 - **CMS:** http://localhost:3000
 - **API:** http://localhost:8080
 
-Ports can be overridden via environment variables before `docker compose up`:
+---
+
+## Runtime environment variables
+
+Both CMS variables are injected at container startup — **no image rebuild needed**.
+
+### frame-cms
+
+| Variable | Default | Description |
+|---|---|---|
+| `VITE_API_BASE_URL` | `http://localhost:8080` | URL of the backend API as seen by the browser |
+| `VITE_BASE_URL` | `/` | Base path where the CMS is served |
+| `CMS_PORT` | `3000` | Host port for the CMS container |
+
+### frame-backend
+
+| Variable | Default | Description |
+|---|---|---|
+| `BACKEND_PORT` | `8080` | Host port for the backend container |
+
+### Subpath deployment example
+
+To serve the CMS at `https://frame.example.com/admin` and the API at `https://frame.example.com/api`:
 
 ```bash
-BACKEND_PORT=9090 CMS_PORT=4000 docker compose up -d
+# .env
+VITE_API_BASE_URL=https://frame.example.com/api
+VITE_BASE_URL=/admin
 ```
 
-### 4. Create an admin user (first time only)
+Then in your reverse proxy, strip `/api` before forwarding to the backend.
+
+---
+
+## Create an admin user (first time only)
 
 If SMTP is not configured, email verification won't work — you'll need to manually verify the user in the DB:
 
diff --git a/docker-compose.yml b/docker-compose.yml
index 06f0cd4..940ab49 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -31,7 +31,12 @@ services:
     depends_on:
       - frame-backend
     environment:
+      # URL of the backend API as seen by the browser.
+      # Override this when the API is not at the default path.
       VITE_API_BASE_URL: ${VITE_API_BASE_URL:-http://localhost:8080}
+      # Base path where the CMS is served (e.g. /admin for frame.example.com/admin).
+      # Defaults to / (served at the root).
+      VITE_BASE_URL: ${VITE_BASE_URL:-/}
     ports:
       - "${CMS_PORT:-3000}:80"
     healthcheck: