Configuration Reference

The Worker is configured through a single YAML file, passed via the --config flag (default: config.yaml in the working directory).

Full Example

# config.yaml

ws_port: 9000        # WebSocket port — browsers connect here
internal_port: 9001  # Internal API port — Wavelog PHP connects here

# Shared secret — must match the value in Wavelog's worker.php config.
# Minimum 32 characters. Generate with: openssl rand -hex 32
worker_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Optional: Redis URL for multi-instance clustering.
# Omit or leave empty for single-instance mode.
# redis_url: "redis://localhost:6379/2"

Options Reference

ws_port

The TCP port on which the Worker listens for incoming WebSocket connections from browsers.

Browsers connect to ws://your-host:9000/ws?topic=<topic>. When using a reverse proxy for HTTPS, this port does not need to be publicly exposed.

internal_port

The TCP port for the internal HTTP API. Wavelog's PHP backend uses this port to:

• Register and unregister topics
• Publish broadcast events to connected clients
• Query the Worker's status

This port should not be exposed to the internet. Restrict it to your internal network or Docker network.

worker_secret

A shared secret that authenticates all communication between Wavelog's PHP backend and the Worker. Every request to the internal API must include this value in the X-Worker-Secret HTTP header.

The same secret must be configured on the Wavelog side in application/config/worker.php.

Generate a secret:

openssl rand -hex 32

redis_url

A Redis connection URL. When set, the Worker uses Redis Pub/Sub to synchronize broadcast events across multiple Worker instances.

redis_url: "redis://localhost:6379/2"

The URL format follows the standard Redis URL scheme:

redis://[:password@]host[:port][/db]
rediss://...   # TLS

Use a dedicated Redis database (e.g. /2) to avoid key collisions with other applications.

When redis_url is empty or omitted, the Worker runs in single-instance mode: all state is in-memory and lost on restart. Topics are automatically re-registered by Wavelog on the next page load.

See Clustering for when and how to use Redis.

Defaults Summary

Ports Overview

┌──────────────────────────────────────────┐
│              Wavelog Worker              │
│                                          │
│  :9000  WebSocket ──► browsers           │
│  :9001  Internal API ──► Wavelog PHP     │
└──────────────────────────────────────────┘