Scaling and clustering #

This page is for engineers who plan capacity or a high-availability setup. The operator's guide, with a checklist, is Several web nodes; the cluster file handler is described in Clustering and shared storage.

Contents #

1. Scale up first
2. Scaling out: what must be shared
3. Files: the cluster file handler
4. Sessions
5. Database scaling
6. The edge: load balancer and proxies
7. Operations across nodes
8. Limits

Scale up first #

A single machine with enough CPU and memory is the simpler choice for most sites. Before adding nodes:

1. Serve with Velocity and its response cache for anonymous traffic (Application servers).
2. Switch on the caches that fit the traffic: the role-aware HTTP cache for signed-in pages, the SQL query cache for what cannot be stored whole (Caching layers for engineers).
3. Size the worker pool by PSS, not RSS (Velocity persistent workers).
4. Measure (Performance measurement and benchmarks).

Scale out when one machine is not enough, or when a node must be able to fail without taking the site down.

Scaling out: what must be shared #

Do not put the whole var/ directory on a network share for all nodes; the cluster handler keeps the nodes in step itself.

Files: the cluster file handler #

Every cache and storage file is written through eZClusterFileHandler. The shipped handler is eZFSFileHandler (local files); for several nodes it is eZDFSFileHandler (kernel/private/classes/clusterfilehandlers/): files on a shared NFS export, their metadata in a database table, cache files copied to each node. bin/php/clusterize.php moves an installation's files into the cluster. Code that writes files directly instead of through the handler breaks clustering; reviews should catch it (Code review checklist).

Sessions #

site.ini [Session] Handler decides where sessions live: empty (the default, ezpSessionHandlerPHP) keeps them in PHP's storage on each node; ezpSessionHandlerDB keeps them in the ezsession table, visible to every node (Sessions).

Database scaling #

• SQLite cannot serve several machines: all processes must be on one machine.
• On MySQL or MariaDB, site.ini [DatabaseSettings] UseSlaveServer sends read queries to replicas (shipped disabled) (Database support, Performance and scaling).
• PostgreSQL brings replication and point-in-time recovery of its own.

The edge: load balancer and proxies #

Behind a load balancer the kernel sees the balancer's address. List it in site.ini [HTTPHeaderSettings] TrustedProxies[], or forwarded headers (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host) are ignored and HTTPS detection, client addresses, the sign-in lockout and the audit log are wrong (Trusted proxies). Exponential sends no purges to a CDN or caching proxy; one that stores pages must be told what to store and for how long.

Operations across nodes #

Limits #

• No built-in purge for external proxies.
• A schema change (exp:upgrade, exp:migration:migrate) is applied once, from one node; the installation lock keeps a second run from writing at the same time on that node only.
• Per-node caches can briefly disagree after a change; plan the order of a deploy.

Related pages #

• Scaling applications
• Clustering and shared storage, for application creators
• Multi-site installations
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.