# Deployment Guide

Diese Anwendung ist jetzt fuer klassisches Apache-Shared-Hosting als einzelner App-Ordner vorbereitet.

Zielbild:

- du laedst genau einen Ordner auf den Webspace hoch
- dieser Ordner liegt direkt im oeffentlichen 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 fuer PHP auf `data/`

Optional:

- funktionierende `mail()`-Konfiguration fuer Email-Alarme
- ausgehende HTTPS-Verbindungen fuer Webhooks
- Zugriff auf `cdn.jsdelivr.net` fuer 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 fuer eine Installation in einem Unterordner:

```text
/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
    ├── 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 oeffentlich
- `src/`, `data/` und `docs/` liegen im selben Ordner, werden aber durch mitgelieferte `.htaccess`-Dateien blockiert
- `README.md` und Dotfiles werden ebenfalls ueber die Root-`.htaccess` geblockt

## Empfohlene URL-Struktur

Wenn du den Ordner `monitor/` in `public_html/` hochlaedst, setze in `data/config.json` oder im Adminpanel:

```json
{
  "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 fuer 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 oeffentlichen Webspace hoch, zum Beispiel:

```text
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 koennen.

Typische Werte:

- Verzeichnisse: `755` oder `775`
- Dateien: `644` oder `664`

Beschreibbar sein muessen mindestens:

- `data/config.json`
- `data/state.json`
- `data/alert_log.json`

### 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 aendern:

- 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 fuer eine Installation unter `/monitor`:

```text
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 duerfen nicht oeffentlich 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 aehnlich blockiert werden.

## Lokale Entwicklung

Lokal kannst du die App direkt aus dem Projektordner starten:

```bash
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
- fuer den Live-Betrieb ist Apache entscheidend

## Fehlerbehebung

### `403` oder `404` auf allen App-URLs

Pruefen:

- liegt der App-Ordner wirklich im oeffentlichen Webspace
- liefert Apache aus diesem Ordner aus
- ist die PHP-Version fuer diesen Ordner aktiv

### Dashboard laedt, aber CSS oder JS fehlt

Pruefen:

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

### API funktioniert nicht unter dem Unterordner

Pruefen:

- `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 fuer `.htaccess` pruefen
- `AllowOverride` bzw. das entsprechende Hosting-Feature aktivieren
- die App nicht produktiv betreiben, bis der Zugriff blockiert ist