Merge branch '18775-aqualls-document-nginx' into 'master'

Add troubleshooting info for reverse proxies

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/168576



Merged-by: Phillip Wells <pwells@gitlab.com>
Approved-by: Kerri Miller <kerrizor@kerrizor.com>
Approved-by: Phillip Wells <pwells@gitlab.com>
Co-authored-by: Amy Qualls <aqualls@gitlab.com>
Co-authored-by: Jay McCure <jmccure@gitlab.com>

doc/api/rest/troubleshooting.md

@@ -165,3 +165,67 @@ REST API requests can be detected as spam. If a request is detected as spam and:
     "https://gitlab.example.com/api/v4/snippets?
     title=Title&file_name=FileName&content=Content&visibility=public"
     ```
+
+## Error: `404 Not Found` when using a reverse proxy
+
+If your GitLab instance uses a reverse proxy, you might see `404 Not Found` errors when
+using a GitLab [editor extension](../../editor_extensions/index.md), the GitLab CLI, or
+API calls with URL-encoded parameters.
+
+This problem occurs when your reverse proxy decodes characters like `/`, `?`, and `@`
+before passing the parameters on to GitLab.
+
+To resolve this problem, edit the configuration for your reverse proxy:
+
+- In the `VirtualHost` section, add `AllowEncodedSlashes NoDecode`.
+- In the `Location` section, edit `ProxyPass` and add the `nocanon` flag.
+
+For example:
+
+::Tabs
+
+:::TabTitle Apache configuration
+
+```plaintext
+<VirtualHost *:443>
+  ServerName git.example.com
+
+  SSLEngine on
+  SSLCertificateFile     /etc/letsencrypt/live/git.example.com/fullchain.pem
+  SSLCertificateKeyFile  /etc/letsencrypt/live/git.example.com/privkey.pem
+  SSLVerifyClient None
+
+  ProxyRequests     Off
+  ProxyPreserveHost On
+  AllowEncodedSlashes NoDecode
+
+  <Location />
+     ProxyPass http://127.0.0.1:8080/ nocanon
+     ProxyPassReverse http://127.0.0.1:8080/
+     Order deny,allow
+     Allow from all
+  </Location>
+</VirtualHost>
+```
+
+:::TabTitle NGINX configuration
+
+```plaintext
+server {
+  listen       80;
+  server_name  gitlab.example.com;
+  location / {
+     proxy_pass    http://ip:port;
+     proxy_set_header        X-Forwarded-Proto $scheme;
+     proxy_set_header        Host              $http_host;
+     proxy_set_header        X-Real-IP         $remote_addr;
+     proxy_set_header        X-Forwarded-For   $proxy_add_x_forwarded_for;
+     proxy_read_timeout    300;
+     proxy_connect_timeout 300;
+  }
+}
+```
+
+::EndTabs
+
+For more information, see [issue 18775](https://gitlab.com/gitlab-org/gitlab/-/issues/18775).

doc/install/installation.md

@@ -1116,6 +1116,9 @@ You can add trusted proxies in `config/gitlab.yml` by customizing the `trusted_p
 option in section 1. Save the file and [reconfigure GitLab](../administration/restart_gitlab.md)
 for the changes to take effect.
+If you encounter problems with improperly encoded characters in URLs, see
+[Error: `404 Not Found` when using a reverse proxy](../api/rest/troubleshooting.md#error-404-not-found-when-using-a-reverse-proxy).
+
 ### Custom Redis Connection
 If you'd like to connect to a Redis server on a non-standard port or a different host, you can configure its connection string via the `config/resque.yml` file.