Websites
Scaling and Auto-Scaling a Node.js App
Auto-scaling grows and shrinks the number of instances running your Node.js app as CPU load changes, so busy periods get more capacity and quiet periods cost less. This guide covers the KPanel tab, every setting, what gets billed, and how to make an app safe to scale.
Where Scaling Lives in KPanel
- Sign in to KPanel.
- Click Websites in the left sidebar, then click the site.
- In the site's tab strip, open Advanced, then Scaling.
The direct address is /websites/<site-id>/autoscale. The older /websites/<site-id>/scaling address still works and sends you to the same place.
The tab only appears on Node.js sites. It will not be in the menu for a WordPress, WooCommerce, static, PHP, Python, or Ruby site, because the mechanism scales a Node.js process cluster.
One Tab, One Configuration
KPanel used to carry two tabs here, Scaling and Autoscale, over one set of settings. They were two views of the same configuration, which was only ever a way to get lost, so they are now a single Scaling tab: live status, the settings, recent scale events, and the usage and cost panel for the current billing period, all in one place.
How It Works
Your app runs as a process cluster. Auto-scaling watches average CPU across the running instances and adds or removes instances against the thresholds you set.
Cluster mode is required. If your app is not already running in cluster mode, enabling auto-scaling switches it over for you, which involves a brief restart. The page tells you when that happens.
Reading the Live Status
The status card shows three things:
- Instances: how many are running right now.
- Avg CPU: the average CPU across those instances.
- Cluster: whether the app is in cluster mode. If it says no, enabling auto-scaling will switch it.
If the app is not running at all, the card says so instead of showing zeros.
The tab also shows Last scale, the time of the most recent scale event, or never.
The Settings
| Setting | Range | What it does |
|---|---|---|
| Min instances | 1 to 16 | The floor. Never scales below this |
| Max instances | 1 to 16 | The ceiling. Never scales above this |
| Scale up at CPU % | 5 to 99 | Average CPU above this adds an instance |
| Scale down at CPU % | 1 to 95 | Average CPU below this removes one |
| Cooldown (sec) | 30 to 3600 | Minimum wait between scale actions |
The master switch is the toggle in the settings card header. When auto-scaling is off, the settings are dimmed and your app stays on its current instance count.
Sensible starting values:
- Min instances 1 or 2. Two if you cannot tolerate a restart of a single instance taking the app offline.
- Max instances at what you are willing to pay for at peak, not at the ceiling.
- Scale up around 70 percent. High enough that you are not paying for headroom you never use, low enough that there is time to add capacity before requests start queueing.
- Scale down around 30 percent. Leave a wide gap between the two thresholds.
- Cooldown of a few minutes. This is the most under-appreciated setting.
Setting the two CPU thresholds close together causes flapping: the cluster scales up, immediately drops under the scale-down threshold because the load is now spread wider, scales down, spikes again, and repeats. Keep a wide gap, and use a generous cooldown. Flapping costs money and destabilises the app.
Scale Events
The tab lists recent scale events, newest first, each showing the direction, the instance count before and after, the CPU reading that triggered it, and the time.
This is the log to read when the app misbehaved. A burst of up and down events in a few minutes means your thresholds are too close or your cooldown too short. A single scale-up that never came back down means load stayed high, which is a capacity question rather than a configuration one. No events at all when you expected some means either the CPU never crossed a threshold or auto-scaling is switched off.
What Auto-Scaling Costs
Instances above your plan's base allocation are metered and billed by the second. The tab shows, for the current period:
- Instance-time used, in hours and minutes, with the raw instance-seconds underneath.
- Spent so far in this period.
- Projected month-end, extrapolated from usage so far.
- Tracking, how many usage windows have been billed out of the total recorded.
- Period progress, days elapsed out of days in the month.
The per-second rate is shown at the top of the same panel, so the figure you are billed on is always visible next to the usage it applies to.
The projection is the number to watch. It extrapolates from what you have used so far, so an unusually busy week early in the month will overstate it. Check it a few days in, then again mid-month, before drawing conclusions. If it is higher than you want, lower the maximum instance count rather than raising the scale-up threshold: the ceiling is a hard limit, a threshold is only a hint.
Scaling down to the minimum stops the metering. If you turn auto-scaling off entirely, the app stays on whatever instance count it currently has, so drop it back to the minimum first if cost is the reason you are switching off.
Making an App Safe to Scale
The page carries a warning, and it is the most important thing on it: your Node.js app must be cluster-safe to scale cleanly across instances.
In practice that means:
No in-memory session state. If a signed-in user's session lives in one instance's memory, they are signed out whenever a request lands on a different instance. Move sessions to a shared store.
No in-memory cache you rely on for correctness. Each instance has its own. A cache that must be consistent has to be shared.
No local filesystem writes you expect to read back. Uploads written to local disk by one instance are invisible to the others. Write to shared storage.
No unguarded scheduled work. If a timer runs inside the app, every instance runs it, so a nightly job at four instances runs four times. Move scheduled work to a cron job, or guard it with a lock. See Cron Jobs.
No assumption that instance count is stable. Anything that partitions work by instance index breaks the moment the count changes.
If any of these apply to your app, fix them before enabling auto-scaling. An app that is not cluster-safe fails in ways that are intermittent and hard to reproduce, because they depend on which instance served which request.
Troubleshooting
The toggle will not enable. Enabling needs the site write permission. With a read-only role the controls are disabled.
The app restarted when I enabled auto-scaling. Expected. Switching to cluster mode requires a restart, and it happens once.
Users are being signed out at random. Classic non-cluster-safe symptom. Sessions are in memory and requests are landing on different instances.
Instances scaled up and never came down. Either load stayed above the scale-down threshold, or something is holding CPU high independently of traffic. Check the events list and look at what the app is actually doing.
A scheduled job ran several times. Every instance ran it. Move it to a cron job or add a lock.
Nothing scales. Confirm the toggle is on, the app is running, and cluster mode is enabled. Then check whether CPU actually crossed your scale-up threshold in the events list.
The cost is higher than expected. Look at the events list for flapping, then lower your maximum instance count.
Related Pages
- Site Performance and APM to see whether CPU is genuinely the bottleneck.
- Site Uptime Monitoring to confirm scaling is actually improving availability.
- Cron Jobs for scheduled work that must run exactly once.
- Resizing a Cloud Server if you need a bigger machine rather than more instances.