Correct gitlab.rb examples that do not configure what they say

What does this MR do?

Three pages give gitlab.rb examples that do not configure what they say. Two set a key that nothing reads, and gitlab-ctl reconfigure accepts both without a warning, so the reader has no way to notice. The third uses a name gitlab.rb does not have, so reconfigure fails.

• Database, "Configure the Rails client": the step asks for the CA file through gitlab_rails['db_rootcert']. database.yml.erb (lines 29-30) renders sslrootcert and sslca from db_sslrootcert and db_sslca only, so a reader who follows the step gets a database.yml whose sslrootcert and sslca are empty (YAML null): the CA file never reaches the Rails client. I changed the key to db_sslrootcert, which is the key the "Require SSL and verify server certificate against CA bundle" section of the same page already uses, and the one gitlab.rb.template lists.
• SMTP, three examples: "SMTP without SSL", the Amazon SES "Using TLS Wrapper" example and "easyDNS (outbound mail)" set gitlab_rails['smtp_force_ssl']. smtp_settings.rb.erb renders a fixed list of smtp_* keys (line 13), and force_ssl is not on it, nor is it an option of the mail gem GitLab uses (2.9.0). Anyone who keeps the line believing it forces SSL is relying on something that does nothing. I removed the line from the three examples. Each one renders the same smtp_settings.rb without it, and still does what its heading says through the settings next to it: smtp_ssl for the SES TLS wrapper on port 465, smtp_enable_starttls_auto for easyDNS on port 587, and TLS, SSL and STARTTLS all off for "SMTP without SSL".
• NGINX troubleshooting, "Error: worker_connections are not enough": the step sets gitlab['nginx']['worker_connections'], which is the attribute's path in the node, not a gitlab.rb setting. gitlab.rb has no top-level gitlab, so Gitlab.from_file, which package/recipes/config.rb calls at the start of reconfigure, raises Mixlib::Config::UnknownConfigOptionError: Reading unsupported config value gitlab. and reconfigure stops. I changed it to nginx['worker_connections'], the form gitlab.rb.template lists (line 2118).

I only changed doc/. The doc-locale/ copies of these pages carry the same lines; I left them alone because the translation workflow in argo_translation.yml produces them from doc/.

To find these I listed every <role>['key'] that a page under doc/ writes and looked for the role and the key in files/gitlab-cookbooks and gitlab.rb.template. Under doc/settings/ these are the only lines that set a key nothing reads or a name gitlab.rb does not have.

What the documented settings do, before and after

I ran three throwaway ChefSpec files (not part of this MR) against 12a6ea3c36a6, in ruby:3.3.12 (.ruby-version) with the project's own bundle. One converges gitlab-base::config and gitlab::gitlab-rails with the settings of the database and SMTP examples; one loads those lines through Gitlab.from_file, the way reconfigure reads /etc/gitlab/gitlab.rb; the third loads the NGINX step's line through Gitlab.from_file and converges the NGINX recipes with the corrected form.

Database, "Configure the Rails client" with db_host, db_sslcert and db_sslkey set:

CA file set through	sslrootcert in database.yml	sslca in database.yml
gitlab_rails['db_rootcert'] (the page today)	empty (null)	empty (null)
gitlab_rails['db_sslrootcert'] (this MR)	/etc/gitlab/ssl/ca.crt	/etc/gitlab/ssl/ca.crt

SMTP: for each of the three examples, smtp_settings.rb rendered with the smtp_force_ssl line and without it are byte-identical (cmp), and neither contains force. The SES example renders, with or without the line (blank lines the template leaves removed):

  smtp_settings = {
    authentication: :login,
    user_name: "IAMmailerKey",
    password: "IAMmailerSecret",
    address: "email-smtp.region-1.amazonaws.com",
    port: 465,
    domain: "yourdomain.com",
    ssl: true,
    ca_file: "/opt/gitlab/embedded/ssl/certs/cacert.pem",
    open_timeout: 30,
    read_timeout: 60,
  }

In mail 2.9.0 (lib/mail/network/delivery_methods/smtp.rb), ssl: true makes the session call enable_tls (implicit TLS), enable_starttls_auto: true makes it call enable_starttls_auto, and no option is named force_ssl.

Parsing: Gitlab.from_file accepts the db_rootcert and smtp_force_ssl lines without an error and stores both values. config_strict_mode in settings_dsl.rb only rejects unknown top-level names, Gitlab::Deprecations.list has no entry for either key, and Gitlab::Deprecations.check_config returns no message for them.

NGINX: gitlab['nginx']['worker_connections'] = 20480 through Gitlab.from_file raises Mixlib::Config::UnknownConfigOptionError: Reading unsupported config value gitlab.. nginx['worker_connections'] = 20480 is stored as 20480, and with it nginx.conf renders worker_connections 20480;.

History: none of these lines ever worked. db_rootcert came in with 690d59b4, the three smtp_force_ssl lines with 568487b5, 916172aa and 1be54724, and the gitlab['nginx'] line with d1a264c2. git log -S finds db_rootcert and force_ssl nowhere under files/, and nginx['worker_connections'] has been the template's form since 2014.

Checks

In the DOCS_LINT_IMAGE from gitlab-ci-config/variables.yml, the commands of docs-lint content, docs-lint markdown and docs-lint links:

$ vale --minAlertLevel error doc
✔ 0 errors, 0 warnings and 0 suggestions in 96 files.
$ markdownlint-cli2 'doc/**/*.md'
Summary: 0 issues in 0 files
$ lychee --offline --include-fragments doc
🔍 1084 Total (in 55ms) 🔗 683 Unique ✅ 236 OK 🚫 0 Errors 👻 848 Excluded

vale on the three pages at every alert level reports the same 110 warnings and 65 suggestions before and after this change.

Related issues

No issue covers these lines. The commits that added them are listed under History above.

Author's checklist

• Consider taking the GitLab Technical Writing Fundamentals course
• Follow the:
  • Documentation process.
  • Documentation guidelines.
  • Style Guide.
• When ready for review, MR is labeled workflowready for review per the Distribution MR workflow

If you are only adding documentation, do not add any of the following labels:

• ~"feature"
• ~"frontend"
• ~"backend"
• ~"bug"
• ~"database"

These labels cause the MR to be added to code verification QA issues.

Review checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

• If the content requires it, ensure the information is reviewed by a subject matter expert.
• Technical writer review items:
  • Ensure docs metadata is present and up-to-date.
  • Ensure the appropriate labels are added to this MR.
  • If relevant to this MR, ensure content topic type principles are in use, including:
    • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
    • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
    • Any task steps should be written as a numbered list.
    • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
• Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
• Ensure a release milestone is set.