fotospiel-app/docs/ops/photobooth/ops_playbook.md

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

# 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/ops/photobooth welcome.