# Installation – barox Switch Test Companion (Ubuntu)

Diese Anleitung beschreibt die Produktivinstallation auf Ubuntu Server
(22.04 / 24.04) mit Apache, PHP und MySQL/MariaDB.

---

## 1. Benötigte Pakete

```bash
sudo apt update
sudo apt install -y apache2 \
  php php-cli php-fpm php-mysql php-mbstring php-zip php-curl php-xml \
  php-snmp mariadb-server unzip git

# Composer (für die native PDF-Erzeugung via dompdf)
sudo apt install -y composer
```

Benötigte PHP-Erweiterungen: `pdo_mysql`, `mbstring`, `zip`, `curl`, `xml`
(SimpleXML), optional `snmp` (SNMP-Prototyp).

Optional für die **Automatisierung** (Server → Switch):

```bash
sudo apt install -y php-snmp                 # SNMP-System-Info
sudo apt install -y openssh-client sshpass   # SSH-Command-Runner (Passwort-Login)
# Alternativ statt openssh-client/sshpass: die PHP-Erweiterung php-ssh2
# sudo apt install -y php-ssh2
sudo apt install -y poppler-utils            # PDF-Textextraktion (KI-Dokumentimport)
```

Der SSH-Command-Runner nutzt bevorzugt `php-ssh2`; ist diese Erweiterung nicht
vorhanden, greift der System-`ssh`-Client (Passwort-Login via `sshpass`).

Apache-Module aktivieren:

```bash
sudo a2enmod rewrite headers
```

---

## 2. Quellcode ablegen

```bash
sudo mkdir -p /var/www/switchtest
sudo chown -R "$USER":www-data /var/www/switchtest
# Projektdateien nach /var/www/switchtest kopieren (git clone / rsync / scp)
cd /var/www/switchtest
```

Optional (empfohlen) – dompdf installieren:

```bash
composer install --no-dev --optimize-autoloader
```

> Ohne dompdf funktioniert alles; der Report wird dann als druckoptimierte
> HTML-Seite ausgeliefert (Browser → „Als PDF speichern“). Setzen Sie in diesem
> Fall `PDF_ENGINE=browser` in der `.env`.

---

## 3. Datenbank anlegen

```bash
sudo mysql <<'SQL'
CREATE DATABASE barox_switchtest CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'barox_switchtest'@'localhost' IDENTIFIED BY 'HIER_SICHERES_PASSWORT';
GRANT ALL PRIVILEGES ON barox_switchtest.* TO 'barox_switchtest'@'localhost';
FLUSH PRIVILEGES;
SQL
```

---

## 4. `.env` konfigurieren

```bash
cp .env.example .env
php scripts/genkey.php    # Ausgabe kopieren
nano .env
```

Mindestens setzen:

```dotenv
APP_URL=https://switchtest.barox.local
APP_ENV=production
APP_DEBUG=false
APP_KEY=<Ausgabe von genkey.php>

DB_HOST=127.0.0.1
DB_NAME=barox_switchtest
DB_USER=barox_switchtest
DB_PASS=HIER_SICHERES_PASSWORT

AUTH_MODE=both            # oder local / ms365
PDF_ENGINE=dompdf         # oder browser (ohne Composer)
```

Für **Microsoft 365** zusätzlich `MS365_ENABLED=true`, `MS365_TENANT_ID`,
`MS365_CLIENT_ID`, `MS365_CLIENT_SECRET`, `MS365_REDIRECT_URI` (muss exakt der
in Entra ID registrierten Redirect-URI entsprechen, z. B.
`https://switchtest.barox.local/auth/ms365/callback`) und optional
`MS365_ALLOWED_DOMAIN=barox.ch`.

---

## 5. Migrationen ausführen & Daten importieren

```bash
php scripts/migrate.php          # Schema
php scripts/seed.php             # Rollen, Einstellungen, Excel-Import
# alternativ nur der Import einer bestimmten Datei:
php scripts/import_excel.php docs/Switch_Test_Checkliste.xlsx
```

Admin-Benutzer anlegen:

```bash
php scripts/create_admin.php "Vorname Nachname" admin@barox.ch "SicheresPasswort10+"
```

Optionale Beispieldaten:

```bash
php scripts/seed.php --demo
```

---

## 6. Storage-Rechte setzen

Der Webserver (`www-data`) muss in `storage/` schreiben können; der Code selbst
soll dem Deployment-Benutzer gehören.

```bash
cd /var/www/switchtest
sudo chown -R "$USER":www-data storage
sudo find storage -type d -exec chmod 2775 {} \;   # setgid: neue Dateien erben Gruppe
sudo find storage -type f -exec chmod 0664 {} \;

# Übriger Code: nur lesbar für www-data
sudo chown -R "$USER":www-data /var/www/switchtest
sudo find /var/www/switchtest -type d -exec chmod 0755 {} \;
sudo find /var/www/switchtest -type f -exec chmod 0644 {} \;
sudo chmod 0640 .env                                # Secrets nicht world-readable
```

Erklärung: `storage/` (Uploads, Reports, Logs) benötigt Schreibrechte für
`www-data`. Das `setgid`-Bit (2775) sorgt dafür, dass neu erstellte Unterordner
die Gruppe `www-data` erben. Die `.env` sollte `0640` (Eigentümer + Gruppe) haben.

---

## 7. Apache Virtual Host

Der **DocumentRoot ist `public/`**. Statische Assets liegen projektweit unter
`/assets` (außerhalb von `public/`) und werden per `Alias` eingebunden.

`/etc/apache2/sites-available/switchtest.conf`:

```apache
<VirtualHost *:80>
    ServerName switchtest.barox.local
    DocumentRoot /var/www/switchtest/public

    Alias /assets /var/www/switchtest/assets
    <Directory /var/www/switchtest/assets>
        Require all granted
        Options -Indexes
    </Directory>

    <Directory /var/www/switchtest/public>
        AllowOverride All
        Require all granted
        Options -Indexes
    </Directory>

    # Storage niemals direkt ausliefern
    <Directory /var/www/switchtest/storage>
        Require all denied
    </Directory>

    ErrorLog  ${APACHE_LOG_DIR}/switchtest_error.log
    CustomLog ${APACHE_LOG_DIR}/switchtest_access.log combined
</VirtualHost>
```

Aktivieren:

```bash
sudo a2ensite switchtest
sudo a2dissite 000-default
sudo systemctl reload apache2
```

---

## 8. HTTPS (Produktivbetrieb – Pflicht)

Zugangsdaten und Session-Cookies dürfen nur über TLS übertragen werden.
Mit Let's Encrypt:

```bash
sudo apt install -y certbot python3-certbot-apache
sudo certbot --apache -d switchtest.barox.local
```

Certbot ergänzt den `:443`-VirtualHost. Übernehmen Sie dort **denselben**
`Alias /assets …`-Block. Empfohlen zusätzlich HSTS (im `:443`-Host):

```apache
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
```

---

## 9. PDF-Export testen

1. Anmelden, unter **Neuer Testlauf** einen Testlauf anlegen.
2. Im Assistenten einige Testfälle bewerten.
3. **Report-Vorschau → PDF erzeugen** aufrufen.

- Mit `PDF_ENGINE=dompdf` (Composer installiert) wird ein PDF ausgeliefert und
  unter `storage/test-runs/<id>/reports/` versioniert abgelegt.
- Mit `PDF_ENGINE=browser` erscheint eine druckoptimierte HTML-Seite.

Prüfen, dass Reports gespeichert werden:

```bash
ls -R storage/test-runs
```

---

## 10. Upload-Größe

`UPLOAD_MAX_MB` in der `.env` begrenzt die App-seitige Prüfung. Passen Sie die
PHP-Limits entsprechend an (`/etc/php/*/apache2/php.ini` bzw. FPM-Pool):

```ini
upload_max_filesize = 64M
post_max_size = 72M
```

Danach `sudo systemctl reload apache2` (bzw. `php*-fpm` neu laden).

---

## Fehlerbehebung

| Symptom | Ursache / Lösung |
|--------|-------------------|
| 500-Fehler, weiße Seite | `storage/logs/app.log` prüfen; `APP_DEBUG=true` temporär setzen |
| „Datenbankverbindung fehlgeschlagen“ | DB-Zugang in `.env`, MySQL läuft, User-Rechte |
| Assets laden nicht (kein Styling) | `Alias /assets`-Block im aktiven VHost prüfen; `mod_rewrite`/`headers` aktiv |
| Uploads scheitern | Rechte auf `storage/` (Schritt 6) und PHP-Limits (Schritt 10) |
| PDF kommt als HTML | dompdf nicht installiert → `composer install` oder `PDF_ENGINE=browser` |
| SNMP-Prototyp meldet „Erweiterung nicht installiert“ | `sudo apt install php-snmp` und Apache/FPM neu laden |