Emphasize the need for setting container limit

Closes keycloak#28729

Signed-off-by: Martin Bartoš <mabartos@redhat.com>

docs/documentation/release_notes/topics/24_0_0.adoc

@@ -430,13 +430,14 @@ mappers would never be used. The supported options were updated to only include
 - `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
 - `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`
 
-= Different JVM memory settings when running in container
+= Different JVM memory settings when running in a container
 
 Instead of specifying hardcoded values for the initial and maximum heap size, {project_name} uses relative values to the total memory of a container.
-The JVM options `-Xms`, and `-Xmx` were replaced by `-XX:InitialRAMPercentage`, and `-XX:MaxRAMPercentage`.
+The JVM options `-Xms` and `-Xmx` were replaced by `-XX:InitialRAMPercentage` and `-XX:MaxRAMPercentage`.
 
-For more details, see the 
-https://www.keycloak.org/server/containers[Running Keycloak in a container] guide.
+WARNING: It can significantly impact memory consumption, so executing particular actions might be required.
+
+For more details, see the link:{upgradingguide_link}[{upgradingguide_name}].
 
 ifeval::[{project_community}==true]
 = GELF log handler has been deprecated

docs/documentation/upgrading/topics/changes/changes-24_0_0.adoc

@@ -488,6 +488,17 @@ For custom extensions there may be some changes needed:
 
 The algorithm that {project_name} uses to sign internal tokens (a JWT which is consumed by {project_name} itself, for example a refresh or action token) is being changed from `HS256` to the more secure `HS512`. A new key provider named `hmac-generated-hs512` is now added for realms. Note that in migrated realms the old `hmac-generated` provider and the old `HS256` key are maintained and still validate tokens issued before the upgrade. The `HS256` provider can be manually deleted when no more old tokens exist following the {adminguide_link}#rotating-keys[rotating keys guidelines].
 
+= Different JVM memory settings when running in a container
+
+The JVM options `-Xms` and `-Xmx` were replaced by `-XX:InitialRAMPercentage` and `-XX:MaxRAMPercentage` when running in a container.
+Instead of the static maximum heap size settings, {project_name} specifies the maximum as 70% of the total container memory.
+
+As the heap size is dynamically calculated based on the total container memory, you should *always set the memory limit* for the container.
+
+WARNING: If the memory limit is not set, the memory consumption rapidly increases as the maximum heap size grows up to 70% of the total container memory.
+
+For more details, see the https://www.keycloak.org/server/containers#_specifying_different_memory_settings[Running Keycloak in a container] guide.
+
 ifeval::[{project_community}==true]
 = GELF log handler has been deprecated
 

docs/guides/server/containers.adoc

@@ -238,17 +238,25 @@ The `-XX:MaxRAMPercentage` option represents the maximum heap size as 70% of the
 The `-XX:InitialRAMPercentage` option represents the initial heap size as 50% of the total container memory.
 These values were chosen based on a deeper analysis of {project_name} memory management.
 
+As the heap size is dynamically calculated based on the total container memory, you should *always set the memory limit* for the container.
+Previously, the maximum heap size was set to 512 MB, and in order to approach similar values, you should set the memory limit to at least 750 MB.
+For smaller production-ready deployments, the recommended memory limit is 2 GB.
+
 The JVM options related to the heap might be overridden by setting the environment variable `JAVA_OPTS_KC_HEAP`.
 You can find the default values of the `JAVA_OPTS_KC_HEAP` in the source code of the `kc.sh`, or `kc.bat` script.
-For example, you can specify the environment variable as follows:
+
+For example, you can specify the environment variable and memory limit as follows:
 
 [source,bash,subs="attributes+"]
 ----
-podman|docker run --name mykeycloak -p 8080:8080 \
+podman|docker run --name mykeycloak -p 8080:8080 -m 1g \
         -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
         -e JAVA_OPTS_KC_HEAP="-XX:MaxHeapFreeRatio=30 -XX:MaxRAMPercentage=65" \
         quay.io/keycloak/keycloak:{containerlabel} \
         start-dev
 ----
 
+WARNING: If the memory limit is not set, the memory consumption rapidly increases as the heap size can grow up to 70% of the total container memory.
+Once the JVM allocates the memory, it is returned to the OS reluctantly with the current {project_name} GC settings.
+
 </@tmpl.guide>