docs: clarify VITE_API_URL usage; remove FRONTEND_API_URL; add storage vars; simplify compose mounts and external DB example (refs #18)

.env.example

@@ -34,9 +34,15 @@ SMTP_PASS=your-app-specific-password
 EMAIL_FROM=noreply@yourdomain.com
 
 # Application URLs
+# Use full origin with scheme, no trailing slash.
+# Admin UI is served by the frontend at /admin.
 FRONTEND_URL=https://yourdomain.com
-ADMIN_URL=https://yourdomain.com:3001
-VITE_API_URL=https://yourdomain.com:3001/api
+ADMIN_URL=https://yourdomain.com
+
+# Frontend API base
+# For pre-built images and production behind a reverse proxy, keep '/api'.
+# If you rebuild the frontend yourself, you may set a full URL at build time.
+VITE_API_URL=/api
 
 # Port Configuration (optional)
 # BACKEND_PORT=3001
@@ -50,4 +56,16 @@ TZ=UTC
 # Analytics (Optional - Umami)
 VITE_UMAMI_URL=
 VITE_UMAMI_WEBSITE_ID=
-VITE_UMAMI_SHARE_URL=
+VITE_UMAMI_SHARE_URL=
+
+# Storage variables (host paths)
+# These control where data is stored on the host. Defaults are local folders.
+APP_STORAGE=./storage
+APP_DATA=./data
+LOGS=./logs
+
+# Note on FRONTEND_API_URL (documentation only):
+# When using pre-built frontend images, runtime env vars cannot override the built JS.
+# Do NOT rely on FRONTEND_API_URL in Compose. Instead, keep VITE_API_URL=/api and
+# let the frontend Nginx proxy /api to the backend. Only if you rebuild the frontend
+# should you change VITE_API_URL at build time.

DEPLOYMENT_GUIDE.md

@@ -180,6 +180,19 @@ Update `.env` with:
   - Always include the scheme (`http://` or `https://`).
   - The backend compares origins strictly for CORS; malformed values will cause login requests to fail with 500.
 
+#### External Database Example
+To use an external PostgreSQL instead of the bundled container, set the following in `.env` and ensure the `postgres` service is disabled or removed:
+
+```env
+DB_HOST=db.example.com
+DB_PORT=5432
+DB_USER=picpeak
+DB_PASSWORD=change_me
+DB_NAME=picpeak_prod
+```
+
+Compose uses these values via `env_file: .env`. The backend service also defaults `DB_HOST=${DB_HOST:-postgres}` so if you don’t set `DB_HOST` it will use the bundled `postgres` container.
+
 ### Frontend Configuration (frontend/.env)
 Create `frontend/.env` from `frontend/.env.example`:
 ```bash

docker-compose.production.yml

@@ -41,13 +41,13 @@ services:
     env_file: .env
     environment:
       - NODE_ENV=production
-      - DB_HOST=postgres
+      - DB_HOST=${DB_HOST:-postgres}
       - REDIS_HOST=redis
       - PHOTOS_DIR=/app/storage/events
     volumes:
-      - ./storage:/app/storage
-      - ./logs:/app/logs
-      - ./data:/app/data
+      - ${APP_STORAGE}:/app/storage
+      - ${LOGS}:/app/logs
+      - ${APP_DATA}:/app/data
     ports:
       - "${BACKEND_PORT:-3001}:3000"
     networks: