Applications

Scaling apps

Run several copies of a Node.js app or several Python workers on one server, and cap an app's CPU and memory with systemd limits.

Last updated

An app can run as several copies on its server to use more CPU cores, and can be capped on CPU and memory so it never takes the whole server. Both are set per app and apply to all of its copies together.

Run several copies

Open the app's Overview tab, set Copies (or Workers for a Python app) in the Scaling card, and click Scale now. Apps can run from 1 to 16 copies. This needs agent 0.14.0 or newer.

How the copies run depends on the runtime:

RuntimeHow several copies run
Node.jsPM2 cluster mode: the copies share the app's port and PM2 spreads connections between them.
PythonOne process with that many workers: the app gets WEB_CONCURRENCY, which Gunicorn and Uvicorn use as their number of workers.
Go, RubyAlways one process, so the Scaling card is not shown. Start more workers inside the app instead (Puma reads WEB_CONCURRENCY).

Node.js copies

PM2 cluster mode can only run a Node.js script, so the start command must run a Node.js file, such as node server.js, not npm start. Use the command your package.json start script runs. If the start command cannot run in cluster mode, setting more than one copy fails and says why.

Copies are added or removed while the others keep serving. Going from one copy to several, or back to one, restarts the app once. With several copies, the Scaling card lists each one with its status, process ID, memory, CPU and restarts.

Python workers

Changing the number of workers restarts the app. Programs other than Gunicorn and Uvicorn may ignore WEB_CONCURRENCY and run one process; the deployment log says so.

A running app is reconfigured as soon as you scale it. A stopped or not yet deployed app uses the new number the next time it starts.

Resource limits

Under Resource limits on the app's Settings tab:

SettingRangeMeaning
CPU (% of one core)10 to 6,400100 is one full core, 200 two cores. Empty for no limit.
Memory (MiB)64 to 262,144The most memory the app may use. Empty for no limit.

The limits are applied by systemd to the app's pm2-<app> unit (CPUQuota and MemoryMax), so they cover every copy together. systemd stops the app if it goes over its memory limit, and starts it again. Limits apply to the running app, not to installs and builds.

Changing a limit needs a restart: click Apply and restart on the banner that appears.

For a hosting customer's app, the limits stay within the CPU and memory per app that the customer's plan allows. See Hosting and billing.

Zero downtime

Zero-downtime reloads use the same PM2 cluster mode, even with one copy. See Zero-downtime reloads.