updating deployment doc

.gitignore

@@ -0,0 +1 @@
+.codex

docs/DEPLOYMENT.md

@@ -23,7 +23,7 @@ Optional but useful:
 - working `mail()` configuration for email alerts
 - `allow_url_fopen` enabled for webhook alerts
 - outbound HTTPS requests for webhook alerts
-- browser access to `cdn.jsdelivr.net` if `/docs/` should load Swagger UI
+- browser access to `cdn.jsdelivr.net` if the Swagger UI should load at `/docs/` or `<base-path>/docs/`
 
 Not required:
 
@@ -32,21 +32,29 @@ Not required:
 - Node.js
 - cron job
 
-## Important Deployment Limitation
+## Base Path And Subfolder Deployments
 
-The current app is written for deployment at the web root of a domain or subdomain, for example:
+The application now supports an optional configured base path for deployments below the domain root.
 
-- `https://monitor.example.com/`
-- `https://example.com/`
+Examples:
 
-It is currently **not prepared for deployment in a subfolder** such as `https://example.com/monitor/`, because the frontend uses root-relative URLs like:
+- root deployment: `https://monitor.example.com/`
+- root deployment: `https://example.com/`
+- subfolder deployment: `https://example.com/monitor/`
 
-- `/styles.css`
-- `/app.js`
-- `/admin/`
-- `/api/v1/status.php`
+The relevant config value is `app.base_path` in `data/config.json`:
 
-If subfolder deployment is needed later, the code should be adjusted first.
+- leave it empty for deployment directly under `/`
+- set it to the URL prefix for subfolder deployments, for example `"/monitor"`
+- the value is normalized on save, so `monitor`, `/monitor`, and `/monitor/` all become `"/monitor"`
+
+This setting is used for generated links, asset URLs, admin redirects, and dashboard API polling.
+
+Important:
+
+- `app.base_path` changes URLs, not the required PHP file layout
+- `src/` and `data/` must still stay outside the public web root
+- the public PHP files must still be deployed in a layout where their relative `../src/...` and `../data/...` paths resolve correctly
 
 ## Where Everything Should Be
 
@@ -170,7 +178,9 @@ In the hosting control panel, select PHP `8.1` or newer for the domain/subdomain
 
 ### 5. Open the app
 
-After upload, these URLs should work:
+After upload, these URLs should work.
+
+If `app.base_path` is empty:
 
 - `/`
 - `/admin/`
@@ -184,6 +194,20 @@ Examples:
 - `https://monitor.example.com/admin/`
 - `https://monitor.example.com/api/v1/status.php`
 
+If `app.base_path` is set to `/monitor`:
+
+- `/monitor/`
+- `/monitor/admin/`
+- `/monitor/api/v1/status.php`
+- `/monitor/docs/`
+- `/monitor/openapi.yaml`
+
+Examples:
+
+- `https://example.com/monitor/`
+- `https://example.com/monitor/admin/`
+- `https://example.com/monitor/api/v1/status.php`
+
 ### 6. Replace the default credentials
 
 The example files ship with placeholder credentials. After the first login, immediately change:
@@ -192,7 +216,7 @@ The example files ship with placeholder credentials. After the first login, imme
 - admin password
 - API bearer token
 
-You can do that in `/admin/`.
+You can do that in `/admin/` or `<base-path>/admin/`, depending on the deployment.
 
 ### 7. Configure the application
 
@@ -202,6 +226,7 @@ In the admin panel, configure:
 - timezone
 - dashboard refresh interval
 - email sender
+- base path
 - webhook targets
 - email recipients
 - machines
@@ -209,6 +234,11 @@ In the admin panel, configure:
 - sensor calibration values
 - alert thresholds
 
+For the base path:
+
+- leave it empty when the app is served directly from the domain root
+- set it to the exact URL prefix when the app is served from a subfolder, for example `/monitor`
+
 The JSON structure is documented in [CONFIG.md](./CONFIG.md).
 
 ### 8. Connect the sensor clients
@@ -216,11 +246,16 @@ The JSON structure is documented in [CONFIG.md](./CONFIG.md).
 Each ESP32 or other sensor client should send readings to:
 
 ```text
-POST https://your-domain.example/api/v1/readings.php
+POST https://your-domain.example<base-path>/api/v1/readings.php
 Authorization: Bearer <your-token>
 Content-Type: application/json
 ```
 
+Examples:
+
+- root deployment: `https://your-domain.example/api/v1/readings.php`
+- subfolder deployment with `app.base_path = "/monitor"`: `https://your-domain.example/monitor/api/v1/readings.php`
+
 The request and response format is documented in [API.md](./API.md).
 
 ### 9. Run a deployment check
@@ -235,13 +270,14 @@ Verify all of the following:
 - email delivery works if configured
 - `/api/v1/status.php` returns JSON
 - `/docs/` loads Swagger UI
+- all links, redirects, CSS, and JavaScript requests use the expected base path if deployed in a subfolder
 
 ## First Live Test
 
 Use one manual API call after deployment:
 
 ```bash
-curl -X POST https://your-domain.example/api/v1/readings.php \
+curl -X POST https://your-domain.example<base-path>/api/v1/readings.php \
   -H 'Authorization: Bearer YOUR_TOKEN' \
   -H 'Content-Type: application/json' \
   -d '{
@@ -287,6 +323,18 @@ Check:
 
 The app already checks both `HTTP_AUTHORIZATION` and `REDIRECT_HTTP_AUTHORIZATION`, which helps on many Apache-based hosts.
 
+### Dashboard loads without CSS/JS, or admin links point to the wrong URL
+
+Cause:
+
+- `app.base_path` does not match the actual public URL prefix
+
+Fix:
+
+- leave `app.base_path` empty for deployment at `/`
+- set it to the exact subfolder path for deployments such as `/monitor`
+- save the config again from `/admin/` or update `data/config.json` directly if the admin URL is currently wrong
+
 ### `/docs/` does not render
 
 Cause:
@@ -300,7 +348,7 @@ Fix:
 
 ## Recommended Go-Live Checklist
 
-- deploy at the domain root, not in a subfolder
+- set `app.base_path` correctly for the final public URL
 - keep `src/` and `data/` outside the public web root
 - ensure `data/` is writable
 - replace all demo credentials