Memory Management in Containers
Understand how Node.js memory works in Galaxy and when to configure heap size manually.
Running out of memory during traffic spikes? Getting mysterious container restarts? You're not alone.
Understanding how Node.js manages memory in containers can save you hours of debugging. The good news is that Galaxy and Node.js handle most of this automatically.
Node.js Is Container-Aware
Modern Node.js (v12 and later) is container-aware. It automatically detects your container's memory limits and sets the heap to about 50% of the container size, up to a maximum of 2GB.
| Container Memory | Default Heap |
|---|---|
| 256MB | ~128MB |
| 512MB | ~256MB |
| 1GB | ~512MB |
| 2GB | ~1GB |
| 4GB | ~2GB (max) |
| 8GB | ~2GB (max) |
It's Automatic for Most Apps
For most applications, Node.js figures out the right memory settings on its own. You don't need to do anything unless you're hitting limits during traffic spikes.
Heap vs Actual Usage
Just because Node.js allocates 1GB of heap doesn't mean your app uses all of it. Under normal traffic, your app might consume 500MB. But during traffic spikes, it tries to allocate more, and things get tight if you're close to the limit.
When to Configure Memory Manually
Don't worry if you're not hitting memory limits. Most apps don't need manual configuration.
But if you want predictable control (or need more than the 2GB default cap), you can set the heap size explicitly.
We recommend allocating 70% to 90% of your container's memory to the heap. This gives your app plenty of room while leaving headroom for the Node.js runtime, native modules, and the operating system.
| Container Memory | Recommended Range (70-90%) |
|---|---|
| 256MB | 180–230 MB |
| 512MB | 360–460 MB |
| 1GB | 720–920 MB |
| 2GB | 1400–1800 MB |
| 4GB | 2800–3600 MB |
| 8GB | 5600–7200 MB |
When You Should Customize
Only manually configure heap size if:
- You're seeing "JavaScript heap out of memory" errors
- Your app crashes during traffic spikes
- You have a larger container and need the extra headroom
Otherwise, stick with defaults.
Configuring Heap Size
If you decide to configure memory manually, here's how.
For Meteor applications, add GALAXY_NODE_OPTIONS to your settings.json file:
{
"galaxy.meteor.com": {
"env": {
"GALAXY_NODE_OPTIONS": "--max-old-space-size=1600"
}
}
}Why GALAXY_NODE_OPTIONS?
Galaxy uses GALAXY_NODE_OPTIONS instead of the standard NODE_OPTIONS.
Meteor (since version 1.6) uses NODE_OPTIONS internally, and that variable
doesn't allow garbage collection parameters to be adjusted.
For Node.js, Python, and AdonisJS apps, set NODE_OPTIONS in the Galaxy dashboard:
- Open your app in Galaxy
- Go to Settings → Environment Variables
- Add:
NODE_OPTIONS=--max-old-space-size=1600
After updating, redeploy for the change to take effect.
Examples
Here are some real-world scenarios.
2GB Container with Traffic Spikes
You're running tight on memory during traffic spikes. Default heap is ~1GB, but you need more headroom.
Solution: Allocate 80% of container memory to heap:
{
"galaxy.meteor.com": {
"env": {
"GALAXY_NODE_OPTIONS": "--max-old-space-size=1600"
}
}
}This allocates 1600MB instead of the default ~1GB.
8GB Container Needing Extra Headroom
You have a larger container and need more than the 2GB default cap.
Solution: Allocate 80% of your 8GB container:
{
"galaxy.meteor.com": {
"env": {
"GALAXY_NODE_OPTIONS": "--max-old-space-size=6400"
}
}
}This gives your app 6.4GB of heap space.
Troubleshooting
Quick Reference
Defaults: Node.js auto-detects container limits and sets heap to ~50% (max 2GB)
Custom config: Allocate 70-90% of container memory to the heap
Meteor: Use GALAXY_NODE_OPTIONS
Web Apps: Use NODE_OPTIONS
Monitor: Check container metrics in Galaxy dashboard regularly
Remember: Increasing heap size doesn't fix memory leaks