Quick note about sudo mkcert -install for SSL on Linux

• Please check this box if this contribution uses AI-generated content (including content generated by GitLab Duo features) as outlined in the GitLab DCO & CLA. As a benefit of being a GitLab Community Contributor, you receive complimentary access to GitLab Duo.

What does this merge request do and why?

Small documentation update suggesting users run sudo mkcert -install if using mkcert to generate a certificate for SSL-enabled GDK. I originally followed the documentation as listed, and just trusted that it would install the generated cert (though I ran mkcert as the debian or gdk user). In that scenario, mkcert's root cert was not added to the trust store, and I could not push to the GDK's git repos, because gitaly complained that the SSL cert was invalid. Using sudo mkcert -install then restarting the GDK resolved that push issue for me.

How to set up and validate locally

1. On a fresh GDK-in-a-box/container, follow all the directions on this howto/nginx.md page.
2. curl https://gdk.test:3443/ should complain that the certificate is untrusted.
3. Run sudo --preserve-env=HOME mkcert -install
4. curl https://gdk.test:3443/
5. Note that curl now trusts the cert.

Discussion

Going the mkcert route has two objectives:

1. Easily create a cert/key pair
2. Make that cert/key pair trusted by the system.

Behind the scenes, what it does when you run mkcert {hostname}:

1. Ensure a self-signed CA key pair exists in $(mkcert -CAROOT), which (for me) resolves to $HOME/.local/share/mkcert, creating it if necessary.
2. Create {hostname}.pem and {hostname}-key.pem in the current directory, where the cert is signed by mkcert's CA.
3. Try to do cp $(mkcert -CAROOT)/rootCA.pem /usr/local/share/ca-certificates/{munged name}.crt && update-ca-certificates

Step 3 needs root permissions to make the mkcert CA cert trusted system-wide. Just doing sudo mkcert -install to do step 3 will default to using root`s $HOME, so generate a new CA for the root user, and trust that. That's why we're left with the awkward invocation.

Impacted categories

The following categories relate to this merge request:

• gdk-reliability - e.g. When a GDK action fails to complete.
• gdk-usability - e.g. Improvements or suggestions around how the GDK functions.
• gdk-performance - e.g. When a GDK action is slow or times out.

Merge request checklist

• This change is backward compatible. If not, please include steps to communicate to our users.
• Tests added for new functionality. If not, please raise an issue to follow-up.
• Documentation added/updated, if needed.
• Announcement added, if change is notable.
• gdk doctor test added, if needed.