This is an automated email from the ASF dual-hosted git repository.
gstein pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/steve.git
The following commit(s) were added to refs/heads/trunk by this push:
new 603aae6 Improve cert documentation.
603aae6 is described below
commit 603aae62a7c6c0a791070dab7e2a3a77a7ac1093
Author: Greg Stein <[email protected]>
AuthorDate: Wed Nov 5 00:47:27 2025 -0600
Improve cert documentation.
Add notes about starting from scratch, and how to update the Chrome browser.
---
v3/server/certs/README.md | 27 ++++++++++++++++++++-------
1 file changed, 20 insertions(+), 7 deletions(-)
diff --git a/v3/server/certs/README.md b/v3/server/certs/README.md
index 2f1d8b0..1716433 100644
--- a/v3/server/certs/README.md
+++ b/v3/server/certs/README.md
@@ -19,15 +19,24 @@ absolute paths.
If you do not have a server certificate to use, or you need a testing
and development certificate, then follow the instructions below.
-**NOTE**: this is based on the **mkcert** tool. Any standard toolchain
+**NOTE**: this documentation is based on the **mkcert** tool. Any standard
toolchain
may be used to create the certificate and private key.
-First step is to create a new Certificate Authority store on your local
-machine. **WARNING:** mkcert uses sudo to elevate privileges to modify
+On Ubuntu:
+```sh
+$ sudo apt install mkcert
+```
+
+First step is to create a new Certificate Authority (CA) store on your local
+machine.
+
+**WARNING:** mkcert uses **sudo** to elevate privileges to modify
the local CA store on your machine. This was a surprise, when it modified
`/etc/ssl/certs` on my machine without a password prompt (Crostini with
a NOPASSWD config on my username).
+Creating the CA is straightforward. You may/not receive a similar warning
about "certutil".
+
```sh
$ mkcert -install
Created a new local CA 💥
@@ -36,7 +45,7 @@ Warning: "certutil" is not available, so the CA can't be
automatically installed
Install "certutil" with "apt install libnss3-tools" and re-run "mkcert
-install" 👈
```
-This will create a CA certificate in your "trusted store" which may need
+This has created a CA certificate in your "trusted store" which may need
to be copied elsewhere. (eg. Certificate Manager in my Chrome browser on
my Chromebook) The certificate appears to have a pattern like
`mkcert_development_CA_*.crt`.
@@ -59,6 +68,8 @@ The certificate is at "./localhost.apache.org+3.pem" and the
key at "./localhost
It will expire on 29 December 2027 🗓
```
+_Note: on a different run, that "Note" about the local CA did not appear. YMMV_
+
Adjust the `config.yaml` to refer to these new files. The default
`config.yaml.example`
config assumes the generated files are moved under the `server/certs`
directory.
@@ -69,9 +80,11 @@ TBD: _more solutions besides Chrome_
### Chrome Browser
This is a self-signed certificate which is usually rejected by the Chrome
browser.
-To correct this, select the "Settings" menu option, then "Privacy and
Security".
+To correct this, select the "Settings" menu option, then "Privacy and
security",
+then the "Security" option.
Within that pane, select "Manage certificates" which will open a new tab.
+Select the "Installed by you" option.
Now select the "Import" button for "Trusted Certificates" and choose the `.pem`
-that was just generated. Should be `localhost.apache.org+3.pem` (not the key!).
+that was just generated. Should be `localhost.apache.org+3.pem` (not the
keyfile!).
-This should now provide trust to localhost for your dev/test operation.
+This should now provide trust to `localhost` for your dev/test operation.
