Reference

Glossary

This page defines the terms the ScalWS documentation uses, in alphabetical order, with links to where each one is described in full.

ACME

The protocol by which a certificate authority such as Let’s Encrypt issues certificates automatically. With server.acme enabled, ScalWS orders and renews the certificates of applications that set acme: true, or of site files with tls: auto. The account and certificates are kept in server.acme.state_dir (/var/lib/scalws/acme in the package); under scalws-controller all instances share it and one of them orders. scalwsctl certs shows their state. See TLS and ADR-0018.

Application

A site or service inside a tenant: its domains, an optional document root, a runtime (or a profile that supplies one), and optional routes, cache and security settings. Every domain belongs to exactly one application. Applications are named tenant/app on the command line, for example scalwsctl restart shop/web. See Applications and the applications reference.

Control plane

See data plane and control plane.

Controller

scalws-controller, the Adaptive Runtime controller. It runs several scalwsd instances on separate CPU slices that share the listening sockets, starts, activates, drains and restarts them, rolls them onto new generations, and can add or remove instances by PressureScore. It never handles client traffic. Its own configuration is controller.yaml. See scalws-controller and Adaptive Runtime.

Data plane and control plane

The data plane is what handles client traffic: scalwsd with its listeners, TLS, HTTP, cache, static files, proxy and FastCGI. The control plane is scalws-controller, which observes the instances, classifies bottlenecks, decides and manages the instances’ lifecycle, but terminates no connections. ScalWS Console sits beside both as a management process; if it fails, client traffic is not affected. See ADR-0033.

Drain

Ending work without cutting off clients: stop accepting new connections, ask keep-alive connections to close (Connection: close, HTTP/2 GOAWAY), and let requests in flight finish until a timeout, after which the remaining connections are closed. scalwsd drains on SIGTERM for up to server.limits.shutdown_timeout. An instance leaving under the controller drains for up to instances.drain_timeout and is killed after a further instances.kill_grace. After a reload, managed runtime processes that the new configuration no longer uses are drained in the background.

External endpoint

An application server that ScalWS does not start but connects to: an existing PHP-FPM pool named by php.fastcgi, or an HTTP server named by a proxy runtime’s upstream. You run and scale it yourself, for example with systemd. Under scalws-controller, applications must be reached as external endpoints (php with fastcgi, everything else through proxy). Compare managed runtime.

Generation

A numbered, validated configuration. scalwsd numbers every configuration it activates (start, reload, rollback); scalwsctl status shows the active generation and scalwsctl history the ones the process keeps in memory. scalws-controller stores each generation on disk as <state_dir>/generations/<n>/scalws.yaml, never changed afterwards, with the site files expanded into it, so a generation keeps the sites it had even when site files change later. Its instances start against an explicit generation, and a reload creates a new one. See ADR-0035.

Instance

One scalwsd process started by scalws-controller. Instances have stable ids (web-0, web-1, …), their own CPU slice, runtime directory and admin socket (/run/scalws/web-<n>/admin.sock), and their own metrics port (127.0.0.1:9910 + n by default). They go through the phases Starting, Warming, Ready, Active, Draining and Stopped, or Failed. Only Active instances receive connections. See Adaptive Runtime.

Listener

An address on which scalwsd accepts connections, set in server.listeners: a name, a socket address, and optionally TLS (with certificates or ACME), HTTP/3, the PROXY protocol and strict SNI. Changing a standalone server’s listener addresses or turning TLS on or off needs a restart; scalws-controller binds new addresses during a reload.

Managed runtime

A runtime whose processes ScalWS starts and supervises itself, as children of scalwsd in the tenant’s cgroup: php without fastcgi (a PHP-FPM pool), node and python without upstream, and container. scalwsd.service runs them; scalws-controller refuses them, because every instance would start its own copy of the application (ADR-0036). Compare external endpoint. See Applications.

PressureScore

A number from 0 to 1 that scalws-controller computes for each instance from its CPU use, event-loop lag, requests in flight and, when a target is set, p99 latency: max(cpu_lag, inflight, latency) with cpu_lag = min(cpu, lag + 0.5), so high CPU alone is not pressure but high CPU with rising loop lag is. In autoscaling mode web-tier, the controller adds an instance when the web tier stays above autoscaling.scale_out_above (0.75) and the bottleneck is the web tier itself, and removes one when it stays below autoscaling.scale_in_below (0.30). See ADR-0034.

Profile

An application profile: built-in knowledge about a framework (wordpress, woocommerce, laravel, php, nextjs, node, django, flask, fastapi, python) with detection rules, a runtime template, a health check, and cache-bypass and security rules. scalwsctl detect proposes a profile for a directory, scalwsctl profiles lists them, and profile: in an application uses one. See ADR-0011.

Reload and restart

A reload applies a changed configuration to running processes: it validates and prepares the new configuration (certificates, document roots, runtimes) and swaps it in at once; if anything fails, the active configuration keeps serving. Open connections are kept. On scalwsd.service a reload happens in the process (scalwsctl reload, SIGHUP); under scalws-controller it creates a new generation and replaces the instances one by one (scalws-controller reload).

A restart stops and starts the process (systemctl restart scalwsd). Some changes need one on a standalone server, such as listener addresses, the metrics or admin endpoints and connection limits; a reload refuses them with “requires a restart”. Restarting scalws-controller restarts only the controller: its instances keep serving and are adopted. scalwsctl restart tenant/app is different again: it replaces one application’s processes without dropping requests. See Files and services.

Route

A path prefix inside an application with its own runtime, for example /api served by a proxy while the rest of the site is static. The longest matching prefix, compared by whole path segments, wins; requests that match no route use the application’s runtime. See the routes reference.

Runtime

How an application or route answers requests: static (files), php (FastCGI), node, python, container, proxy (an HTTP upstream), redirect or respond (a fixed response). A runtime is either a managed runtime or reaches an external endpoint; static, redirect and respond are served by scalwsd itself. See Applications.

Site file

A short YAML file that describes one site, usually /etc/scalws/sites.d/<domain>.yaml, read through the main configuration’s include. It names the domain, aliases, www handling, document root, TLS mode and at most one runtime, and becomes a tenant with an application when the configuration is loaded. scalwsctl site add|list|remove and scalwsctl migrate manage them. See Sites and the site file reference.

SNI

Server Name Indication: the host name a TLS client sends at the start of the handshake. ScalWS uses it to choose the certificate: an exact server_names match, then a one-label wildcard, then the listener’s default certificate; otherwise the handshake fails. Which application answers is decided later by the request’s Host, not by SNI. See TLS.

Strict SNI

The listener option strict_sni. With it, a request whose host differs from the SNI name of its TLS connection is answered with 421 Misdirected Request, and the client opens a new connection for that host. Browsers may otherwise reuse one HTTP/2 connection for several names its certificate covers (connection coalescing); strict SNI keeps one tenant’s connection from being used to reach another tenant’s site. See TLS.

Tenant

The unit of isolation and accounting: a named group of applications that share resource limits. Its CPU, memory, I/O and process limits are enforced through cgroup v2 for its managed application processes, its request quotas in the server, and it can run as its own Unix user. scalwsctl limit and scalwsctl high work per tenant. See the tenants reference and ADR-0010.