148 lines
6.3 KiB
Markdown
148 lines
6.3 KiB
Markdown
# Photobooth FTP Ingestion
|
||
|
||
This guide explains how to operate the Photobooth FTP workflow end‑to‑end: provisioning FTP users for tenants, running the ingest pipeline, and exposing photobooth photos inside the Guest PWA.
|
||
|
||
## Architecture Overview
|
||
|
||
1. **vsftpd container** (port `2121`) accepts uploads into a shared volume (default `/var/www/storage/app/photobooth`). Each event receives isolated credentials and a dedicated directory.
|
||
2. **Control Service** (REST) provisions FTP accounts. Laravel calls it during enable/rotate/disable actions.
|
||
3. **Photobooth settings** (Filament SuperAdmin) define global port, rate limit, expiry grace, and Control Service connection.
|
||
4. **Ingest command** copies uploaded files into the event’s storage disk, generates thumbnails, records `photos.ingest_source = photobooth`, and respects package quotas.
|
||
5. **Guest PWA filter** consumes `/api/v1/events/{token}/photos?filter=photobooth` to render the “Fotobox” tab. Sparkbooth uploads reuse this filter via `ingest_source = sparkbooth`.
|
||
|
||
```
|
||
Photobooth -> FTP (vsftpd) -> photobooth disk
|
||
photobooth:ingest (queue/scheduler)
|
||
-> Event media storage (public disk/S3)
|
||
-> packages_usage, thumbnails, security scan
|
||
|
||
Sparkbooth -> HTTP upload endpoint -> ingest (direct, no staging disk)
|
||
```
|
||
|
||
## Environment Variables
|
||
|
||
Add the following to `.env` (already scaffolded in `.env.example`):
|
||
|
||
```env
|
||
PHOTOBOOTH_CONTROL_BASE_URL=https://control.internal/api
|
||
PHOTOBOOTH_CONTROL_TOKEN=your-control-token
|
||
PHOTOBOOTH_CONTROL_TIMEOUT=5
|
||
|
||
PHOTOBOOTH_FTP_HOST=ftp.internal
|
||
PHOTOBOOTH_FTP_PORT=2121
|
||
|
||
PHOTOBOOTH_USERNAME_PREFIX=pb
|
||
PHOTOBOOTH_USERNAME_LENGTH=8
|
||
PHOTOBOOTH_PASSWORD_LENGTH=8
|
||
|
||
PHOTOBOOTH_RATE_LIMIT_PER_MINUTE=20
|
||
PHOTOBOOTH_EXPIRY_GRACE_DAYS=1
|
||
|
||
PHOTOBOOTH_IMPORT_DISK=photobooth
|
||
PHOTOBOOTH_IMPORT_ROOT=/var/www/storage/app/photobooth
|
||
PHOTOBOOTH_IMPORT_MAX_FILES=50
|
||
PHOTOBOOTH_ALLOWED_EXTENSIONS=jpg,jpeg,png,webp
|
||
|
||
# Sparkbooth defaults (optional overrides)
|
||
SPARKBOOTH_ALLOWED_EXTENSIONS=jpg,jpeg,png,webp
|
||
SPARKBOOTH_MAX_SIZE_KB=8192
|
||
SPARKBOOTH_RATE_LIMIT_PER_MINUTE=20
|
||
SPARKBOOTH_RESPONSE_FORMAT=json
|
||
```
|
||
|
||
### Filesystem Disk
|
||
|
||
`config/filesystems.php` registers a `photobooth` disk that must point to the shared volume where vsftpd writes files. Mount the same directory inside both the FTP container and the Laravel app container.
|
||
|
||
## Control Service Contract
|
||
|
||
Laravel expects the Control Service to expose:
|
||
|
||
```
|
||
POST /users { username, password, path, rate_limit_per_minute, expires_at, ftp_port }
|
||
POST /users/{username}/rotate { password, rate_limit_per_minute, expires_at }
|
||
DELETE /users/{username}
|
||
POST /config { ftp_port, rate_limit_per_minute, expiry_grace_days }
|
||
```
|
||
|
||
Authentication is provided via `PHOTOBOOTH_CONTROL_TOKEN` (Bearer token).
|
||
|
||
## Scheduler & Commands
|
||
|
||
| Command | Purpose | Default schedule |
|
||
|---------|---------|------------------|
|
||
| `photobooth:ingest [--event=ID] [--max-files=N]` | Pulls files from the Photobooth disk and imports them into the event storage. | every 5 minutes |
|
||
| `photobooth:cleanup-expired` | De-provisions FTP accounts after their expiry. | hourly |
|
||
|
||
You can run the ingest job manually for a specific event:
|
||
|
||
```bash
|
||
php artisan photobooth:ingest --event=123 --max-files=20
|
||
```
|
||
|
||
## Sparkbooth HTTP Uploads (Custom Upload)
|
||
|
||
Use this when Sparkbooth runs in “Custom Upload” mode instead of FTP.
|
||
|
||
- Endpoint: `POST /api/v1/photobooth/sparkbooth/upload`
|
||
- Auth: per-event username/password (set in Event Admin → Fotobox-Uploads; switch mode to “Sparkbooth”).
|
||
- Body (multipart/form-data): `media` (file or base64), `username`, `password`, optionally `name`, `email`, `message`.
|
||
- Response:
|
||
- JSON success: `{"status":true,"error":null,"url":null}`
|
||
- JSON failure: `{"status":false,"error":"Invalid credentials"}`
|
||
- XML (if `format=xml` or event preference is XML):
|
||
- Success: `<rsp status="ok" url="..."/>`
|
||
- Failure: `<rsp status="fail"><err msg="Invalid credentials" /></rsp>`
|
||
- Limits: allowed extensions reuse photobooth defaults; max size `SPARKBOOTH_MAX_SIZE_KB` (default 8 MB); per-event rate limit `SPARKBOOTH_RATE_LIMIT_PER_MINUTE` (fallback to photobooth rate limit).
|
||
- Ingest: writes straight to the event’s hot storage, applies thumbnail/watermark/security scan, sets `photos.ingest_source = sparkbooth`.
|
||
|
||
Example cURL (JSON response):
|
||
|
||
```bash
|
||
curl -X POST https://app.example.com/api/v1/photobooth/sparkbooth/upload \
|
||
-F "media=@/path/to/photo.jpg" \
|
||
-F "username=PB123" \
|
||
-F "password=SECRET" \
|
||
-F "message=Wedding booth"
|
||
```
|
||
|
||
Example cURL (request XML response):
|
||
|
||
```bash
|
||
curl -X POST https://app.example.com/api/v1/photobooth/sparkbooth/upload \
|
||
-F "media=@/path/to/photo.jpg" \
|
||
-F "username=PB123" \
|
||
-F "password=SECRET" \
|
||
-F "format=xml"
|
||
```
|
||
|
||
## Tenant Admin UX
|
||
|
||
Inside the Event Admin PWA, go to **Event → Fotobox-Uploads** to:
|
||
|
||
1. Enable/disable the Photobooth link.
|
||
2. Rotate credentials (max 10-char usernames, 8-char passwords).
|
||
3. Switch mode (FTP or Sparkbooth), view rate limit + expiry info, copy ftp:// or POST URL + creds.
|
||
|
||
## Guest PWA Filter
|
||
|
||
The Guest gallery now exposes a “Fotobox” tab (both preview card and full gallery). API usage:
|
||
|
||
```
|
||
GET /api/v1/events/{token}/photos?filter=photobooth
|
||
Headers: X-Device-Id (optional)
|
||
```
|
||
|
||
Response items contain `ingest_source`, allowing the frontend to toggle photobooth-only views.
|
||
|
||
## Operational Checklist
|
||
|
||
1. **Set env vars** from above and restart the app.
|
||
2. **Ensure vsftpd + Control Service** are deployed; verify port 2121 and REST endpoint connectivity.
|
||
3. **Mount shared volume** to `/var/www/storage/app/photobooth` (or update `PHOTOBOOTH_IMPORT_ROOT` + `filesystems.disks.photobooth.root`).
|
||
4. **Run migrations** (`php artisan migrate`) to create settings/event columns.
|
||
5. **Seed default storage target** (e.g., `MediaStorageTarget::create([... 'key' => 'public', ...])`) in non-test environments if not present.
|
||
6. **Verify scheduler** (Horizon or cron) is running commands `photobooth:ingest` and `photobooth:cleanup-expired`.
|
||
7. **Test end-to-end**: enable Photobooth on a staging event, upload a file via FTP, wait for ingest, and confirm it appears under the Fotobox filter in the PWA.
|
||
8. **Test Sparkbooth**: switch event mode to Sparkbooth, copy Upload URL/user/pass, send a sample POST (or real Sparkbooth upload), verify it appears under the Fotobox filter.
|