Merge branch 'docs/add-reverse-proxy-advice-nginx' into 'master'

Add details for using NGINX as reverse proxy

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

Merged-by: Balasankar 'Balu' C <[email protected]>
Approved-by: João Alexandre Cunha <[email protected]>
Approved-by: Evan Read <[email protected]>
Approved-by: Balasankar 'Balu' C <[email protected]>
Reviewed-by: Evan Read <[email protected]>
Co-authored-by: Anton Smith <[email protected]>
Co-authored-by: Evan Read <[email protected]>
Co-authored-by: Kenneth Chu <[email protected]>

Author: 4 people

doc/settings/nginx.md

@@ -351,16 +351,30 @@ existing server blocks, you can use the following setting.
 
 ```ruby
 # Example: include a directory to scan for additional config files
-nginx['custom_nginx_config'] = "include /etc/nginx/conf.d/*.conf;"
+nginx['custom_nginx_config'] = "include /etc/gitlab/nginx/sites-enabled/*.conf;"
 ```
 
+You should create custom server blocks in the `/etc/gitlab/nginx/sites-available` directory. To enable them, symlink them into the
+`/etc/gitlab/nginx/sites-enabled` directory:
+
+1. Create the `/etc/gitlab/nginx/sites-enabled` directory.
+1. Run the following command:
+
+   ```shell
+   sudo ln -s /etc/gitlab/nginx/sites-available/example.conf /etc/gitlab/nginx/sites-enabled/example.conf 
+   ```
+
+You can add domains for server blocks [as an alternative name](ssl/index.md#add-alternative-domains-to-the-certificate)
+to the generated Let's Encrypt SSL certificate.
+
 Run `gitlab-ctl reconfigure` to rewrite the NGINX configuration and restart
-NGINX.
+NGINX. You must reload NGINX (`gitlab-ctl hup nginx`) or restart NGINX (`gitlab-ctl restart nginx`) whenever you make changes to the custom server blocks.
 
 This inserts the defined string into the end of the `http` block of
 `/var/opt/gitlab/nginx/conf/nginx.conf`.
 
-Consider including your custom NGINX configuration file in `/etc/gitlab/` so the custom configuration is backed up.
+Custom NGINX settings inside the `/etc/gitlab/` directory are backed up to `/etc/gitlab/config_backup/`
+during an upgrade and when `sudo gitlab-ctl backup-etc` is manually executed.
 
 ## Custom error pages
 

doc/settings/ssl/index.md

@@ -169,6 +169,35 @@ To configure GitLab to use a custom ACME server:
    sudo gitlab-ctl reconfigure
    ```
 
+### Add alternative domains to the certificate
+
+You can add alternative domains (or subject alternative names) to the Let's Encrypt certificate.
+This can be helpful if you would like to use the [bundled NGINX](../nginx.md) as a
+[reverse proxy for other backend applications](../nginx.md#inserting-custom-settings-into-the-nginx-configuration).
+
+The DNS records for the alternative domains must point to the GitLab instance.
+
+To add alternative domains to your Let's Encrypt certificate:
+
+1. Edit `/etc/gitlab/gitlab.rb` and add the alternative domains:
+
+    ```ruby
+    # Separate multiple domains with commas
+    letsencrypt['alt_names'] = ['another-application.example.com']
+    ```
+
+1. Reconfigure GitLab:
+
+   ```shell
+   sudo gitlab-ctl reconfigure
+   ```  
+
+The resulting Let's Encrypt certificates generated for the main GitLab application will
+include the alternative domains specified. The generated files are located at:
+
+- `/etc/gitlab/ssl/gitlab.example.com.key` for the key.
+- `/etc/gitlab/ssl/gitlab.example.com.crt` for the certificate.
+
 ## Configure HTTPS manually
 
 WARNING:

files/gitlab-config-template/gitlab.rb.template

@@ -2702,6 +2702,7 @@ external_url 'GENERATED_EXTERNAL_URL'
 # letsencrypt['auto_renew_minute'] = nil # Should be a number or cron expression, if specified.
 # letsencrypt['auto_renew_day_of_month'] = "*/4"
 # letsencrypt['auto_renew_log_directory'] = '/var/log/gitlab/lets-encrypt'
+# letsencrypt['alt_names'] = []
 
 ##! Turn off automatic init system detection. To skip init detection in
 ##! non-docker containers. Recommended not to change.