# Coolify Deployment Guide

Coolify provides a managed Docker host with service orchestration, logs, metrics, CI hooks, and secret management. This document outlines how to run Fotospiel (including the Photobooth FTP stack) on Coolify and how to prepare for SuperAdmin observability.

## 1. Services to deploy

| Service | Notes |
|---------|-------|
| **Laravel App** | Build from this repo. Expose port 8080. Attach environment variables from `.env`. |
| **Scheduler** | Clone the app container; command `php artisan schedule:work`. |
| **Queue workers** | Use `docs/queue-supervisor/queue-worker.sh` scripts (default, media-storage, media-security). |
| **Horizon (optional)** | Add service executing `docs/queue-supervisor/horizon.sh`. |
| **Redis / Database** | Use Coolify managed services or bring your own (RDS/Aurora). |
| **vsftpd container** | Host FTP on port 2121 and mount the shared Photobooth volume. |
| **Photobooth Control Service** | Lightweight API (Go/Node/Laravel Octane) that Coolify can redeploy alongside vsftpd. |

### Volumes

- `storage-app` (Laravel `storage`, uploads, compiled views).
- `photobooth` (shared between vsftpd, control-service, and Laravel).
- Database/Redis volumes if self-hosted.

Mount these volumes in Coolify under “Persistent Storage” for each service.

## 2. Environment & Secrets

Configure the following keys inside Coolify’s “Environment Variables” panel:

- All standard Laravel vars (`APP_KEY`, `DB_*`, `QUEUE_CONNECTION`, `AWS_*` etc.).
- Photobooth block (as documented in `.env.example`): `PHOTOBOOTH_CONTROL_*`, `PHOTOBOOTH_FTP_HOST/PORT`, `PHOTOBOOTH_IMPORT_*`.
- New Coolify integration vars (planned for SuperAdmin widgets):

```
COOLIFY_API_BASE_URL=https://coolify.example.com/api/v1
COOLIFY_API_TOKEN=...   # generated per project
COOLIFY_SERVICE_IDS={"app":"svc_xxx","ftp":"svc_yyy"}
```

Store the JSON mapping so Laravel knows which Coolify “service” controls the app, queue, vsftpd, etc.

## 3. Deploy steps

1. Add the Git repository to Coolify (build hook). Configure the Dockerfile build args if needed.
2. Define services:
   - **App**: HTTP worker (build & run). Health check `/up`.
   - **Scheduler**: same image, command `php artisan schedule:work`.
   - **Queue**: command `/var/www/html/docs/queue-supervisor/queue-worker.sh default`.
   - Additional queue types as separate services.
3. Configure networks so all services share the same internal bridge, allowing Redis/DB connectivity.
4. Attach the `photobooth` volume to both vsftpd and the Laravel app.
5. Run `php artisan migrate --force` from Coolify’s “One-off command” console after the first deploy.
6. Seed storage targets if necessary (`php artisan db:seed --class=MediaStorageTargetSeeder --force`).

## 4. Metrics & Controls for SuperAdmin

To surface Coolify data inside the platform:

1. **API Token** – create a Coolify PAT with read access to services and optional “actions” scope.
2. **Laravel config** – introduce `config/coolify.php` with base URL, token, and service IDs.
3. **Service client** – wrap Coolify endpoints:
   - `GET /services/{id}` → CPU/RAM, status, last deploy, git SHA.
   - `POST /services/{id}/actions/restart` for restart buttons.
   - `GET /deployments/{id}/logs` for tailing last deploy logs.
4. **Filament widgets** – in SuperAdmin dashboard add:
   - **Platform Health**: per service status (App, Queue, Scheduler, vsftpd, Control Service).
   - **Recent Deploys**: table of the last Coolify deployments and commit messages.
   - **Actions**: buttons (with confirmations) to restart vsftpd or re-run `photobooth:ingest` service.

Ensure all requests are audited (database table) and require SuperAdmin role.

## 5. FTP container controls

Coolify makes it easier to:

- View vsftpd metrics (CPU, memory, network) directly; replicate those values in SuperAdmin via the API.
- Trigger redeploys of the vsftpd service when Photobooth settings change (Laravel can call Coolify’s redeploy endpoint).
- Inspect container logs from SuperAdmin by proxying `GET /services/{id}/logs?tail=200`.

## 6. Monitoring & Alerts

- Configure Coolify Webhooks (Deploy succeeded/failed, service unhealthy) → point to a Laravel route, mark incidents in `photobooth_metadata`.
- Use Coolify’s built-in notifications (Slack, email) for infrastructure-level alerts; complement with Laravel notifications for application-level events (e.g., ingest failures).

## 7. Production readiness checklist

1. All services built and running in Coolify with health checks.
2. Volumes backed up (database snapshots + `storage` tarball).
3. Photobooth shared volume mounted & writeable by vsftpd + Laravel.
4. Environment variables set (APP_KEY, DB creds, Photobooth block, Coolify API token).
5. Scheduler & queue services logging to Coolify.
6. SuperAdmin Filament widgets wired to Coolify API (optional but recommended).

With this setup you can manage deployments, restarts, and metrics centrally while still using Laravel’s built-in scheduler and worker scripts. The next step is implementing the `CoolifyClient` + Filament widgets described above.
