Make GitLab Pages easier to use for GitLab.com users?
I recently went through the process of creating a site using GitLab Pages on gitlab.com. Not being experienced in setting up websites, I had trouble and needed help from colleagues at GitLab to
- get the SSL certs up (with intermediates),
- we had a bit of back and forth about how to share the private key (used a 1password credential, then shared that 'securely' per 1password's workflow)
- set the DNS record
What I learned from it is that you do need to know how to set up SSL certs and DNS records, and those things are mentioned in the docs with the assumption that the reader knows how to do that. This is fine, depending on the audience. Who are we expecting / wanting to use pages?
If we want to make it easy for people who have not set up a page before (for example, a researcher who just started using GitLab.com to host code and data for her biology research group, who then wants to create a website) then we have to do more hand-holding in the docs.
Activity
Also \cc @AshleyS @sytses
@ernstvn Maybe creating a video tutorial for non-tech people is easier to understand for people new to setting up websites. (And it makes for great content)
There is this post https://webnugget.de/setting-up-gitlab-with-free-ssl-certs-from-lets-encrypt-on-ubuntu-14-04/ that explains how to setup gitlab with lets encrypt.
Granted that cryptography is hard, and there are a lot of concepts that are quite complex. From a user perspective I think that we need to map our error messages like “Certificate misses intermediates" to a brief explanation that points at what is going on, and provides some guidance.
I don't think we can cover all the possible edge cases as there are way too many.
This said, what was handled by geeks was:
- Creating the private key and generating the certificate signature request (CSR) <- this one is hard even for technical people.
- Obtaining the certificate from our provider
- Building the certificate chain so GitLab accepts it (Certificates misses intermediates)
- Adding the DNS CNAME record so the domain resolves correctly
From a non technical perspective @ernstvn, what would have made sense to have in the documentation to easing the process if you did not had access to technical staff?
@pcarranza I'm not sure if I understand your question at the end:
From a non technical perspective @ernstvn, what would have made sense to have in the documentation to easing the process if you did not had access to technical staff?
all the issues I had were related to the technical implementation... So perhaps links to "basics of..." would have helped, although they would have taken time to read and learn from. It is not clear to me at this point if I could indeed have done this without your help at all (as in, because I don't have the right permissions / level of authorization to request certs, make keys, set DNS records, etc.).
@ernstvn Thanks for creating the issue. SSL should be solved with Letsencrypt support https://gitlab.com/gitlab-org/gitlab-ce/issues/14926 Can you focus on documenting DNS records better?
Thanks for creating this @ernstvn. There is a general issue with DNS that needs better documentation in and out of GitLab. For context see https://gitlab.com/gitlab-org/gitlab-ee/issues/443.
I can work on a quick guide for the DNS part next week.
Edited by Achilleas PipinellisThanks @axil , I'll assign this issue to you for now then.
Reassigned to @axil
I agree that UX of this feature should be improved :) It was made by engineer (me), so it assumes that it's also used by engineer.
@sytses @axil I think that we should add a button to
validateyour domain. It should: Check if DNS record is properly configured, and if not it should instruct how to do it. I think that documentation for this should be part of the that Page.
@marcia created a great guide https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/ which we can make sure is linked to from docs with additional "getting started" content.
changed milestone to %8.17
mentioned in issue gitlab-com/gitlab-docs#69 (closed)
