feuerwehr-getraenkeautomat-status/docs/DEPLOYMENT.md

Deployment Guide

Diese Anwendung ist jetzt für klassisches Apache-Shared-Hosting als einzelner App-Ordner vorbereitet.

Zielbild:

• du lädst genau einen Ordner auf den Webspace hoch
• dieser Ordner liegt direkt im öffentlichen Webspace, z. B. unter public_html/monitor/
• die App ist dann unter https://example.com/monitor/ erreichbar
• die API liegt automatisch unter https://example.com/monitor/api/v1/
• src/, data/ und die Markdown-Doku bleiben im selben Ordner, sind aber per .htaccess gesperrt

Voraussetzungen

Erforderlich:

• Apache-Webhosting mit aktiviertem .htaccess-Support
• PHP 8.1 oder neuer empfohlen
• PHP-Sessions aktiviert
• Schreibrechte für PHP auf data/

Optional:

• funktionierende mail()-Konfiguration für Email-Alarme
• ausgehende HTTPS-Verbindungen für Webhooks
• Zugriff auf cdn.jsdelivr.net für die Swagger UI unter /api-docs/

Deploy-Modell

Die Anwendung wird nicht mehr in public/ und private Nachbarordner getrennt deployt. Stattdessen ist der Projektordner selbst das Deploy-Artefakt.

Beispiel für eine Installation in einem Unterordner:

/home/account/public_html/
└── monitor/
    ├── .htaccess
    ├── index.php
    ├── app.js
    ├── styles.css
    ├── openapi.yaml
    ├── admin/
    ├── api/
    ├── api-docs/
    ├── data/
    │   ├── .htaccess
    │   ├── config.json
    │   ├── state.json
    │   ├── alert_log.json
    │   └── php_errors.log
    ├── docs/
    │   ├── .htaccess
    │   ├── API.md
    │   ├── CONFIG.md
    │   └── DEPLOYMENT.md
    └── src/
        └── .htaccess

Wichtig:

• index.php, admin/, api/, api-docs/, app.js, styles.css und openapi.yaml sind öffentlich
• src/, data/ und docs/ liegen im selben Ordner, werden aber durch mitgelieferte .htaccess-Dateien blockiert
• README.md und Dotfiles werden ebenfalls über die Root-.htaccess geblockt

Empfohlene URL-Struktur

Wenn du den Ordner monitor/ in public_html/ hochlädst, setze in data/config.json oder im Adminpanel:

{
  "app": {
    "base_path": "/monitor"
  }
}

Dann sind die wichtigsten URLs:

• Dashboard: https://example.com/monitor/
• Adminpanel: https://example.com/monitor/admin/
• Status-API: https://example.com/monitor/api/v1/status.php
• Readings-API: https://example.com/monitor/api/v1/readings.php
• Swagger UI: https://example.com/monitor/api-docs/
• OpenAPI-Spec: https://example.com/monitor/openapi.yaml

Wenn du den Inhalt direkt in den Domain-Root legst, bleibt base_path leer.

Upload

1. Projektordner vorbereiten

Du brauchst für das Hosting den kompletten Projektordner inklusive:

• Runtime-Dateien im Root
• admin/
• api/
• api-docs/
• src/
• data/
• docs/
• .htaccess

2. Ordner hochladen

Lade den kompletten Ordner in den öffentlichen Webspace hoch, zum Beispiel:

lokal:  /mein-projekt/automat
server: /home/account/public_html/monitor

Danach muss Apache aus genau diesem Ordner ausliefern.

3. Schreibrechte setzen

PHP muss in data/ schreiben können.

Typische Werte:

• Verzeichnisse: 755 oder 775
• Dateien: 644 oder 664

Beschreibbar sein müssen mindestens:

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

Empfohlen zusätzlich:

• data/php_errors.log (wird beim ersten geloggten Fehler angelegt)

4. PHP-Version einstellen

Im Hosting-Panel PHP 8.1 oder neuer aktivieren.

5. Basis-Pfad setzen

Falls die App in einem Unterordner wie monitor/ liegt:

• app.base_path auf "/monitor" setzen

Falls die App direkt unter der Domain liegt:

• app.base_path leer lassen

Das Feld wird im Adminpanel normalisiert. monitor, /monitor und /monitor/ werden zu "/monitor".

6. Default-Zugangsdaten ersetzen

Nach dem ersten Login sofort ändern:

• Admin-Benutzername
• Admin-Passwort
• API-Bearer-Token

Apache-Schutz

Die Bereitstellung setzt auf die mitgelieferten .htaccess-Dateien:

• Root .htaccess
  • verhindert Directory Listing
  • blockiert Dotfiles
  • blockiert README.md
• src/.htaccess
  • blockiert den Quellcode
• data/.htaccess
  • blockiert JSON-Daten und Zugangsdaten
• docs/.htaccess
  • blockiert die internen Markdown-Dateien

Wenn dein Hosting .htaccess ignoriert, ist dieses Deploy-Modell nicht sicher.

Sensor-Clients

Sensoren senden an den Readings-Endpunkt relativ zum base_path.

Beispiel für eine Installation unter /monitor:

POST https://example.com/monitor/api/v1/readings.php
Authorization: Bearer <token>
Content-Type: application/json

Verifikation nach dem Upload

Diese Checks sollten direkt funktionieren:

1. https://example.com/monitor/ zeigt das Dashboard.
2. https://example.com/monitor/admin/ zeigt den Login.
3. https://example.com/monitor/api/v1/status.php liefert JSON.
4. https://example.com/monitor/api-docs/ zeigt Swagger UI.
5. https://example.com/monitor/openapi.yaml ist abrufbar.

Diese Pfade dürfen nicht öffentlich lesbar sein:

1. https://example.com/monitor/data/config.json
2. https://example.com/monitor/src/bootstrap.php
3. https://example.com/monitor/docs/DEPLOYMENT.md

Sie sollten 403 Forbidden oder ähnlich blockiert werden.

Lokale Entwicklung

Lokal kannst du die App direkt aus dem Projektordner starten:

php -S localhost:8000

Wichtig:

• der PHP Built-in Server wertet .htaccess nicht aus
• der Schutz von src/, data/ und docs/ gilt deshalb lokal nicht
• für den Live-Betrieb ist Apache entscheidend

Fehlerbehebung

403 oder 404 auf allen App-URLs

Prüfen:

• liegt der App-Ordner wirklich im öffentlichen Webspace
• liefert Apache aus diesem Ordner aus
• ist die PHP-Version für diesen Ordner aktiv

Dashboard lädt, aber CSS oder JS fehlt

Prüfen:

• app.base_path stimmt exakt mit dem URL-Unterordner überein
• app.js und styles.css liegen im Root des App-Ordners

PHP-Fehler finden

PHP-Laufzeitfehler werden in data/php_errors.log geschrieben. Wenn etwas serverseitig fehlschlägt, zuerst diese Datei prüfen.

API funktioniert nicht unter dem Unterordner

Prüfen:

• app.base_path ist z. B. "/monitor"
• der Sensor postet an /monitor/api/v1/readings.php
• das Bearer-Token stimmt

data/config.json ist im Browser erreichbar

Dann greift .htaccess nicht korrekt. In dem Fall:

• Hosting-Konfiguration für .htaccess prüfen
• AllowOverride bzw. das entsprechende Hosting-Feature aktivieren
• die App nicht produktiv betreiben, bis der Zugriff blockiert ist