# Dokploy Deployment Guide

Dokploy is our self-hosted PaaS for orchestrating the Fotospiel stack (Laravel app, scheduler, queue workers, Horizon, and the Photobooth FTP pipeline). This guide explains how to provision the services in Dokploy and how to wire the SuperAdmin observability widgets that now talk to the Dokploy API.

## 1. Services to provision

| Service | Notes |
|---------|-------|
| **Laravel App** | Build from this repository. Expose port 8080 (or Dokploy HTTP service). Attach the production `.env`. Health check `/up`. |
| **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). Deploy each as a dedicated Dokploy application or Docker service. |
| **Horizon (optional)** | Run `docs/queue-supervisor/horizon.sh` for dashboard + metrics. |
| **Redis / Database** | Use managed offerings or self-host in Dokploy. Configure network access for the app + workers. |
| **vsftpd container** | Expose port 2121 and mount the shared Photobooth volume. |
| **Photobooth Control Service** | Lightweight API (Go/Node/Laravel Octane) that can be redeployed together with vsftpd for ingest controls. |

### Volumes

Create persistent volumes inside Dokploy and mount them across the services:

- `storage-app` – Laravel `storage`, uploads, compiled views.
- `photobooth` – shared by vsftpd, the control service, and Laravel for ingest.
- Database / Redis volumes if you self-manage those containers.

## 2. Environment & secrets

Every Dokploy application should include the regular Laravel secrets (see `.env.example`). Important blocks:

- `APP_KEY`, `APP_URL`, `DB_*`, `CACHE_DRIVER`, `QUEUE_CONNECTION`, `MAIL_*`.
- Photobooth integration (`PHOTOBOOTH_CONTROL_*`, `PHOTOBOOTH_FTP_*`, `PHOTOBOOTH_IMPORT_*`).
- AWS / S3 credentials if the tenant media is stored remotely.

### Dokploy integration variables

Add the infrastructure observability variables to the Laravel app environment:

```
DOKPLOY_API_BASE_URL=https://dokploy.example.com/api
DOKPLOY_API_KEY=pat_xxxxxxxxxxxxxxxxx
DOKPLOY_WEB_URL=https://dokploy.example.com
DOKPLOY_COMPOSE_IDS={"stack":"cmp_main","ftp":"cmp_ftp"}
DOKPLOY_API_TIMEOUT=10
```

- `DOKPLOY_COMPOSE_IDS` ist eine JSON-Map Label → `composeId` (siehe Compose-Detailseite in Dokploy). Diese IDs steuern Widget & Buttons.
- Optional kannst du weiterhin `DOKPLOY_APPLICATION_IDS` pflegen, falls du später einzelne Apps statt Compose-Stacks integrieren möchtest.
- Die API benötigt Rechte für `compose.one`, `compose.loadServices`, `compose.redeploy`, `compose.stop` etc.

## 3. Project & server setup

1. **Register the Docker host** in Dokploy (`Servers → Add Server`). Install the Dokploy agent on the target VM.
2. **Create a Project** (e.g., `fotospiel-prod`) to group all services.
3. **Attach repositories** using Dokploy Git providers (GitHub / Gitea / GitLab / Bitbucket) or Docker images. Fotospiel uses the source build (Dockerfile at repo root).
4. **Networking** – keep all services on the same internal network so they can talk to Redis/DB. Expose the public HTTP service only for the Laravel app (behind Traefik/Let’s Encrypt).

## 4. Deploy applications

Follow these steps for each component:

1. **Laravel HTTP app**
   - Build from the repo.
   - `Dockerfile` already exposes port `8080`.
   - Set branch (e.g. `main`) for automatic deployments.
   - Add health check `/up`.
   - Mount `storage-app` and `photobooth` volumes.

2. **Scheduler**
   - Duplicate the image.
   - Override command: `php artisan schedule:work`.
   - Disable HTTP exposure.

3. **Queue workers**
   - Duplicate the image.
   - Commands:
     - `docs/queue-supervisor/queue-worker.sh default`
     - `docs/queue-supervisor/queue-worker.sh media-storage`
     - `docs/queue-supervisor/queue-worker.sh media-security`
   - Optionally create a dedicated container for Horizon using `docs/queue-supervisor/horizon.sh`.

4. **vsftpd + Photobooth control**
   - Nutze deinen bestehenden Docker-Compose-Stack (z. B. `docker-compose.dokploy.yml`) oder dedizierte Compose-Applikationen.
   - Mount `photobooth` volume read-write.

5. **Database/Redis**
   - Dokploy can provision standard MySQL/Postgres/Redis apps. Configure credentials to match `.env`.

6. **Apply migrations**
   - Use Dokploy one-off command to run `php artisan migrate --force` on first deploy.
   - Seed storage targets if required: `php artisan db:seed --class=MediaStorageTargetSeeder --force`.

## 5. SuperAdmin observability (Dokploy API)

Das SuperAdmin-Dashboard nutzt jetzt ausschließlich Compose-Endpunkte:

1. **Config file** – `config/dokploy.php` liest `DOKPLOY_COMPOSE_IDS`.
2. **Client** – `App\Services\Dokploy\DokployClient` kapselt:
   - `GET /compose.one?composeId=...` für Meta- und Statusinfos (deploying/error/done).
   - `GET /compose.loadServices?composeId=...` für die einzelnen Services innerhalb des Stacks.
   - `GET /deployment.allByCompose?composeId=...` für die Deploy-Historie.
   - `POST /compose.redeploy`, `POST /compose.deploy`, `POST /compose.stop` (Buttons im UI).
3. **Widgets / Pages** – `DokployPlatformHealth` zeigt jeden Compose-Stack inkl. Services; die `DokployDeployments`-Seite bietet Redeploy/Stop + Audit-Log (`InfrastructureActionLog`).
4. **Auditing** – jede Aktion wird mit User, Payload, Response & HTTP-Code in `infrastructure_action_logs` festgehalten.

Only SuperAdmins should have access to these widgets. If you rotate the API key, update the `.env` and deploy the app to refresh the cache.

## 6. Monitoring & alerts

- Dokploy already produces container metrics and deployment logs. Surface the most important ones (CPU, memory, last deployment) through the widget using the monitoring endpoint.
- Configure Dokploy webhooks (Deploy succeeded/failed, health alerts) to call a Laravel route that records incidents in `photobooth_metadata` or sends notifications.
- Use Dokploy’s Slack/email integrations for infrastructure-level alerts. Application-specific alerts (e.g., ingest failures) still live inside Laravel notifications.

## 7. Production readiness checklist

1. Alle Compose-Stacks in Dokploy laufen mit Health Checks & Volumes.
2. `photobooth` volume mounted for Laravel + vsftpd + control service.
3. Database/Redis backups scheduled (Dokploy snapshot or external tooling).
4. `.env` enthält die Dokploy-API-Credentials und `DOKPLOY_COMPOSE_IDS`.
5. Scheduler, Worker, Horizon werden im Compose-Stack überwacht.
6. SuperAdmin-Widget zeigt die Compose-Stacks und erlaubt Redeploy/Stop.
7. Webhooks/alerts configured for failed deployments or unhealthy containers.

With this setup the Fotospiel team can manage deployments, restarts, and metrics centrally through Dokploy while Laravel’s scheduler and workers continue to run within the same infrastructure.

## 8. Internal docs publishing in Dokploy

- Build the static docs site during CI/CD by running `./scripts/build-docs-site.sh`. Upload the resulting `docs/site/build` directory as part of the deployment artifact or copy it into the Dokploy server before redeploying the stack.
- `docker-compose.dokploy.yml` mounts that directory into the Nginx container and exposes it at `/internal-docs/`, protected by HTTP Basic Auth.
- Update `docker/nginx/.htpasswd-docs` with production credentials (use `htpasswd -c docker/nginx/.htpasswd-docs <user>` locally, then redeploy). The repository ships with a weak default only for development—always override it in Dokploy.
- If Dokploy builds the image itself, add a post-build hook or automation step that runs the docs build and copies it into the shared storage volume before restarting the `web` service.