Merge branch 'bprescott-hashedstorage-20200205' into 'master'

docs: commands for translating hashed repo path +SSOT for rails console

See merge request gitlab-org/gitlab!24453

doc/administration/repository_storage_types.md

@@ -78,6 +78,58 @@ by another folder with the next 2 characters. They are both stored in a special
 "@hashed/#{hash[0..1]}/#{hash[2..3]}/#{hash}.wiki.git"
 ```
 
+### Translating hashed storage paths
+
+Troubleshooting problems with the Git repositories, adding hooks, and other
+tasks will require you translate between the human readable project name
+and the hashed storage path.
+
+#### From project name to hashed path
+
+The hashed path is shown on the project's page in the [admin area](../user/admin_area/index.md#administering-projects).
+
+To access the Projects page, go to **Admin Area > Overview > Projects** and then
+open up the page for the project.
+
+The "Gitaly relative path" is shown there, for example:
+
+```
+"@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git"
+```
+
+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),
+get this information using either the numeric project ID or the full path:
+
+```ruby
+Project.find(16).disk_path
+Project.find_by_full_path('group/project').disk_path
+```
+
+#### From hashed path to project name
+
+To translate from a hashed storage path to a project name:
+
+1. Start a [Rails console](troubleshooting/debug.md#starting-a-rails-console).
+1. Run the following:
+
+```ruby
+ProjectRepository.find_by(disk_path: '@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9').project
+```
+
+The quoted string in that command is the directory tree you'll find on your
+GitLab server. For example, on a default Omnibus installation this would be
+`/var/opt/gitlab/git-data/repositories/@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git`
+with `.git` from the end of the directory name removed.
+
+The output includes the project id and the project name:
+
+```
+=> #<Project id:16 it/supportteam/ticketsystem>
+```
+
 ### Hashed object pools
 
 > [Introduced](https://gitlab.com/gitlab-org/gitaly/issues/1606) in GitLab 12.1.

doc/administration/server_hooks.md

@@ -96,6 +96,10 @@ The hooks are searched and executed in this order:
 The hooks of the same type are executed in order and execution stops on the
 first script exiting with a non-zero value.
 
+For `<project>.git` you'll need to
+[translate your project name into the hashed storage format](repository_storage_types.md#translating-hashed-storage-paths)
+that GitLab uses.
+
 ## Custom error messages
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5073) in GitLab 8.10.

doc/administration/troubleshooting/debug.md

@@ -3,22 +3,32 @@
 Sometimes things don't work the way they should. Here are some tips on debugging issues out
 in production.
 
-## Mail not working
+## Starting a Rails console
 
-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:
+Troubleshooting and debugging often requires a rails console.
 
-1. Run a Rails console:
+**For Omnibus installations**
 
-   ```shell
-   sudo gitlab-rails console -e production
-   ```
+```shell
+sudo gitlab-rails console
+```
 
-   or for source installs:
+---
 
-   ```shell
-   bundle exec rails console -e production
-   ```
+**For installations from source**
+
+```shell
+bundle exec rails console 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.
+
+## 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. 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
@@ -160,22 +170,17 @@ 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. For omnibus users, run:
-
-   ```shell
-   sudo gitlab-rails console
-   ```
-
+1. Bring up the [GitLab Rails console.](#starting-a-rails-console)
 1. At the Rails console, run:
 
    ```ruby
-   [1] pry(main)> app.get '<URL FROM STEP 2>/?private_token=<TOKEN FROM STEP 3>'
+   app.get '<URL FROM STEP 2>/?private_token=<TOKEN FROM STEP 3>'
    ```
 
    For example:
 
    ```ruby
-   [1] pry(main)> app.get 'https://gitlab.com/gitlab-org/gitlab-foss/issues/1?private_token=123456'
+   app.get 'https://gitlab.com/gitlab-org/gitlab-foss/issues/1?private_token=123456'
    ```
 
 1. In a new window, run `top`. It should show this ruby process using 100% CPU. Write down the PID.