Fix: docs dependencies and keypair configuration (#320)

Author: thekaveman

.markdownlint.yaml

@@ -13,3 +13,6 @@ MD024: false
 
 # Allow inline HTML
 MD033: false
+
+# Allow fenced code blocks
+MD046: false

docs/configuration/README.md

@@ -9,7 +9,35 @@ If you want to run with different settings, you should:
 1. Set the `ELIGIBILITY_SERVER_SETTINGS` environment variable to the path of your new file
 
 !!! note
-The Eligibility server loads in settings using Flask's methods for [Configuration Handling](https://flask.palletsprojects.com/en/2.2.x/config/).
 
-!!! important
-The default settings that will always be loaded are in [eligibility_server/settings.py](https://github.com/cal-itp/eligibility-server/blob/dev/eligibility_server/settings.py)
+    The Eligibility server loads in settings using Flask's methods for [Configuration Handling](https://flask.palletsprojects.com/en/2.3.x/config/).
+
+!!! note
+
+    The default settings that will always be loaded are in [eligibility_server/settings.py](https://github.com/cal-itp/eligibility-server/blob/dev/eligibility_server/settings.py)
+
+## Creating a new keypair
+
+!!! warning
+
+    The sample keys cannot be used for production. You must create and use a new keypair.
+
+To create a new keypair, start by creating the private key e.g. using [OpenSSL](https://www.openssl.org/docs/man3.1/man1/openssl-genrsa.html):
+
+```console
+openssl genrsa -out private.pem -traditional 4096
+```
+
+Next, extract the public key e.g. using [OpenSSL](https://www.openssl.org/docs/man3.1/man1/openssl-rsa.html):
+
+```console
+openssl rsa -in private.pem -pubout -out public.pem
+```
+
+Now there are two files:
+
+- The private key, kept secret for this server instance only: `private.pem`
+- The public key, shared with all clients of this server: `public.pem`
+
+The server instance also needs a public key reference from its client, so the above process should be repeated on the client-
+side and the client's _public key_ should be shared with the server.

docs/requirements.txt

@@ -1,4 +1,3 @@
-fontawesome_markdown
 mkdocs
 mkdocs-awesome-pages-plugin
 mkdocs-macros-plugin

keys/README.md

@@ -1,3 +1,5 @@
 # keys
 
-*These keys are just samples*. They cannot be used for production systems.
+_These keys are just samples_. They cannot be used for production systems.
+
+See more at <https://docs.calitp.org/eligibility-server/configuration>

mkdocs.yml

@@ -57,4 +57,3 @@ markdown_extensions:
       # insert a blank space before the character
       permalink: " ¶"
   - smarty
-  - fontawesome_markdown