feuerwehr-getraenkeautomat-status/docs/DEPLOYMENT.md

Deployment Guide

This application can run on basic shared webhosting because it uses:

• plain PHP
• no database
• no Composer dependencies
• JSON files for persistence

The deployment target assumed by this guide is a classic shared hosting account with a document root such as public_html/.

Requirements

Required:

• PHP 8.1 or newer recommended
• PHP sessions enabled
• permission for PHP to read src/ and read/write data/
• domain or subdomain pointing to the app

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 the Swagger UI should load at /docs/ or <base-path>/docs/

Not required:

• database
• Composer
• Node.js
• cron job

Base Path And Subfolder Deployments

The application now supports an optional configured base path for deployments below the domain root.

Examples:

• root deployment: https://monitor.example.com/
• root deployment: https://example.com/
• subfolder deployment: https://example.com/monitor/

The relevant config value is app.base_path in data/config.json:

• 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

Preferred layout if the host allows a custom document root

Keep the repository structure as-is and point the domain document root to public/.

/home/account/getraenke-monitor/
├── data/
│   ├── alert_log.json
│   ├── config.json
│   └── state.json
├── public/              <- document root
│   ├── admin/
│   ├── api/
│   ├── docs/
│   ├── app.js
│   ├── index.php
│   ├── openapi.yaml
│   └── styles.css
└── src/

Recommended layout for basic shared hosting with public_html/

If the host does not let you choose public/ as document root, upload the files like this:

/home/account/
├── data/
│   ├── alert_log.json
│   ├── config.json
│   └── state.json
├── public_html/         <- public contents go here
│   ├── admin/
│   ├── api/
│   ├── docs/
│   ├── app.js
│   ├── index.php
│   ├── openapi.yaml
│   └── styles.css
└── src/

Important:

• upload the contents of public/ into public_html/
• upload src/ next to public_html/, not inside it
• upload data/ next to public_html/, not inside it

This exact layout matches how the PHP files resolve ../src/bootstrap.php and ../data/....

What Must Be Public And What Must Stay Private

Public in the web root:

• index.php
• styles.css
• app.js
• openapi.yaml
• admin/
• api/
• docs/

Private, outside the public web root:

• src/
• data/config.json
• data/state.json
• data/alert_log.json

Do not place data/ inside the public web root if you can avoid it. Those files contain credentials, live state, and alert history.

Deployment Steps

1. Prepare the files

From this repository, you need these folders:

• public/
• src/
• data/

You do not need docs/ on the server for runtime operation. The docs/ folder in the repository is only Markdown documentation for developers.

2. Upload the application

Using FTP, SFTP, or your hosting file manager:

• upload src/ outside the public web root
• upload data/ outside the public web root
• upload the contents of public/ into the public web root

For a typical shared host that means:

• repo src/ -> server ~/src/
• repo data/ -> server ~/data/
• repo public/* -> server ~/public_html/

3. Set permissions

PHP must be able to write to data/ and the JSON files in it.

Typical safe defaults:

• directories: 755 or 775
• files: 644 or 664

If the host runs PHP under your own account, 755/644 is often enough. If writes fail, adjust group write permissions first before considering anything more permissive.

The app needs write access for:

• data/config.json
• data/state.json
• data/alert_log.json

4. Set the PHP version

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.

If app.base_path is empty:

• /
• /admin/
• /api/v1/status.php
• /docs/
• /openapi.yaml

Examples:

• https://monitor.example.com/
• 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:

• admin username
• admin password
• API bearer token

You can do that in /admin/ or <base-path>/admin/, depending on the deployment.

7. Configure the application

In the admin panel, configure:

• app name
• timezone
• dashboard refresh interval
• email sender
• base path
• webhook targets
• email recipients
• machines
• slots
• 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.

8. Connect the sensor clients

Each ESP32 or other sensor client should send readings to:

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.

9. Run a deployment check

Verify all of the following:

• dashboard loads without PHP errors
• admin login works
• saving config works
• data/state.json updates after a test reading
• webhook delivery works if configured
• 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:

curl -X POST https://your-domain.example<base-path>/api/v1/readings.php \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "machine_id": "automat-lobby",
    "sensor_id": "fach-a1",
    "distance_mm": 184
  }'

If that works, the dashboard should shortly show the new state.

Troubleshooting

Dashboard loads, but saving config fails

Cause:

• data/ is not writable by PHP

Check:

• directory permissions
• file ownership
• hosting PHP user

PHP errors about missing src/bootstrap.php

Cause:

• src/ was uploaded into the wrong place

Fix:

• place src/ next to public_html/, not inside it

API works locally but not on shared hosting

Check:

• PHP version
• whether Authorization headers are forwarded by the host
• whether HTTPS is used

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:

• the Swagger UI page loads its assets from cdn.jsdelivr.net

Fix:

• allow outbound access to the CDN
• or replace the hosted Swagger assets with local files later

Recommended Go-Live Checklist

• 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
• test one real API reading
• verify alerts before production use