# Operations ### Installation ``` sudo tools/worker install ``` This copies the systemd unit files (`vte-worker@.service` and `vte-worker@.socket`) to `/etc/systemd/system/`, enables the socket, and starts it. Both files are [systemd templates](https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html) that take the relative path from `/var/www/html` as the instance parameter (e.g. `vte-worker@vte-agentic`), which allows running multiple Workers for different VTE installations on the same machine. If your installation differs from `/var/www/html/PATH`, you must edit the templates manually or with `systemctl edit [--full]` for both `vte-worker@.socket` and `vte-worker@.service`, before installing. #### Commands

Command	Effect
`tools/worker install`	Install systemd units, enable and start the socket
`tools/worker restart`	Send a restart signal to the running Worker
`tools/worker status`	Print uptime, number of active consumers, queued jobs

#### Signals

Signal	Effect
`SIGTERM` / `SIGINT`	Graceful shutdown: stop accepting new connections, wait for all running Consumers to finish, then exit.
`SIGHUP` / `SIGUSR1`	Reload.

#### Configuration

Setting	Location
Maximum concurrent Consumers	`Zygote.php — CONSUMERS_MAX`
Socket path	`systemd/vte-worker@.socket — ListenStream` `config.inc.php — $worker_socket_URL`
Log file	`logs/worker.log`

--- ### Web servers config All clients must hold a streaming connection to the worker to receive events in **real time**. This means your web server pipeline must handle - **concurrently** - **without buffering or compression** - **at least 1 connection per user across all vte installs** for [browsers that support the SharedWorker](https://caniuse.com/sharedworkers) - **plus margin for heartbeats** this translates to reverse proxies, single virtualhosts, apache proxy module, php fpm pools, ecc... To simplify targeting the streaming connections only without interfering with other requests flows, `sse.php` can be choosen. #### PHP FPM pool `/etc/php/8.3/fpm/pool.d/sse.conf` ```ini [sse] user = www-data group = www-data ; align with your web server listen = /run/php/php8.3-fpm-sse.sock listen.owner = www-data listen.group = www-data listen.mode = 0660 pm = dynamic ; at least 1 per user + 10 for heartbeats ; 30 users for vte1, 20 users for vte2 -> 60 childrens pm.max_children = 60 pm.start_servers = 8 pm.min_spare_servers = 4 pm.max_spare_servers = 12 pm.max_requests = 500 ; enable to verify (domain.com/status?full) ; pm.status_path = /status ``` #### Apache + mod\_proxy `/etc/apache2/sites-available/domain.conf` ```ruby # ... # example pre-existing config SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://main" # /run/php/php8.3-fpm-sse.sock - different pool, must be configured in php-fpm # fcgi://sse - "sse" is an arbitrary name, must not conflict with other apache pools SetHandler "proxy:unix:/run/php/php8.3-fpm-sse.sock|fcgi://sse" SetEnv no-gzip 1 SetEnv dont-vary 1 ProxySet flushpackets=on timeout=600 # ... ``` #### NGINX gateway `/etc/nginx/conf.d/domain.conf` ```nginx server { # ... location ~ \.php(?:$|/) { include fastcgi_params; # ... fastcgi_pass_header X-Accel-Buffering; # forward header to client (to reverse proxy) } # ... } ``` #### NGINX reverse proxy `/etc/nginx/conf.d/proxy_hosts/domain.conf` (can differ) ```nginx server { # ... location /sse.php { proxy_buffering off; proxy_read_timeout 3600; proxy_send_timeout 60; # ... proxy_pass http://...; } # ... } ``` --- ### Troubleshooting #### Enable Logging Logging is disabled by default. To enable it, set the static flag before starting the Worker: ``` \Vtenext\Services\Worker\Worker::$enableLog = true; ``` Logs are written to `logs/worker.log`. The log format includes a timestamp, the process role, and the message. In the browser, put the console verbosity to debug. #### Common Issues

Symptom	Likely Cause
Connection refused	The Worker is not running or the socket path is incorrect. Check `$worker_socket_URL` in `config.inc.php` and verify the socket file exists.
Consumer not starting	Process limit reached (`RLIMIT_NPROC`). The Worker attempts to raise it to 1000 + `CONSUMERS_MAX` at startup.
Job queued but never runs	All 10 Consumer slots are occupied by long-running tasks. Check `tools/worker status` for current usage.
CRM doesn't load anymore	All PHP-FPM pool slots are saturated, check with the `/status` endpoint

#### SharedWorker When the SharedWorker is active, [debugging can done differently on each browser](https://lihautan.com/Debugging%20web%20workers): - **Firefox** — visit about:debugging#workers (copy-paste) and press **Debug** then you can inspect everything and put breakpoints. Logs are also shown in the first tab that spawned the SW (*yes 3 times, it's a browser bug as of June 2026*) and in the browser console in multi-process mode (Ctrl+Shift+J). - **Chrome** — visit chrome://inspect/#workers (copy-paste) and press **Inspect**, same story. No logs are shown in individual tabs. --- ### Technical limitations #### Browsers connections cap Web connections from browser tabs rely on Server-Sent Events (SSE), which keep a long-lived HTTP connection open to the server. Browsers enforce a hard limit of **6 concurrent connections per domain** (HTTP/1.1). The `SharedWorker.js` script multiplexes all tabs through a single SSE connection per browser, bypassing the limit entirely. - When SharedWorker is not available (older or unsupported browsers), each tab opens its own SSE connection and the 6-connection limit per domain applies. - The Worker's `CONSUMERS_MAX` limit (10 concurrent Consumer processes) is a separate server-side concern — it caps how many jobs run in parallel, not how many connections can remain open. #### Disconnection detection TCP provides no built-in notification when a peer disconnects, but even so some web servers components don't forward such events. To detect that a browser has closed the connection, the `WebConnector` writes a newline at every read tick (default every 10 seconds) and clients must keep sending heartbeats (default every 30 seconds) otherwise the worker will reap them. #### Xdebug and `set_time_limit` When the Xdebug extension is loaded, `set_time_limit(0)` (which normally removes the execution time limit) does not work reliably. Xdebug overrides PHP's internal timer and enforces its own `xdebug.max_nesting_level` and related constraints, which can cause long-running Consumer methods to be terminated prematurely on development environments where Xdebug is active. If the Worker behaves unexpectedly during development, disable Xdebug or set `xdebug.mode=off` in the PHP configuration.