From 2bd5dafba744729d36f501e66cb4f218dc62eaa1 Mon Sep 17 00:00:00 2001
From: Alexander Strachan <astrachan@gitlab.com>
Date: Mon, 5 Jul 2021 10:19:19 +0000
Subject: [PATCH] Resolve "Docs update for puma worker installation
 requirements"

---
 doc/install/requirements.md | 57 +++++++++++++++++++++++++++++++++----
 1 file changed, 52 insertions(+), 5 deletions(-)

diff --git a/doc/install/requirements.md b/doc/install/requirements.md
index a84cd179b3005..133c3103c7b79 100644
--- a/doc/install/requirements.md
+++ b/doc/install/requirements.md
@@ -183,11 +183,58 @@ tune the Puma settings:
 The recommended number of workers is calculated as the highest of the following:
 
 - `2`
-- Number of CPU cores - 1
-
-For example a node with 4 cores should be configured with 3 Puma workers.
-
-You can increase the number of Puma workers, providing enough CPU and memory capacity is available.
+- A combination of CPU and memory resource availability (see how this is configured automatically for the [Linux package](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/ef9facdc927e7389db6a5e0655414ba8318c7b8a/files/gitlab-cookbooks/gitlab/libraries/puma.rb#L31-46)).
+
+Take for example the following scenarios:
+
+- A node with 2 cores / 8 GB memory should be configured with **2 Puma workers**.
+
+  Calculated as:
+
+  ```plaintext
+  The highest number from
+  2
+  And 
+  [
+  the lowest number from
+    - number of cores: 2
+    - memory limit: (8 - 1.5) = 6
+  ]
+  ```
+
+  So, the highest from 2 and 2 is 2.
+
+- A node with 4 cores / 4 GB memory should be configured with **2 Puma workers**.
+
+  ```plaintext
+  The highest number from
+  2
+  And 
+  [
+  the lowest number from
+    - number of cores: 4
+    - memory limit: (4 - 1.5) = 2.5 
+  ]
+  ``
+
+  So, the highest from 2 and 2 is 2.
+
+- A node with 4 cores / 8 GB memory should be configured with **4 Puma workers**.
+
+  ```plaintext
+  The highest number from
+  2
+  And 
+  [
+  the lowest number from
+    - number of cores: 4
+    - memory limit: (8 - 1.5) = 6.5
+  ]
+  ```
+
+  So, the highest from 2 and 4 is 4.
+
+You can increase the number of Puma workers, provided enough CPU and memory capacity is available.
 A higher number of Puma workers usually helps to reduce the response time of the application
 and increase the ability to handle parallel requests. You must perform testing to verify the
 optimal settings for your infrastructure.
-- 
GitLab