fotospiel-app/docs/queue-supervisor

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
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.

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

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

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

Heads-up: Guest push notifications are dispatched on the notifications queue. Either add that queue to the default worker (queue-worker.sh default,notifications) or create a dedicated worker so push jobs are consumed even when other queues are busy.

3. Optional: Horizon container

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

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.
• SECURITY_SCAN_QUEUE — overrides the queue name for the photo antivirus/EXIF worker (media-security by default).
• 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:

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.

8. Running inside Dokploy

If you host Fotospiel on Dokploy:

• Create separate Dokploy applications for each worker type using the same image and command snippets above (queue-worker.sh default, media-storage, etc.).
• Attach the same environment variables and storage volumes defined for the main app.
• Use Dokploy’s one-off command feature to run migrations or queue:retry.
• Expose the Horizon service through the Dokploy HTTP proxy (or keep it internal and access via SSH tunnel).
• Enable health checks so Dokploy restarts workers automatically if they exit unexpectedly.

These services can be observed, redeployed, or reloaded from Dokploy’s dashboard and from the SuperAdmin integration powered by the Dokploy API.