[meta] Questions and doc improvements based on installing GitLab Geo
Things to do / check / update docs for based on my experience as a newbie setting up GitLab Geo. Raw notes in https://docs.google.com/document/d/1AvimgYoc3aLKSveuOEb5PTyQfM12yXIscHIDT1WxNfI/edit
Check the box if an issue has been made to specifically address the concern, that allows the meta issue to be dissolved.
-
In https://docs.gitlab.com/ee/gitlab-geo/database.html#step-1-configure-the-primary-server can we make steps 1.1-1.3 a script of multiple steps that you just copy paste with a handy button that copies the commands to the clipboard? - where else in the docs do we have such buttons (that is not on www-gitlab-com)? - Not currently possible, opened issue https://gitlab.com/gitlab-org/gitlab-ce/issues/40846#note_50200080 marking as done here since will be addressed in that issue.
-
Setting a password for gitlab_replicator in step 1.4 is a "silent" experience. -
Regarding setting up TLS support for the postgres server, it wasn't clear to me whether I should pick option A or option B, but I believe @nick.thomas is already removing option A altogether? -
Combine steps 1.5 and 1.6 on https://docs.gitlab.com/ee/gitlab-geo/database.html#step-1-configure-the-primary-server - wait for omnibus-gitlab#2797 (closed) to be resolved as it is likely to reshuffle this page.
- addressed in https://gitlab.com/gitlab-org/gitlab-ee/issues/4254
-
Bit confusing that we include pretty much all commands in the geo documentation, except for gitlab-ctl reconfigure
, for which we consistently link to another page that furthermore includessudo
in front of it which is not needed since we already started off withsudo -i
. So remove that link, unless we think there is a real risk of the reconfigure command changing within a year.- wait for omnibus-gitlab#2797 (closed) to be resolved as it is likely to reshuffle this page.
- solved with https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3648
-
Step 1.8 in https://docs.gitlab.com/ee/gitlab-geo/database.html#step-1-configure-the-primary-server says it will fail but does not describe what the looks like. In my case it hung. But that is not the same as a fail. - Resolved by omnibus-gitlab#2797 (closed)
-
Counterintuitive that you click "Add Node" after changing the inputs. https://docs.gitlab.com/ee/gitlab-geo/database.html#step-2-add-the-secondary-gitlab-node This may be a bigger UX choice we made in the GitLab admin interface though - Will be fixed as part of https://gitlab.com/gitlab-org/gitlab-ee/issues/3195
-
Step 2 in https://docs.gitlab.com/ee/gitlab-geo/database.html#step-3-configure-the-secondary-server says "Or, if you generated a self-signed certificate, copy the generated server.crt file onto the secondary server from the primary, then install it in the right location." --> not clear what "the right location" is. -
In https://docs.gitlab.com/ee/administration/operations/speed_up_ssh.html#the-solution, the command sudo service sshd reload
seems to be distro specific, e.g. in my case it worked with ssh instead of sshd. We should point that out. -
Also on the page about speed_up_ssh, the docs indicate to test SSH by removing your SSH key from the web UI and then adding a new one and pulling a repo. But is there another way to test? If you are just setting things up from fresh this test isn't a viable path. -
https://docs.gitlab.com/ee/gitlab-geo/configuration.html needs some editing TLC to remove duplication and ambiguity. Include: clarify that when you first log on to secondary it redirects to primary to authenticate with oauth. In my case, it wasn't clear if it was asking to oauth user root
on primary, or userernstvn
on gitlab.com...
Edited by Ernst van Nierop