# Photobooth Operations Playbook

Use this checklist when bringing Photobooth FTP online for a tenant or debugging ingest issues.

## 1. Provisioning Flow

1. **SuperAdmin config** – set defaults in Filament → Platform Management → Photobooth Settings.
2. **Tenant enablement** – Event Admin opens the event → Fotobox-Uploads → “Photobooth aktivieren”.
3. Laravel generates credentials and calls the control service (`POST /users`).
4. vsftpd accepts uploads at `ftp://username:password@HOST:PORT/`.
5. `photobooth:ingest` copies files into the hot storage disk and applies moderation/security pipelines.

## 2. Troubleshooting

| Symptom | Action |
|---------|--------|
| Tenant’s Photobooth page shows “Deaktiviert” immediately | Check `storage/logs/laravel.log` for control-service errors; re-run `photobooth:ingest --event=ID -vv`. |
| Files remain under `/storage/app/photobooth/<tenant>/<event>` | Ensure scheduler (Horizon/cron) runs `photobooth:ingest`; run manual command to force ingestion. |
| Photos missing from guest “Fotobox” tab | Confirm `photos.ingest_source = photobooth` and that `/api/v1/events/{token}/photos?filter=photobooth` returns data. |
| Rate-limit complaints | Inspect control service logs; adjust `PHOTOBOOTH_RATE_LIMIT_PER_MINUTE` and re-save settings (fires `/config`). |
| Credentials leaked/compromised | Click “Zugang neu generieren” in Event Admin; optional `php artisan photobooth:cleanup-expired --event=ID` to force deletion before expiry. |

## 3. Command Reference

```bash
# Manually ingest pending files for a single event
php artisan photobooth:ingest --event=123 --max-files=100

# Check ingest for all active events (dry run)
php artisan photobooth:ingest --max-files=10

# Remove expired accounts (safe to run ad hoc)
php artisan photobooth:cleanup-expired
```

## 4. Pre-flight Checklist for New Deployments

1. `php artisan migrate`
2. Configure `.env` Photobooth variables.
3. Mount shared Photobooth volume in all containers (FTP + Laravel).
4. Verify `MediaStorageTarget` records exist (hot target pointing at the hot disk).
5. Seed baseline emotions (Photobooth ingest assigns `emotion_id` from existing rows).
6. Confirm scheduler runs (Horizon supervisor or system cron).

## 5. Incident Response

1. **Identify scope** – which events/tenants are affected? Check ingestion logs for specific usernames/path.
2. **Quarantine** – disable the Photobooth toggle for impacted events via Admin UI.
3. **Remediate** – fix FTP/control issues, rotate credentials, run `photobooth:ingest`.
4. **Audit** – review `photobooth_metadata` on events and `photos.ingest_source`.
5. **Communicate** – notify tenant admins via in-app message or email template referencing incident ID.

Keep this playbook updated whenever infra/process changes. PRs to `/docs/photobooth_ftp` welcome.