fotospiel-app/docs/deployment/coolify.md

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.