Reference

Caddy Reference

Directive overview for Queue, Scheduler, Pogo, Upload, and WebSocket.

Queue

pogo_queue is a global Caddy option.

Caddyfile

{
  pogo_queue {
    backend redis {
      url {$POGO_REDIS_URL}
    }

    worker public/queue-worker.php
  }
}

Directive	Default	Description
`backend redis`	`redis`	Durable Redis Streams backend.
`backend memory`	none	Local demo backend only.
`worker`	`queue-worker.php`	PHP worker script.
`queues`	`default`	Comma or space separated queue names.
`concurrency`	`1`	Number of queue reserve loops.
`worker_threads`	`concurrency`	FrankenPHP worker thread count.
`max_payload_bytes`	`1048576`	Maximum job payload size.
`visibility_timeout`	`90s`	Time before a pending job can be reclaimed.
`reserve_timeout`	`1s`	Blocking reserve timeout.
`shutdown_timeout`	`30s`	Grace period for queue loop shutdown.
`max_attempts`	`3`	Attempts before failed stream/dead-letter behavior.

Redis backend directives:

Directive	Default	Description
`url`	`POGO_REDIS_URL`	Redis URL. Required if env var is absent.
`key_prefix`	`pogo`	Redis key prefix.
`group`	`default`	Redis consumer group.
`consumer`	hostname and process id	Base consumer name.
`tls`	`false`	Enables TLS for Redis connection.

Memory backend directives:

Directive	Default	Description
`max_messages`	`1000`	Maximum in-memory messages.
`max_total_bytes`	`67108864`	Maximum total payload bytes.

Scheduler

pogo_scheduler is a global Caddy option.

Caddyfile

{
  pogo_scheduler {
    command php artisan schedule:run
    dir /var/www/html
    timeout 5m
    overlap allow
    shutdown_grace 30s
  }
}

Directive	Default	Description
`command`	`php artisan schedule:run`	Command and arguments.
`dir`	empty	Optional working directory.
`timeout`	`5m`	Max duration per command run.
`overlap`	`allow`	`allow` or `skip`.
`shutdown_grace`	`30s`	Grace period before cancelling active commands.

Pogo

pogo is a global Caddy option.

Caddyfile

{
  pogo {
    worker public/pogo-worker.php
    num_threads 8
    max_wait 30s

    pool external_api {
      worker public/pogo-worker.php
      num_threads 16
      max_wait 10s
    }
  }
}

Directive	Required	Description
`pool`	No	Defines a named worker pool. The top-level worker config is the required `default` pool.
`worker`	Yes	PHP worker script for the default pool or named pool.
`num_threads`	No	FrankenPHP worker thread count.
`max_wait`	No	Maximum `SendMessage` wait. Defaults to `30s`.

Upload

pogo_upload is both a global Caddy option and an HTTP handler directive.

Caddyfile

{
  pogo_upload {
    store default {
      worker public/upload-worker.php
      signing_secret {$POGO_UPLOAD_SECRET}

      backend local {
        root storage/app/pogo-uploads
      }
    }
  }
}

handle /_pogo/upload/* {
  pogo_upload default
}

Store directives:

Directive	Default	Description
`worker`	none	Required PHP worker script for completion and failure events.
`signing_secret`	none	Required HMAC secret for upload URLs.
`backend local`	`local`	v1 storage backend.
`root`	none	Required local backend root directory.
`token_ttl`	`15m`	Default signed URL lifetime.
`max_upload_bytes`	`1073741824`	Store-level upload limit.
`max_concurrency`	`32`	Max in-flight uploads for the store.
`read_timeout`	`30s`	Max idle read time while receiving the body.
`complete_timeout`	`10s`	Max wait for the PHP completion worker.
`progress_ttl`	`10m`	Finished progress record lifetime.

Handler argument:

Argument	Default	Description
`store`	`default`	Configured store that owns the signed URL.

WebSocket

pogo_websocket is an HTTP handler directive. Place it before php_server for the WebSocket route.

Caddyfile

route /app/* {
  pogo_websocket {
    app_id {$REVERB_APP_ID}
    app_key {$REVERB_APP_KEY}
    app_secret {$REVERB_APP_SECRET}
  }
}

Required directives:

Directive	Description
`app_id`	Reverb/Pusher app id. May be resolved from `REVERB_APP_ID`.
`app_key`	Public Reverb/Pusher app key. May be resolved from `REVERB_APP_KEY`.
`app_secret`	Shared secret. May be resolved from `REVERB_APP_SECRET`.

Common optional directives:

Directive	Default	Description
`num_workers`	`2`	Dedicated PHP auth workers.
`auth_path`	empty	Auth endpoint path. Defaults to `/broadcasting/auth` when `auth_script` is set.
`auth_script`	empty	Optional PHP auth fallback worker script. Required if `auth_path` is configured.
`max_connections`	`10000`	Max concurrent clients.
`max_auth_body`	`16384`	Max PHP auth response body size.
`max_concurrent_auth`	`100`	Auth concurrency guard.
`num_shards`	CPU based	Internal hub shard count.
`handshake_rate`	`100`	Connection attempts per second per direct remote IP.
`handshake_burst`	`50`	Handshake burst allowance.
`allowed_origins`	allow all	`*`, exact `http://` or `https://` origins, or host-only values.
`broker_queue_size`	delivery default	Internal broker queue size.
`shard_queue_size`	delivery default	Per-shard queue size.
`outbound_queue_size`	delivery default	Per-client outbound queue size.
`write_burst_size`	delivery default	Per-client write burst size.
`client_msg_rate_limit`	module default	Client event rate limit.
`client_msg_rate_burst`	module default	Client event burst.
`enable_compression`	`false`	WebSocket compression.
`ping_period`	module default	Server ping interval.
`pong_wait`	module default	Client pong timeout.
`write_wait`	module default	Socket write timeout.
`shutdown_timeout`	module default	Graceful shutdown timeout.
`webhook_url`	empty	Best-effort webhook target.
`webhook_secret`	empty	Webhook signing secret.
`redis_host`	empty	Enables Redis Pub/Sub broker.
`redis_password`	empty	Redis password.
`redis_db`	`0`	Redis database.
`redis_tls`	`false`	Redis TLS.

Upload

Signed single-file upload ingress for FrankenPHP applications.

PHP API

Native PHP functions exposed by the Pogo FrankenPHP plugins.