Running Thallo in production

Everything on this page is stated once, per the capability that creates the obligation. A tier-1 install (the fresh default) needs only the Core rows.

Core (every install)#

Public-site browser floor#

The public site's stylesheets use cascade layers, revert-layer and color-mix(): the floor is Chrome 111, Firefox 113 and Safari 16.2 (and their derivatives). Older browsers get the theme's own CSS without block settings applied. The tested matrix is the current stable engine of each family that the pinned Playwright ships (tools/style-proofs, run in CI on every render change).

Upgrading across a settings conversion (the cutover contract)#

A release that retires block presentation fields ships a conversion stage: the converter (thallo:blocks:convert-settings) turns the retired fields of every stored document — drafts, every retained version, the regions — into typed settings, and provision runs it only when its preflight is clean; it never bypasses an unresolved decision and never activates incompatible code after a partial run. No stage ships today (every install is authored in the settings shape), so provision's conversion step finds nothing pending; the contract below applies the first time a release adds one.

1. Stage the candidate release and verify a restorable backup (database and storage/).
2. Preflight content with the candidate converter: php glueful thallo:blocks:convert-settings --dry-run --report=storage/conversion/report.jsonl. The report is one JSON line per legacy value with its status; unmappable lines (raw hex colours, pixel sizes) need a decision.
3. Record every decision in storage/conversion/decisions.json, keyed as the report names the diagnostic and pinned to its document_hash and converter_version (choose a vocabulary token, a typed value, or discard). A decision is invalid once its document changes.
4. Enter maintenance or write protection; run the dry run again and confirm nothing is unresolved.
5. composer update && php glueful thallo:provision: provision converts, compiles the style artifact, clears caches, and stops before any of that with the report path when a diagnostic is unresolved or a document changed underneath it. Reopen writes.

Recovery after a partial conversion is restore from backup; the converter is idempotent per stage, so a retry after an interruption lands on the same state, but idempotence does not replace rollback. A fresh install is the trivial case of this contract.

Running the scheduler and the queue#

Two long-lived pieces, both plain PHP; nothing else to install with the default QUEUE_CONNECTION=database (its tables are created by provision).

The scheduler tick evaluates config/schedule.php and runs the due jobs inside the tick:

* * * * * php /path/to/site/glueful queue:scheduler run >> /path/to/site/storage/logs/scheduler.log 2>&1

A queue worker processes jobs the application dispatches (mail, extension operations, maintenance, block-type schema backfills, and a style class's detach-everywhere or remove-everywhere job — the class stays locked until that job completes, so without a worker run it by hand with php glueful thallo:style-classes:run-job <id>). It exits on its memory and job limits, so keep it under a supervisor. A systemd unit:

[Unit]
Description=Thallo queue worker
After=network.target postgresql.service

[Service]
User=deploy
WorkingDirectory=/path/to/site
ExecStart=/usr/bin/php glueful queue:work --queue=default,webhooks,import-export,tenancy-maintenance --sleep=3 --tries=3 --max-runtime=3600
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

A worker runs only the queues it is given. Thallo's own jobs go to default; imports and exports (Settings › Import / Export) go to import-export, so an import stays "queued" on a worker that was not given that one; Run now under Utilities › Scheduled Tasks puts a task on its own queue (maintenance for most). With workspaces on, tenancy adds tenancy-purge and tenancy-maintenance. The scheduler and the queue lists every queue and what arrives on it. Add a queue name to --queue if an extension you enable documents its own. Sizing presets (*_QUEUE_MEMORY, *_QUEUE_TIMEOUT, *_QUEUE_MAX_JOBS) live in .env. A site that cannot keep a worker under a supervisor can drain the queue from a second cron line instead (queue:work --stop-when-empty); the same page gives the line and its limits. There is no inline connection: only the database and redis drivers exist. Redis (QUEUE_CONNECTION=redis plus REDIS_*) is optional and only worth it under real load.

PHP-served asset paths (web server)#

Only public/admin/* (the admin bundle, published there by thallo:provision from core/resources/admin) is real files; uploads live outside the document root at storage/uploads/ and are served at /v1/blobs/{uuid}. Three URL prefixes are generated by PHP on every request and never exist on disk:

Most nginx templates (CloudPanel's included) carry a "static files" location that matches any URL ending in .css, .js, .woff2, … and serves it straight from the document root. nginx picks the first regex location that matches, in file order, so that rule takes these URLs before location / ever sees them and answers 404: the rendered site loads unstyled and the designer loses its stylesheet and bridge.

Add a location for these prefixes above the static-file location, with the same body as location /. CloudPanel (nginx in front of Varnish in front of PHP-FPM):

  location / {
    {{varnish_proxy_pass}}
    ...
  }

  # Thallo: /theme-assets/*, /_thallo/*, /v1/* and /api-docs/* are generated by PHP, not files on
  # disk. Must precede the static-extension location below (first matching regex wins).
  location ~ ^/(theme-assets|_thallo|v1|api-docs)/ {
    {{varnish_proxy_pass}}
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_hide_header X-Varnish;
    proxy_redirect off;
    proxy_max_temp_file_size 0;
    proxy_connect_timeout      720;
    proxy_send_timeout         720;
    proxy_read_timeout         720;
    proxy_buffer_size          128k;
    proxy_buffers              4 256k;
    proxy_busy_buffers_size    256k;
    proxy_temp_file_write_size 256k;
  }

  location ~* ^.+\.(css|js|jpg|jpeg|gif|png|ico|gz|svg|svgz|ttf|otf|woff|woff2|eot|mp4|ogg|ogv|webm|webp|zip|swf|map|mjs)$ {
    expires max;
    ...
  }

Plain nginx + PHP-FPM (no Varnish): the same location, handing the request to the front controller:

  location ~ ^/(theme-assets|_thallo)/ {
    try_files /index.php?$args =404;
  }

Apache with mod_rewrite needs nothing extra as long as the standard front-controller rewrite (RewriteCond %{REQUEST_FILENAME} !-f → index.php) is in place; only a rule that short-circuits by extension has to exclude the two prefixes.

Verify from the server (a CDN or Varnish may hold an earlier 404 — purge if the browser disagrees):

curl -sI https://example.com/theme-assets/site.css?t=default | head -1   # HTTP/2 200
curl -sI https://example.com/_thallo/preview.css | head -1                # HTTP/2 200

php glueful thallo:provision and php glueful thallo:doctor run this probe on a public BASE_URL and report asset-routing as a warning when the answer is 404.

Email (any capability that sends mail)#

Commerce (after extensions:enable Commerce)#

Payments (after extensions:enable Payvia)#

Workspaces / multi-tenancy (after enabling via Settings → Workspaces)#

Monitoring worth having (any install taking money)#

Alert on: failed/undelivered provider webhooks, payment_late_rejected audit entries (Admin → Audit, category security — a refused late or duplicate payment may need a refund), mail failures, queue backlog, and 5xx rates.