Add latest changes from gitlab-org/gitlab@master

12 files changed, 76 insertions, 52 deletions

diff --git a/doc/administration/auth/ldap-troubleshooting.md b/doc/administration/auth/ldap-troubleshooting.md
index 01c22711efc..b852140e80a 100644
--- a/doc/administration/auth/ldap-troubleshooting.md
+++ b/doc/administration/auth/ldap-troubleshooting.md
@@ -634,7 +634,7 @@ The rails console is a valuable tool to help debug LDAP problems. It allows you
 directly interact with the application by running commands and seeing how GitLab
 responds to them.
 
-Please refer to [this guide](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session)
+Please refer to [this guide](../troubleshooting/debug.md#starting-a-rails-console-session)
 for instructions on how to use the rails console.
 
 #### Enable debug output
diff --git a/doc/administration/img/repository_storages_admin_ui_v12_10.png b/doc/administration/img/repository_storages_admin_ui_v12_10.png
index b66e2c598bc..e5ac09524b8 100644
--- a/doc/administration/img/repository_storages_admin_ui_v12_10.png
+++ b/doc/administration/img/repository_storages_admin_ui_v12_10.png
diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md
index c53c46bf0cb..22f2d6ca0b9 100644
--- a/doc/administration/instance_limits.md
+++ b/doc/administration/instance_limits.md
@@ -70,7 +70,7 @@ There is a limit when embedding metrics in GFM for performance reasons.
 On GitLab.com, the [maximum number of webhooks](../user/gitlab_com/index.md#maximum-number-of-webhooks) per project, and per group, is limited.
 
 To set this limit on a self-managed installation, run the following in the
-[GitLab Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session):
+[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
 
 ```ruby
 # If limits don't exist for the default plan, you can create one with:
@@ -120,7 +120,7 @@ will fail with a `job_activity_limit_exceeded` error.
   This limit is disabled by default.
 
 To set this limit on a self-managed installation, run the following in the
-[GitLab Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session):
+[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
 
 ```ruby
 # If limits don't exist for the default plan, you can create one with:
@@ -145,7 +145,7 @@ limit, the subscription will be considered invalid.
 - On [GitLab Starter](https://about.gitlab.com/pricing/#self-managed) tier or higher self-managed installations, this limit is defined for the `default` plan that affects all projects.
 
 To set this limit on a self-managed installation, run the following in the
-[GitLab Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session):
+[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
 
 ```ruby
 Plan.default.limits.update!(ci_project_subscriptions: 500)
@@ -170,7 +170,7 @@ or higher tiers), this limit is defined for the `default` plan that affects all
 projects. By default, there is no limit.
 
 To set this limit on a self-managed installation, run the following in the
-[GitLab Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session):
+[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
 
 ```ruby
 Plan.default.limits.update!(ci_pipeline_schedules: 100)
diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md
index 29b4179a3f7..562f653765a 100644
--- a/doc/administration/repository_storage_types.md
+++ b/doc/administration/repository_storage_types.md
@@ -100,7 +100,7 @@ The "Gitaly relative path" is shown there, for example:
 This is the path under `/var/opt/gitlab/git-data/repositories/` on a
 default Omnibus installation.
 
-In a [Rails console](troubleshooting/debug.md#starting-a-rails-console),
+In a [Rails console](troubleshooting/debug.md#starting-a-rails-console-session),
 get this information using either the numeric project ID or the full path:
 
 ```ruby
@@ -112,7 +112,7 @@ Project.find_by_full_path('group/project').disk_path
 
 To translate from a hashed storage path to a project name:
 
-1. Start a [Rails console](troubleshooting/debug.md#starting-a-rails-console).
+1. Start a [Rails console](troubleshooting/debug.md#starting-a-rails-console-session).
 1. Run the following:
 
 ```ruby
diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md
index 6a22b22a5be..295dab2be38 100644
--- a/doc/administration/troubleshooting/debug.md
+++ b/doc/administration/troubleshooting/debug.md
@@ -3,9 +3,10 @@
 Sometimes things don't work the way they should. Here are some tips on debugging issues out
 in production.
 
-## Starting a Rails console
+## Starting a Rails console session
 
-Troubleshooting and debugging often requires a rails console.
+Troubleshooting and debugging your GitLab instance often requires a
+[Rails console](https://guides.rubyonrails.org/command_line.html#rails-console).
 
 **For Omnibus installations**
 
@@ -13,22 +14,81 @@ Troubleshooting and debugging often requires a rails console.
 sudo gitlab-rails console
 ```
 
----
-
 **For installations from source**
 
 ```shell
-bundle exec rails console production
+sudo -u git -H bundle exec rails console -e production
 ```
 
 Kubernetes: the console is in the task-runner pod, refer to our [Kubernetes cheat sheet](kubernetes_cheat_sheet.md#gitlab-specific-kubernetes-information) for details.
 
+### Enabling Active Record logging
+
+You can enable output of Active Record debug logging in the Rails console
+session by running:
+
+```ruby
+ActiveRecord::Base.logger = Logger.new(STDOUT)
+```
+
+This will show information about database queries triggered by any Ruby code
+you may run in the console. To turn off logging again, run:
+
+```ruby
+ActiveRecord::Base.logger = nil
+```
+
+### Disabling database statement timeout
+
+You can disable the PostgreSQL statement timeout for the current Rails console
+session by running:
+
+```ruby
+ActiveRecord::Base.connection.execute('SET statement_timeout TO 0')
+```
+
+Note that this change only affects the current Rails console session and will
+not be persisted in the GitLab production environment or in the next Rails
+console session.
+
+### Output Rails console session history
+
+If you'd like to output your Rails console command history in a format that's
+easy to copy and save for future reference, you can run:
+
+```ruby
+puts Readline::HISTORY.to_a
+```
+
+## Using the Rails Runner
+
+If you need to run some Ruby code in thex context of your GitLab production
+environment, you can do so using the [Rails Runner](https://guides.rubyonrails.org/command_line.html#rails-runner).
+
+**For Omnibus installations**
+
+```shell
+sudo gitlab-rails runner "RAILS_COMMAND"
+
+# Example with a two-line Ruby script
+sudo gitlab-rails runner "user = User.first; puts user.username"
+```
+
+**For installations from source**
+
+```shell
+sudo -u git -H bundle exec rails runner -e production "RAILS_COMMAND"
+
+# Example with a two-line Ruby script
+sudo -u git -H bundle exec rails runner -e production "user = User.first; puts user.username"
+```
+
 ## Mail not working
 
 A common problem is that mails are not being sent for some reason. Suppose you configured
 an SMTP server, but you're not seeing mail delivered. Here's how to check the settings:
 
-1. Run a [Rails console.](#starting-a-rails-console)
+1. Run a [Rails console](#starting-a-rails-console-session).
 
 1. Look at the ActionMailer `delivery_method` to make sure it matches what you
    intended. If you configured SMTP, it should say `:smtp`. If you're using
@@ -168,7 +228,7 @@ separate Rails process to debug the issue:
 1. Log in to your GitLab account.
 1. Copy the URL that is causing problems (e.g. `https://gitlab.com/ABC`).
 1. Create a Personal Access Token for your user (Profile Settings -> Access Tokens).
-1. Bring up the [GitLab Rails console.](#starting-a-rails-console)
+1. Bring up the [GitLab Rails console.](#starting-a-rails-console-session)
 1. At the Rails console, run:
 
    ```ruby
diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md
index 15ed436fb34..0471c7b7ffd 100644
--- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md
+++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md
@@ -25,36 +25,6 @@ mentioned above, we recommend running these scripts under the supervision of a
 Support Engineer, who can also verify that they will continue to work as they
 should and, if needed, update the script for the latest version of GitLab.
 
-## Use the Rails Runner
-
-If the script you want to run is short, you can use the Rails Runner to avoid
-entering the rails console in the first place. Here's an example of its use:
-
-```shell
-gitlab-rails runner "RAILS_COMMAND"
-
-# Example with a 2-line script
-gitlab-rails runner "user = User.first; puts user.username"
-```
-
-## Enable debug logging on rails console
-
-```ruby
-Rails.logger.level = 0
-```
-
-## Enable debug logging for ActiveRecord (db issues)
-
-```ruby
-ActiveRecord::Base.logger = Logger.new(STDOUT)
-```
-
-## Temporarily Disable Timeout
-
-```ruby
-ActiveRecord::Base.connection.execute('SET statement_timeout TO 0')
-```
-
 ## Find specific methods for an object
 
 ```ruby
@@ -85,12 +55,6 @@ o = Object.where('attribute like ?', 'ex')
 Rails.cache.instance_variable_get(:@data).keys
 ```
 
-## Rails console history
-
-```ruby
-puts Readline::HISTORY.to_a
-```
-
 ## Profile a page
 
 ```ruby
diff --git a/doc/administration/troubleshooting/img/Okta-SAMLsetup.png b/doc/administration/troubleshooting/img/Okta-SAMLsetup.png
index 8171febb5bc..1bd9bf4d7e9 100644
--- a/doc/administration/troubleshooting/img/Okta-SAMLsetup.png
+++ b/doc/administration/troubleshooting/img/Okta-SAMLsetup.png
diff --git a/doc/administration/troubleshooting/img/Okta-advancedsettings.png b/doc/administration/troubleshooting/img/Okta-advancedsettings.png
index 43eb546f238..45e378d1d12 100644
--- a/doc/administration/troubleshooting/img/Okta-advancedsettings.png
+++ b/doc/administration/troubleshooting/img/Okta-advancedsettings.png
diff --git a/doc/administration/troubleshooting/img/Okta-attributes.png b/doc/administration/troubleshooting/img/Okta-attributes.png
index e4a7b33fe55..a3405e4de9b 100644
--- a/doc/administration/troubleshooting/img/Okta-attributes.png
+++ b/doc/administration/troubleshooting/img/Okta-attributes.png
diff --git a/doc/administration/troubleshooting/img/Okta-linkscert.png b/doc/administration/troubleshooting/img/Okta-linkscert.png
index 33e6b3cc53e..38cae415f7e 100644
--- a/doc/administration/troubleshooting/img/Okta-linkscert.png
+++ b/doc/administration/troubleshooting/img/Okta-linkscert.png
diff --git a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md
index 01c3da80481..b78d5490cd2 100644
--- a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md
+++ b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md
@@ -3,7 +3,7 @@
 At the heart of GitLab is a web application [built using the Ruby on Rails
 framework](https://about.gitlab.com/blog/2018/10/29/why-we-use-rails-to-build-gitlab/).
 Thanks to this, we also get access to the amazing tools built right into Rails.
-In this guide, we'll introduce the [Rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session)
+In this guide, we'll introduce the [Rails console](debug.md#starting-a-rails-console-session)
 and the basics of interacting with your GitLab instance from the command line.
 
 CAUTION: **CAUTION:**
diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md
index 9474126e5c8..475b7d44eac 100644
--- a/doc/administration/troubleshooting/ssl.md
+++ b/doc/administration/troubleshooting/ssl.md
@@ -23,7 +23,7 @@ After configuring a GitLab instance with an internal CA certificate, you might n
   More details here: https://curl.haxx.se/docs/sslcerts.html
   ```
 
-- Testing via the [rails console](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session) also fails:
+- Testing via the [rails console](debug.md#starting-a-rails-console-session) also fails:
 
   ```ruby
   uri = URI.parse("https://gitlab.domain.tld")