Merge branch '61376-add-documentation-about-how-to-enable-puma-web-server-for-installations-from-source' into 'master'

Add documentation about how to enable Puma web server for installations from source

Closes #61376

See merge request gitlab-org/gitlab-ce!28235

(cherry picked from commit 5ec4052281da296f40d6eec90301cbf44c93f5c4)

c06dfd9d Replace Unicorn with web server in the init.d script [ci skip]
95afca31 Add puma example for production [ci skip]
f2c6bfbe Add using Puma section to install from source [ci skip]
5ebf0492 Add Puma web server support to init.d file
aa7b053c Minor doc improvements to Puma instructions
29e49b45 Apply suggestion to doc/install/installation.md
6a691fa7 Apply suggestion to doc/install/installation.md

4 files changed, 113 insertions, 19 deletions

diff --git a/config/puma.rb.example b/config/puma.rb.example
new file mode 100644
index 00000000000..6558dbc6cfe
--- /dev/null
+++ b/config/puma.rb.example
@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Load "path" as a rackup file.
+#
+# The default is "config.ru".
+#
+rackup 'config.ru'
+pidfile '/home/git/gitlab/tmp/pids/puma.pid'
+state_path '/home/git/gitlab/tmp/pids/puma.state'
+
+stdout_redirect '/home/git/gitlab/log/puma.stdout.log',
+  '/home/git/gitlab/log/puma.stderr.log',
+  true
+
+# Configure "min" to be the minimum number of threads to use to answer
+# requests and "max" the maximum.
+#
+# The default is "0, 16".
+#
+threads 1, 16
+
+# By default, workers accept all requests and queue them to pass to handlers.
+# When false, workers accept the number of simultaneous requests configured.
+#
+# Queueing requests generally improves performance, but can cause deadlocks if
+# the app is waiting on a request to itself. See https://github.com/puma/puma/issues/612
+#
+# When set to false this may require a reverse proxy to handle slow clients and
+# queue requests before they reach puma. This is due to disabling HTTP keepalive
+queue_requests false
+
+# Bind the server to "url". "tcp://", "unix://" and "ssl://" are the only
+# accepted protocols.
+bind 'unix:///home/git/gitlab/tmp/sockets/gitlab.socket'
+
+workers 3
+
+require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events"
+require_relative "/home/git/gitlab/lib/gitlab/cluster/puma_worker_killer_initializer"
+
+on_restart do
+  # Signal application hooks that we're about to restart
+  Gitlab::Cluster::LifecycleEvents.do_master_restart
+end
+
+before_fork do
+  # Signal to the puma killer
+  Gitlab::Cluster::PumaWorkerKillerInitializer.start @config.options unless ENV['DISABLE_PUMA_WORKER_KILLER']
+
+  # Signal application hooks that we're about to fork
+  Gitlab::Cluster::LifecycleEvents.do_before_fork
+end
+
+Gitlab::Cluster::LifecycleEvents.set_puma_options @config.options
+on_worker_boot do
+  # Signal application hooks of worker start
+  Gitlab::Cluster::LifecycleEvents.do_worker_start
+end
+
+# Preload the application before starting the workers; this conflicts with
+# phased restart feature. (off by default)
+preload_app!
+
+tag 'gitlab-puma-worker'
+
+# Verifies that all workers have checked in to the master process within
+# the given timeout. If not the worker process will be restarted. Default
+# value is 60 seconds.
+#
+worker_timeout 60
diff --git a/doc/install/installation.md b/doc/install/installation.md
index 9548aee5fe3..a96ea78bdf5 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -434,7 +434,8 @@ sudo -u git -H editor config/resque.yml
 ```
 
 CAUTION: **Caution:**
-Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup.
+Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup. 
+If you want to use Puma web server, see [Using Puma](#using-puma) for the additional steps.
 
 NOTE: **Note:**
 If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps.
@@ -875,6 +876,25 @@ You also need to change the corresponding options (e.g. `ssh_user`, `ssh_host`,
 
 Apart from the always supported markdown style, there are other rich text files that GitLab can display. But you might have to install a dependency to do so. See the [github-markup gem README](https://github.com/gitlabhq/markup#markups) for more information.
 
+### Using Puma
+
+Puma is a multi-threaded HTTP 1.1 server for Ruby applications.
+
+To use GitLab with Puma:
+
+1. Finish GitLab setup so you have it up and running.
+1. Copy the supplied example Puma config file into place:
+
+   ```sh
+   cd /home/git/gitlab
+
+   # Copy config file for the web server
+   sudo -u git -H config/puma.rb.example config/puma.rb
+   ```
+
+1. Edit the system `init.d` script to use `EXPERIMENTAL_PUMA=1` flag. If you have `/etc/default/gitlab`, then you should edit it instead.
+1. Restart GitLab.
+
 ## Troubleshooting
 
 ### "You appear to have cloned an empty repository."
diff --git a/lib/support/init.d/gitlab b/lib/support/init.d/gitlab
index 2f2de083dc0..32df74f104a 100755
--- a/lib/support/init.d/gitlab
+++ b/lib/support/init.d/gitlab
@@ -1,8 +1,8 @@
 #! /bin/sh
 
 # GITLAB
-# Maintainer: @randx
-# Authors: rovanion.luckey@gmail.com, @randx
+# Maintainer: @dzaporozhets
+# Authors: rovanion.luckey@gmail.com, @dzaporozhets
 
 ### BEGIN INIT INFO
 # Provides:          gitlab
@@ -26,6 +26,7 @@
 
 ### Environment variables
 RAILS_ENV="production"
+EXPERIMENTAL_PUMA=""
 
 # Script variable names should be lower-case not to conflict with
 # internal /bin/sh variables such as PATH, EDITOR or SHELL.
@@ -75,7 +76,7 @@ check_pids(){
     echo "Could not create the path $pid_path needed to store the pids."
     exit 1
   fi
-  # If there exists a file which should hold the value of the Unicorn pid: read it.
+  # If there exists a file which should hold the value of the web server pid: read it.
   if [ -f "$web_server_pid_path" ]; then
     wpid=$(cat "$web_server_pid_path")
   else
@@ -198,7 +199,7 @@ check_stale_pids(){
   # If there is a pid it is something else than 0, the service is running if
   # *_status is == 0.
   if [ "$wpid" != "0" ] && [ "$web_status" != "0" ]; then
-    echo "Removing stale Unicorn web server pid. This is most likely caused by the web server crashing the last time it ran."
+    echo "Removing stale web server pid. This is most likely caused by the web server crashing the last time it ran."
     if ! rm "$web_server_pid_path"; then
       echo "Unable to remove stale pid, exiting."
       exit 1
@@ -250,12 +251,12 @@ exit_if_not_running(){
   fi
 }
 
-## Starts Unicorn and Sidekiq if they're not running.
+## Starts web server and Sidekiq if they're not running.
 start_gitlab() {
   check_stale_pids
 
   if [ "$web_status" != "0" ]; then
-    echo "Starting GitLab Unicorn"
+    echo "Starting GitLab web server"
   fi
   if [ "$sidekiq_status" != "0" ]; then
     echo "Starting GitLab Sidekiq"
@@ -275,12 +276,12 @@ start_gitlab() {
 
   # Then check if the service is running. If it is: don't start again.
   if [ "$web_status" = "0" ]; then
-    echo "The Unicorn web server already running with pid $wpid, not restarting."
+    echo "The web server already running with pid $wpid, not restarting."
   else
     # Remove old socket if it exists
     rm -f "$rails_socket" 2>/dev/null
     # Start the web server
-    RAILS_ENV=$RAILS_ENV bin/web start
+    RAILS_ENV=$RAILS_ENV EXPERIMENTAL_PUMA=$EXPERIMENTAL_PUMA bin/web start
   fi
 
   # If sidekiq is already running, don't start it again.
@@ -336,13 +337,13 @@ start_gitlab() {
   print_status
 }
 
-## Asks Unicorn, Sidekiq and MailRoom if they would be so kind as to stop, if not kills them.
+## Asks web server, Sidekiq and MailRoom if they would be so kind as to stop, if not kills them.
 stop_gitlab() {
   exit_if_not_running
 
   if [ "$web_status" = "0" ]; then
-    echo "Shutting down GitLab Unicorn"
-    RAILS_ENV=$RAILS_ENV bin/web stop
+    echo "Shutting down GitLab web server"
+    RAILS_ENV=$RAILS_ENV EXPERIMENTAL_PUMA=$EXPERIMENTAL_PUMA bin/web stop
   fi
   if [ "$sidekiq_status" = "0" ]; then
     echo "Shutting down GitLab Sidekiq"
@@ -398,9 +399,9 @@ print_status() {
     return
   fi
   if [ "$web_status" = "0" ]; then
-      echo "The GitLab Unicorn web server with pid $wpid is running."
+      echo "The GitLab web server with pid $wpid is running."
   else
-      printf "The GitLab Unicorn web server is \033[31mnot running\033[0m.\n"
+      printf "The GitLab web server is \033[31mnot running\033[0m.\n"
   fi
   if [ "$sidekiq_status" = "0" ]; then
       echo "The GitLab Sidekiq job dispatcher with pid $spid is running."
@@ -438,15 +439,15 @@ print_status() {
   fi
 }
 
-## Tells unicorn to reload its config and Sidekiq to restart
+## Tells web server to reload its config and Sidekiq to restart
 reload_gitlab(){
   exit_if_not_running
   if [ "$wpid" = "0" ];then
-    echo "The GitLab Unicorn Web server is not running thus its configuration can't be reloaded."
+    echo "The GitLab web server Web server is not running thus its configuration can't be reloaded."
     exit 1
   fi
-  printf "Reloading GitLab Unicorn configuration... "
-  RAILS_ENV=$RAILS_ENV bin/web reload
+  printf "Reloading GitLab web server configuration... "
+  RAILS_ENV=$RAILS_ENV EXPERIMENTAL_PUMA=$EXPERIMENTAL_PUMA bin/web reload
   echo "Done."
 
   echo "Restarting GitLab Sidekiq since it isn't capable of reloading its config..."
@@ -461,7 +462,7 @@ reload_gitlab(){
   print_status
 }
 
-## Restarts Sidekiq and Unicorn.
+## Restarts Sidekiq and web server.
 restart_gitlab(){
   check_status
   if [ "$web_status" = "0" ] || [ "$sidekiq_status" = "0" ] || [ "$gitlab_workhorse" = "0" ] || { [ "$mail_room_enabled" = true ] && [ "$mail_room_status" = "0" ]; } || { [ "$gitlab_pages_enabled" = true ] && [ "$gitlab_pages_status" = "0" ]; } || { [ "$gitaly_enabled" = true ] && [ "$gitaly_status" = "0" ]; }; then
diff --git a/lib/support/init.d/gitlab.default.example b/lib/support/init.d/gitlab.default.example
index 295c79fccfc..ab41dba3017 100644
--- a/lib/support/init.d/gitlab.default.example
+++ b/lib/support/init.d/gitlab.default.example
@@ -5,6 +5,9 @@
 # Normal values are "production", "test" and "development".
 RAILS_ENV="production"
 
+# Uncomment the line below to enable Puma web server instead of Unicorn.
+# EXPERIMENTAL_PUMA=1
+
 # app_user defines the user that GitLab is run as.
 # The default is "git".
 app_user="git"