fotospiel-app/docs/queue-supervisor/README.md

## Docker Queue & Horizon Setup

This directory bundles ready-to-use entrypoint scripts and deployment notes for running Fotospiel’s queue workers inside Docker containers. The examples assume you already run the main application in Docker (e.g. via `docker-compose.yml`) and share the same application image for workers.

### 1. Prepare the application image

Make sure the worker scripts are copied into the image and marked as executable:

```dockerfile
# Dockerfile
COPY docs/queue-supervisor /var/www/html/docs/queue-supervisor
RUN chmod +x /var/www/html/docs/queue-supervisor/*.sh
```

If you keep the project root mounted as a volume during development the `chmod` step can be skipped because the files will inherit host permissions.

### 2. Queue worker containers

Add one or more worker services to `docker-compose.yml`. The production compose file in the repo already defines `queue` and `media-storage-worker` services that call these scripts; the snippet below shows the essential pattern if you need to tweak scaling.

```yaml
services:
  queue-worker:
    image: fotospiel-app          # reuse the main app image
    restart: unless-stopped
    depends_on:
      - redis                     # or your queue backend
    environment:
      APP_ENV: ${APP_ENV:-production}
      QUEUE_CONNECTION: redis
      QUEUE_TRIES: 3              # optional overrides
      QUEUE_SLEEP: 3
    command: >
      /var/www/html/docs/queue-supervisor/queue-worker.sh default

  media-storage-worker:
    image: fotospiel-app
    restart: unless-stopped
    depends_on:
      - redis
    environment:
      APP_ENV: ${APP_ENV:-production}
      QUEUE_CONNECTION: redis
      QUEUE_TRIES: 5
      QUEUE_SLEEP: 5
    command: >
      /var/www/html/docs/queue-supervisor/queue-worker.sh media-storage
```

Scale workers by increasing `deploy.replicas` (Swarm) or adding `scale` counts (Compose v2).

### 3. Optional: Horizon container

If you prefer Horizon’s dashboard and auto-balancing, add another service:

```yaml
services:
  horizon:
    image: fotospiel-app
    restart: unless-stopped
    depends_on:
      - redis
    environment:
      APP_ENV: ${APP_ENV:-production}
      QUEUE_CONNECTION: redis
    command: >
      /var/www/html/docs/queue-supervisor/horizon.sh
```

Expose Horizon via your web proxy and protect it with authentication (the app already guards `/horizon` behind the super admin panel login if configured).

### 4. Environment variables

- `QUEUE_CONNECTION` — should match the driver configured in `.env` (`redis` recommended).
- `QUEUE_TRIES`, `QUEUE_SLEEP`, `QUEUE_TIMEOUT`, `QUEUE_MAX_TIME` — optional tuning knobs consumed by `queue-worker.sh`.
- `STORAGE_ALERT_EMAIL` — enables upload failure notifications introduced in the new storage pipeline.
- Redis / database credentials must be available in the worker containers exactly like the web container.

### 5. Bootstrapping reminder

Before starting workers on a new environment:

```bash
php artisan migrate
php artisan db:seed --class=MediaStorageTargetSeeder
```

Existing assets should be backfilled into `event_media_assets` with a one-off artisan command before enabling automatic archival jobs.

### 6. Monitoring & logs

- Containers log to STDOUT; aggregate via `docker logs` or a centralized stack.
- Horizon users can inspect `/horizon` for queue lengths and failed jobs.
- With plain workers run `php artisan queue:failed` (inside the container) to inspect failures and `php artisan queue:retry all` after resolving issues.

### 7. Rolling updates

When deploying new code:

1. Build and push updated app image.
2. Run migrations & seeders.
3. Recreate worker/horizon containers: `docker compose up -d --force-recreate queue-worker media-storage-worker horizon`.
4. Tail logs to confirm workers boot cleanly and start consuming jobs.