sso-service memory management

Overview

The Keycloak authentication system (sso-service container) in the imaging-services component automatically uses 70% of available container memory. These instructions explain how to adjust this memory allocation.

Prerequisites

Administrative access to the server where imaging-services is installed
Basic understanding of Docker and YAML configuration

Steps to configure memory settings

Step 1 - Locate and edit Docker Compose file

Locate and edit the following file on the machine on which the imaging-services component is installed:

Edit the file using your preferred editor (vim, nano, etc.)
sudo nano /opt/cast/installation/imaging-services/docker-compose.yml

Step 2 - Modify memory configuration

Locate the sso-service: section in the file:

services:
    sso-service:
        environment:

Add ONE of the following memory configuration options under the environment: section:

Option A: Percentage-based memory allocation

environment:
    # Default configuration that uses 70% of available memory (inside the container, not host memory)
    JAVA_OPTS_KC_HEAP: -XX:MaxRAMPercentage=70 -XX:MinRAMPercentage=70 -XX:InitialRAMPercentage=50

Adjust the percentage values based on your needs. Lower percentages will reduce memory usage.

Option B: Fixed memory allocation

environment:
    # To set a fixed memory usage
    JAVA_OPTS_KC_HEAP: -Xms64m -Xmx512m

-Xms sets initial memory and -Xmx sets maximum memory. Adjust these values according to your server capacity and application needs.

Step 3 - Apply changes

After saving the file, restart the imaging-services containers to apply your changes:

cd /opt/cast/installation/imaging-services/
docker-compose up -d

Step 4 - Check memory usage

Monitor the memory consumption to ensure your changes were applied correctly:

docker stats

Look for the sso-service container in the output to confirm its memory usage matches your configuration:

Troubleshooting

If the service fails to start after configuration changes:

Check container logs: docker logs sso-service
Verify your YAML syntax is correct (proper indentation is critical)
Consider increasing memory limits if you see “Out of Memory” errors

Additional Information

When using Option B: Fixed memory allocation, the JVM will use additional memory beyond the heap space for classes and other operations
Monitor system performance after changes to ensure stability