Fix incoming links to running-a-rails-console

References to the 'how to run a rails console' sections of the two
existing documents are redirected to relevant section of the new
document.

doc/administration/auth/ldap/ldap-troubleshooting.md

@@ -682,7 +682,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](../../troubleshooting/debug.md#starting-a-rails-console-session)
+Please refer to [this guide](../../operations/rails_console.md#starting-a-rails-console-session)
 for instructions on how to use the rails console.
 
 #### Enable debug output

doc/administration/feature_flags.md

@@ -65,7 +65,7 @@ For installations from the source:
 sudo -u git -H bundle exec rails console -e production
 ```
 
-For details, see [starting a Rails console session](troubleshooting/debug.md#starting-a-rails-console-session).
+For details, see [starting a Rails console session](operations/rails_console.md#starting-a-rails-console-session).
 
 ### Enable or disable the feature
 

doc/administration/instance_limits.md

@@ -163,7 +163,7 @@ There is a limit when embedding metrics in GFM for performance reasons.
 On GitLab.com, the [maximum number of webhooks and their size](../user/gitlab_com/index.md#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](troubleshooting/debug.md#starting-a-rails-console-session):
+[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 # If limits don't exist for the default plan, you can create one with:
@@ -203,7 +203,7 @@ support keyset-based pagination. More information about pagination options can b
 found in the [API docs section on pagination](../api/README.md#pagination).
 
 To set this limit on a self-managed installation, run the following in the
-[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
+[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 # If limits don't exist for the default plan, you can create one with:
@@ -238,7 +238,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](troubleshooting/debug.md#starting-a-rails-console-session):
+[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 # If limits don't exist for the default plan, you can create one with:
@@ -264,7 +264,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](troubleshooting/debug.md#starting-a-rails-console-session):
+[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 Plan.default.actual_limits.update!(ci_project_subscriptions: 500)
@@ -290,7 +290,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](troubleshooting/debug.md#starting-a-rails-console-session):
+[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 Plan.default.actual_limits.update!(ci_pipeline_schedules: 100)
@@ -308,7 +308,7 @@ On self-managed instances this limit is defined for the `default` plan. By defau
 this limit is set to `25`.
 
 To update this limit to a new value on a self-managed installation, run the following in the
-[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
+[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 Plan.default.actual_limits.update!(ci_instance_level_variables: 30)
@@ -361,7 +361,7 @@ setting is used:
 | `ci_max_artifact_size_trace`                | 0             |
 
 For example, to set the `ci_max_artifact_size_junit` limit to 10MB on a self-managed
-installation, run the following in the [GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
+installation, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 Plan.default.actual_limits.update!(ci_max_artifact_size_junit: 10)
@@ -538,7 +538,7 @@ On GitLab.com, the maximum file size for a package that's uploaded to the [GitLa
 - PyPI: 3GB
 
 To set this limit on a self-managed installation, run the following in the
-[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session):
+[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 # File size limit is stored in bytes

doc/administration/operations/rails_console.md

+# The Rails Console
+
+The [Rails console](https://guides.rubyonrails.org/command_line.html#rails-console).
+provides a way to interact with your GitLab instance from the command line.
+
+CAUTION: **Caution:**
+The Rails console interacts directly with GitLab. In many cases,
+there are no handrails to prevent you from permanently modifying, corrupting
+or destroying production data. If you would like to explore the Rails console
+with no consequences, you are strongly advised to do so in a test environment.
+
+The Rails console is for GitLab system administrators who are troubleshooting
+a problem or need to retrieve some data that can only be done through direct
+access of the GitLab application.
+
+## Starting a Rails console session
+
+**For Omnibus installations**
+
+```shell
+sudo gitlab-rails console
+```
+
+**For installations from source**
+
+```shell
+sudo -u git -H bundle exec rails console -e production
+```
+
+**For Kubernetes deployments**
+
+The console is in the task-runner pod. Refer to our [Kubernetes cheat sheet](../troubleshooting/kubernetes_cheat_sheet.md#gitlab-specific-kubernetes-information) for details.
+
+To exit the console, type: `quit`.
+
+## Output Rails console session history
+
+Enter the following command on the rails console to display
+your command history.
+
+```ruby
+puts Readline::HISTORY.to_a
+```
+
+You can then copy it to your clipboard and save for future reference.
+
+## Using the Rails Runner
+
+If you need to run some Ruby code in the context of your GitLab production
+environment, you can do so using the [Rails Runner](https://guides.rubyonrails.org/command_line.html#rails-runner).
+When executing a script file, the script must be accessible by the `git` user.
+
+When the command or script completes, the Rails Runner process finishes.
+It is useful for running within other scripts or cron jobs for example.
+
+**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"
+
+# Example with a ruby script file (make sure to use the full path)
+sudo gitlab-rails runner /path/to/script.rb
+```
+
+**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"
+
+# Example with a ruby script file (make sure to use the full path)
+sudo -u git -H bundle exec rails runner -e production /path/to/script.rb
+```
+
+Rails Runner does not produce the same output as the console.
+
+If you set a variable on the console, the console will generate useful debug output
+such as the variable contents or properties of referenced entity:
+
+```ruby
+irb(main):001:0> user = User.first
+=> #<User id:1 @root>
+```
+
+Rails Runner does not do this: you have to be explicit about generating
+output:
+
+```shell
+$ sudo gitlab-rails runner "user = User.first"
+$ sudo gitlab-rails runner "user = User.first; puts user.username ; puts user.id"
+root
+1
+```
+
+Some basic knowledge of Ruby will be very useful. Try [this
+30-minute tutorial](https://try.ruby-lang.org/) for a quick introduction.
+Rails experience is helpful but not essential.
+
+### Troubleshooting Rails Runner
+
+The `gitlab-rails` command executes Rails Runner using a non-root account and group, by default: `git:git`.
+
+If the non-root account cannot find the Ruby script filename passed to `gitlab-rails runner`
+you may get a syntax error, not an error that the file couldn't be accessed.
+
+A common reason for this is that the script has been put in the root account's home directory.
+
+`runner` tries to parse the path and file parameter as Ruby code.
+
+For example:
+
+```plaintext
+[root ~]# echo 'puts "hello world"' > ./helloworld.rb
+[root ~]# sudo gitlab-rails runner ./helloworld.rb
+Please specify a valid ruby command or the path of a script to run.
+Run 'rails runner -h' for help.
+
+/opt/gitlab/..../runner_command.rb:45: syntax error, unexpected '.'
+./helloworld.rb
+^
+[root ~]# sudo gitlab-rails runner /root/helloworld.rb
+Please specify a valid ruby command or the path of a script to run.
+Run 'rails runner -h' for help.
+
+/opt/gitlab/..../runner_command.rb:45: unknown regexp options - hllwrld
+[root ~]# mv ~/helloworld.rb /tmp
+[root ~]# sudo gitlab-rails runner /tmp/helloworld.rb
+hello world
+```
+
+A meaningful error should be generated if the directory can be accessed, but the file cannot:
+
+```plaintext
+[root ~]# chmod 400 /tmp/helloworld.rb
+[root ~]# sudo gitlab-rails runner /tmp/helloworld.rb
+Traceback (most recent call last):
+      [traceback removed]
+/opt/gitlab/..../runner_command.rb:42:in `load': cannot load such file -- /tmp/helloworld.rb (LoadError)
+```

doc/administration/raketasks/check.md

@@ -148,7 +148,7 @@ above.
 for the affected project(s).
 
 If the issue persists, try triggering `gc` via the
-[Rails Console](../troubleshooting/navigating_gitlab_via_rails_console.md#starting-a-rails-console-session):
+[Rails Console](../operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 p = Project.find_by_path("project-name")
@@ -171,7 +171,7 @@ Checking integrity of Uploads
 Done!
 ```
 
-To delete these references to remote uploads that were deleted externally, open the [GitLab Rails Console](../troubleshooting/navigating_gitlab_via_rails_console.md#starting-a-rails-console-session) and run:
+To delete these references to remote uploads that were deleted externally, open the [GitLab Rails Console](../operations/rails_console.md#starting-a-rails-console-session) and run:
 
 ```ruby
 uploads_deleted=0

doc/administration/repository_storage_types.md

@@ -83,7 +83,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-session),
+In a [Rails console](operations/rails_console.md#starting-a-rails-console-session),
 get this information using either the numeric project ID or the full path:
 
 ```ruby
@@ -95,7 +95,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-session).
+1. Start a [Rails console](operations/rails_console.md#starting-a-rails-console-session).
 1. Run the following:
 
 ```ruby

doc/administration/troubleshooting/debug.md

@@ -5,27 +5,15 @@ in production.
 
 ## Starting a Rails console session
 
-Troubleshooting and debugging your GitLab instance often requires a
-[Rails console](https://guides.rubyonrails.org/command_line.html#rails-console).
+Troubleshooting and debugging your GitLab instance often requires a Rails console.
+
+Your type of GitLab installation determines how
+[to start a rails console](../operations/rails_console.md).
 See also:
 
 - [GitLab Rails Console Cheat Sheet](gitlab_rails_cheat_sheet.md).
 - [Navigating GitLab via Rails console](navigating_gitlab_via_rails_console.md).
 
-**For Omnibus installations**
-
-```shell
-sudo gitlab-rails console
-```
-
-**For installations from source**
-
-```shell
-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
@@ -98,7 +86,7 @@ sudo -u git -H bundle exec rails runner -e production /path/to/script.rb
 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-session).
+1. Run a [Rails console](../operations/rails_console.md#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
@@ -238,7 +226,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-session)
+1. Bring up the [GitLab Rails console.](../operations/rails_console.md#starting-a-rails-console-session)
 1. At the Rails console, run:
 
    ```ruby

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](debug.md#starting-a-rails-console-session)
+In this guide, we'll introduce the [Rails console](../operations/rails_console.md#starting-a-rails-console-session)
 and the basics of interacting with your GitLab instance from the command line.
 
 CAUTION: **Caution:**
@@ -20,20 +20,10 @@ Rails experience is helpful to have but not a must.
 
 ## Starting a Rails console session
 
-Omnibus GitLab comes with a convenient wrapper command which automatically loads
-the production GitLab environment:
+Your type of GitLab installation determines how
+[to start a rails console](../operations/rails_console.md).
 
-```shell
-sudo gitlab-rails console
-```
-
-For source installations, you'll have to instead run:
-
-```shell
-sudo -u git -H bundle exec rails console -e production
-```
-
-Further code examples will all take place inside the Rails console and also
+The following code examples will all take place inside the Rails console and also
 assume an Omnibus GitLab installation.
 
 ## Active Record objects

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](debug.md#starting-a-rails-console-session) also fails:
+- Testing via the [rails console](../operations/rails_console.md#starting-a-rails-console-session) also fails:
 
   ```ruby
   uri = URI.parse("https://gitlab.domain.tld")

doc/integration/github.md

@@ -150,7 +150,7 @@ via Omnibus, or [restart GitLab](../administration/restart_gitlab.md#installatio
 Check the [`production.log`](../administration/logs.md#productionlog)
 on your GitLab server to obtain further details. If you are getting the error like
 `Faraday::ConnectionFailed (execution expired)` in the log, there may be a connectivity issue
-between your GitLab instance and GitHub Enterprise. To verify it, [start the rails console](../administration/troubleshooting/debug.md#starting-a-rails-console-session)
+between your GitLab instance and GitHub Enterprise. To verify it, [start the rails console](../administration/operations/rails_console.md#starting-a-rails-console-session)
 and run the commands below replacing `<github_url>` with the URL of your GitHub Enterprise instance:
 
 ```ruby

doc/raketasks/import.md

@@ -131,7 +131,7 @@ Bare repositories are **not** importable by GitLab 10.4 to GitLab 11.6, if all t
 bare repositories are importable.
 
 To manually migrate repositories yourself (for GitLab 10.4 to GitLab 11.6), you can use the
-[Rails console](../administration/troubleshooting/debug.md#starting-a-rails-console-session)
+[Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session)
 to do so. In a Rails console session, run the following to migrate a project:
 
 ```ruby

doc/security/project_import_decompressed_archive_size_limits.md

@@ -17,7 +17,7 @@ If you have a project with decompressed size exceeding this limit,
 it is possible to disable the validation by turning off the
 `validate_import_decompressed_archive_size` feature flag.
 
-Start a [Rails console](../administration/troubleshooting/debug.md#starting-a-rails-console-session).
+Start a [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session).
 
 ```ruby
 # Disable

doc/update/README.md

@@ -123,7 +123,7 @@ If using GitLab 12.9 and newer, run:
 sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
 ```
 
-If using GitLab 12.8 and older, run the following using a [Rails console](../administration/troubleshooting/debug.md#starting-a-rails-console-session):
+If using GitLab 12.8 and older, run the following using a [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 puts Sidekiq::Queue.new("background_migration").size
@@ -141,7 +141,7 @@ cd /home/git/gitlab
 sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
 ```
 
-If using GitLab 12.8 and older, run the following using a [Rails console](../administration/troubleshooting/debug.md#starting-a-rails-console-session):
+If using GitLab 12.8 and older, run the following using a [Rails console](../administration/operations/rails_console.md#starting-a-rails-console-session):
 
 ```ruby
 puts Sidekiq::Queue.new("background_migration").size

doc/user/packages/container_registry/index.md

@@ -461,7 +461,7 @@ Cleanup policies can be run on all projects, with these exceptions:
   for all projects (even those created before 12.8) in
   [GitLab application settings](../../../api/settings.md#change-application-settings)
   by setting `container_expiration_policies_enable_historic_entries` to true.
-  Alternatively, you can execute the following command in the [Rails console](../../../administration/troubleshooting/navigating_gitlab_via_rails_console.md#starting-a-rails-console-session):
+  Alternatively, you can execute the following command in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session):
 
   ```ruby
   ApplicationSetting.last.update(container_expiration_policies_enable_historic_entries: true)

doc/user/profile/personal_access_tokens.md

@@ -71,7 +71,7 @@ the following table.
 
 You can programmatically create a predetermined personal access token for use in
 automation or tests. You need sufficient access to run a
-[Rails console session](../../administration/troubleshooting/debug.md#starting-a-rails-console-session)
+[Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session)
 for your GitLab instance.
 
 To create a token belonging to a user with username `automation-bot`, run the
@@ -101,7 +101,7 @@ The list of valid scopes and what they do can be found
 ## Programmatically revoking a personal access token
 
 You can programmatically revoke a personal access token. You need
-sufficient access to run a [Rails console session](../../administration/troubleshooting/debug.md#starting-a-rails-console-session)
+sufficient access to run a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session)
 for your GitLab instance.
 
 To revoke a known token `token-string-here123`, run the following in the Rails

doc/user/upgrade_email_bypass.md

@@ -82,7 +82,7 @@ As an administrator, you may also confirm a user in the [Admin Area](admin_area/
 ## What do I do if I am an administrator and I am locked out?
 
 If you are an administrator and cannot otherwise verify your email address, sign in to your GitLab
-instance with a [Rails console session](../administration/troubleshooting/navigating_gitlab_via_rails_console.md#starting-a-rails-console-session).
+instance with a [Rails console session](../administration/operations/rails_console.md#starting-a-rails-console-session).
 Once connected, run the following commands to confirm your administrator account:
 
 ```ruby
@@ -94,7 +94,7 @@ admin.save!
 ## How do I force-confirm all users on my self-managed instance?
 
 If you are an administrator and would like to force-confirm all users on your system, sign in to your GitLab
-instance with a [Rails console session](../administration/troubleshooting/navigating_gitlab_via_rails_console.md#starting-a-rails-console-session).
+instance with a [Rails console session](../administration/operations/rails_console.md#starting-a-rails-console-session).
 Once connected, run the following commands to confirm all user accounts:
 
 ```ruby