Merge branch 'katrinleinweber-harmonise-pages-with-nfs-docs' into 'master'

Docs: Polish "Pages on separate server" setup

Closes gitlab-com/support/support-team-meta#2469

See merge request gitlab-org/gitlab!36282

doc/administration/high_availability/nfs_host_client_setup.md

@@ -38,10 +38,10 @@ In this setup we will share the home directory on the host with the client. Edit
 
 ```plaintext
 #/etc/exports for one client
-/home <client-ip-address>(rw,sync,no_root_squash,no_subtree_check)
+/home <client_ip_address>(rw,sync,no_root_squash,no_subtree_check)
 
 #/etc/exports for three clients
-/home <client-ip-address>(rw,sync,no_root_squash,no_subtree_check) <client-2-ip-address>(rw,sync,no_root_squash,no_subtree_check) <client-3-ip-address>(rw,sync,no_root_squash,no_subtree_check)
+/home <client_ip_address>(rw,sync,no_root_squash,no_subtree_check) <client_2_ip_address>(rw,sync,no_root_squash,no_subtree_check) <client_3_ip_address>(rw,sync,no_root_squash,no_subtree_check)
 ```
 
 Restart the NFS server after making changes to the `exports` file for the changes
@@ -54,7 +54,7 @@ systemctl restart nfs-kernel-server
 NOTE: **Note:**
 You may need to update your server's firewall. See the [firewall section](#nfs-in-a-firewalled-environment) at the end of this guide.
 
-## Client/ GitLab application node Setup
+## Client / GitLab application node Setup
 
 > Follow the instructions below to connect any GitLab Rails application node running
 inside your HA environment to the NFS server configured above.
@@ -90,7 +90,7 @@ df -h
 
 ### Step 3 - Set up Automatic Mounts on Boot
 
-Edit `/etc/fstab` on client as below to mount the remote shares automatically at boot.
+Edit `/etc/fstab` on the client as below to mount the remote shares automatically at boot.
 Note that GitLab requires advisory file locking, which is only supported natively in
 NFS version 4. NFSv3 also supports locking as long as Linux Kernel 2.6.5+ is used.
 We recommend using version 4 and do not specifically test NFSv3.
@@ -98,14 +98,19 @@ See [NFS documentation](nfs.md#nfs-client-mount-options) for guidance on mount o
 
 ```plaintext
 #/etc/fstab
-10.0.0.1:/nfs/home  /nfs/home  nfs4 defaults,hard,vers=4.1,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
+<host_ip_address>:/home  /nfs/home  nfs4 defaults,hard,vers=4.1,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2
 ```
 
 Reboot the client and confirm that the mount point is mounted automatically.
 
+NOTE: **Note:**
+If you followed our guide to [GitLab Pages on a separate server](../pages/index.md#running-gitlab-pages-on-a-separate-server)
+here, please continue there with the pages-specific NFS mounts.
+The step below is for broader use-cases than only sharing pages data.
+
 ### Step 4 - Set up GitLab to Use NFS mounts
 
-When using the default Omnibus configuration you will need to share 5 data locations
+When using the default Omnibus configuration you will need to share 4 data locations
 between all GitLab cluster nodes. No other locations should be shared. Changing the
 default file locations in `gitlab.rb` on the client allows you to have one main mount
 point and have all the required locations as subdirectories to use the NFS mount for
@@ -136,7 +141,7 @@ the command: `sudo ufw status`. If it's being blocked, then you can allow traffi
 client with the command below.
 
 ```shell
-sudo ufw allow from <client-ip-address> to any port nfs
+sudo ufw allow from <client_ip_address> to any port nfs
 ```
 
 <!-- ## Troubleshooting

doc/administration/pages/index.md

@@ -511,10 +511,17 @@ The following procedure includes steps to back up and edit the
 `gitlab-secrets.json` file. This file contains secrets that control
 database encryption. Proceed with caution.
 
+1. Create a backup of the secrets file on the **GitLab server**:
+
+   ```shell
+   cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak
+   ```
+
 1. On the **GitLab server**, to enable Pages, add the following to `/etc/gitlab/gitlab.rb`:
 
    ```ruby
    gitlab_pages['enable'] = true
+   pages_external_url "http://<pages_server_URL>"
    ```
 
 1. Optionally, to enable [access control](#access-control), add the following to `/etc/gitlab/gitlab.rb`:
@@ -527,26 +534,25 @@ database encryption. Proceed with caution.
    changes to take effect. The `gitlab-secrets.json` file is now updated with the
    new configuration.
 
-1. Create a backup of the secrets file on the **GitLab server**:
-
-   ```shell
-   cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.bak
-   ```
-
 1. Set up a new server. This will become the **Pages server**.
 
-1. Create an [NFS share](../high_availability/nfs_host_client_setup.md) on the new server and configure this share to
-   allow access from your main **GitLab server**. For this example, we use the
+1. Create an [NFS share](../high_availability/nfs_host_client_setup.md)
+   on the **Pages server** and configure this share to
+   allow access from your main **GitLab server**.
+   Note that the example there is more general and
+   shares several sub-directories from `/home` to several `/nfs/home` mountpoints.
+   For our Pages-specific example here, we instead share only the
    default GitLab Pages folder `/var/opt/gitlab/gitlab-rails/shared/pages`
-   as the shared folder on the new server and we will mount it to `/mnt/pages`
+   from the **Pages server** and we mount it to `/mnt/pages`
    on the **GitLab server**.
+   Therefore, omit "Step 4" there.
 
 1. On the **Pages server**, install Omnibus GitLab and modify `/etc/gitlab/gitlab.rb`
    to include:
 
    ```ruby
-   external_url 'http://<ip-address-of-the-server>'
-   pages_external_url "http://<your-pages-server-URL>"
+   external_url 'http://<gitlab_server_IP_or_URL>'
+   pages_external_url "http://<pages_server_URL>"
    postgresql['enable'] = false
    redis['enable'] = false
    prometheus['enable'] = false
@@ -566,7 +572,15 @@ database encryption. Proceed with caution.
    ```
 
 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from the **GitLab server**
-   to the **Pages server**.
+   to the **Pages server**, for example via the NFS share.
+
+   ```shell
+   # On the GitLab server
+   cp /etc/gitlab/gitlab-secrets.json /mnt/pages/gitlab-secrets.json
+
+   # On the Pages server
+   mv /var/opt/gitlab/gitlab-rails/shared/pages/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json
+   ```
 
 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -574,13 +588,13 @@ database encryption. Proceed with caution.
 
    ```ruby
    gitlab_pages['enable'] = false
-   pages_external_url "http://<your-pages-server-URL>"
+   pages_external_url "http://<pages_server_URL>"
    gitlab_rails['pages_path'] = "/mnt/pages"
    ```
 
 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
-It is possible to run GitLab Pages on multiple servers if you wish to distribute
+It's possible to run GitLab Pages on multiple servers if you wish to distribute
 the load. You can do this through standard load balancing practices such as
 configuring your DNS server to return multiple IPs for your Pages server,
 configuring a load balancer to work at the IP level, and so on. If you wish to