# Deployment-Anleitung (Debian 12) – plate-ai-api

Getestet fuer: Debian 12, x86_64, 4 vCPU, 15 GB RAM, **ohne GPU** (CPU-Betrieb).

---

## 1. Systempakete

```bash
sudo apt update
sudo apt install -y python3 python3-venv python3-dev build-essential \
    nginx postgresql redis-server git \
    libgl1 libglib2.0-0            # Laufzeit-Libs fuer opencv-headless
```

> `python3.11-venv` ist zwingend fuer virtuelle Umgebungen. Fehlt es, schlaegt
> `python3 -m venv` fehl.

## 2. Projekt ablegen + venv

```bash
sudo mkdir -p /opt/plate-ai-api
sudo chown "$USER" /opt/plate-ai-api
# Projektdateien nach /opt/plate-ai-api kopieren (rsync/git)
cd /opt/plate-ai-api

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip wheel
pip install -r requirements.txt          # Kern (API laeuft bereits)
pip install -r requirements-ml.txt       # ML (Detection + OCR), ~1-2 GB
```

## 3. Konfiguration

```bash
cp .env.example .env
python -c "import secrets; print(secrets.token_urlsafe(48))"   # -> SECRET_KEY
python -c "import secrets; print(secrets.token_urlsafe(32))"   # -> ADMIN_TOKEN
nano .env    # SECRET_KEY, ADMIN_TOKEN, DATABASE_URL, REDIS_URL setzen
```

## 4. Datenbank (PostgreSQL)

```bash
sudo -u postgres psql <<'SQL'
CREATE USER plateai WITH PASSWORD 'STARKES_PASSWORT';
CREATE DATABASE plate_ai OWNER plateai;
SQL
# DATABASE_URL in .env:
#   postgresql+psycopg://plateai:STARKES_PASSWORT@localhost:5432/plate_ai
```

(Alternativ MariaDB: `DATABASE_URL=mysql+pymysql://user:pass@localhost/plate_ai`.)

## 5. Schema + Regionen laden

```bash
source .venv/bin/activate
python scripts/init_db.py --demo        # Tabellen + Demo-Client (gibt API-Key aus!)
python scripts/import_regions.py        # DE-Zulassungsbezirke in die DB spiegeln
```

> Fuer produktive Schema-Aenderungen langfristig **Alembic** einfuehren.

## 6. Modelle bereitstellen

Ins Verzeichnis `data/models/` legen (Pfade in `.env`):

- `yolov8n.onnx` – Fahrzeug-Detektion (COCO). Export:
  `yolo export model=yolov8n.pt format=onnx opset=12`
- `plate_yolov8n.onnx` – feingetunter Kennzeichen-Detektor (eigenes Training, s. README Phase 10).
- optional `vehicle_make.onnx` (+ `vehicle_make.onnx.labels.json`) – Marke/Modell.

Ohne Modelle laeuft die API im **degraded mode** (deterministische Teile aktiv,
`/health` meldet `"mode":"degraded"`).

## 7. Als Dienst betreiben (systemd)

```bash
sudo cp deploy/plate-ai-api.service /etc/systemd/system/
sudo nano /etc/systemd/system/plate-ai-api.service   # User/WorkingDirectory pruefen
sudo systemctl daemon-reload
sudo systemctl enable --now plate-ai-api
systemctl status plate-ai-api
journalctl -u plate-ai-api -f          # Logs (JSON)
```

## 8. Nginx + SSL

```bash
sudo cp deploy/nginx.conf /etc/nginx/sites-available/plate-ai-api
sudo ln -s /etc/nginx/sites-available/plate-ai-api /etc/nginx/sites-enabled/
# optional Netz-Ratelimit: in /etc/nginx/nginx.conf im http{}-Block ergaenzen:
#   limit_req_zone $binary_remote_addr zone=plateai:10m rate=10r/s;
sudo nginx -t && sudo systemctl reload nginx

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d api.deine-domain.de
```

## 9. Logrotation / Backup / Monitoring

- **Logs:** journald rotiert automatisch – `sudo journalctl --vacuum-time=30d`.
  (Datei-Logging optional via `deploy/logrotate.conf`.)
- **Backup:** taeglicher DB-Dump:
  ```bash
  pg_dump -U plateai plate_ai | gzip > /var/backups/plate_ai_$(date +\%F).sql.gz
  ```
  als Cron `0 3 * * *`. Bilder werden nicht gespeichert -> nichts weiter zu sichern.
- **Monitoring:** `GET /api/v1/health` in Uptime-Kuma/Statuscake; App-Fehler in
  Tabelle `error_logs` und via `GET /api/v1/admin/errors`.

## 10. Sicherheitsmassnahmen (Checkliste)

- [ ] `SECRET_KEY` und `ADMIN_TOKEN` gesetzt, nicht Default (`/health`-Warnung beachten).
- [ ] `.env` nur fuer den Dienst-User lesbar (`chmod 600 .env`).
- [ ] Firewall: nur 80/443 offen; App-Port 8080 nur lokal (127.0.0.1).
- [ ] TLS erzwungen (HTTP->HTTPS-Redirect via certbot).
- [ ] `STORE_IMAGES=false` (DSGVO – Bilder nicht persistieren).
- [ ] Postgres/Redis nur an localhost gebunden.
- [ ] Regelmaessige `apt upgrade` + `pip` Security-Updates.

## Schnelltest nach Deployment

```bash
curl -s https://api.deine-domain.de/api/v1/health | jq
curl -s -H "X-API-Key: <DEIN_KEY>" \
     -F "file=@/pfad/zum/auto.jpg" \
     https://api.deine-domain.de/api/v1/recognize | jq
```