Overview

When configuring CircleCI Server's frontend service with custom memory limits, it's important to set the JVM heap size appropriately to avoid out-of-memory (OOM) errors while maximizing performance.

Understanding the Default Configuration

CircleCI Server's chart establishes a proven ratio between JVM heap size and container memory limits:

Default heap size: frontend.jvmHeapSize: "3g"
Default container limit: 5Gi
Ratio: Heap ≈ 60% of container memory limit

This ratio ensures sufficient memory remains for:

Non-heap JVM memory
Nginx processes
Thread stacks
Metaspace and direct buffers
Garbage collection overhead

Recommended Configuration for 18Gi Memory Limit

If you're setting your container memory limit to 18Gi, use the following guidelines:

Recommended Starting Point

JVM heap size: 10g or 11g

This maintains the same ~60% ratio as the default chart configuration:

Calculation: 18 × (3/5) ≈ 10.8 → round to 10g or 11g

Practical Range

8g to 12g

12g is acceptable if monitoring shows stable RSS (Resident Set Size) and you still have several GB of headroom under the 18Gi limit
8g provides more conservative headroom if you're experiencing memory pressure

Critical: Never Set Heap Near the Container Limit

Do not set heap anywhere near 18g when your container limit is 18Gi. The JVM and other processes require substantial non-heap memory, and setting heap too high will cause OOM errors even though the container limit appears sufficient.

Operational Best Practice

Rule: After setting JVM heap size, monitor container memory working set versus the configured limit.

If you need to increase JVM_HEAP_SIZE:

Increase the container memory limit in the same configuration change
Maintain appropriate non-heap headroom (roughly 40% of total memory)
Never let non-heap headroom shrink to zero

Example Configuration

For an 18Gi container limit, your configuration should look like:

frontend:
  jvmHeapSize: "11g"
  resources:
    limits:
      memory: "18Gi"

For CircleCI Server with an 18Gi memory limit:

Start with: 10g or 11g heap size
Acceptable range: 8g to 12g
Maintain: ~40% non-heap headroom
Always: Increase memory limits when increasing heap size

This configuration maintains the proven ratio established in CircleCI Server's default chart and ensures stable operation under memory pressure.

Monitoring Recommendations

After adjusting heap size, monitor the following metrics:

Container memory working set vs. the configured limit
JVM heap usage patterns
Out-of-memory error frequency
Garbage collection frequency and duration

If you see memory usage consistently approaching the container limit, either:

Reduce the JVM heap size slightly, or
Increase the container memory limit to maintain healthy headroom

Additional Resources

[SERVER] Recommended JVM Heap Size Configuration Based on Memory Usage