From fbf07c66d9515da4e44c3f8613f1c5919e0a26b1 Mon Sep 17 00:00:00 2001
From: Brian McCullough <bmccullough@cacert.org>
Date: Sun, 6 Aug 2023 15:54:14 -0400
Subject: [PATCH] Updated README to show current practice.

---
 README-extra.md | 14 ++++++++++++++
 README.md       | 43 ++++++++++++++++++++++++++++++++++---------
 2 files changed, 48 insertions(+), 9 deletions(-)
 create mode 100644 README-extra.md

diff --git a/README-extra.md b/README-extra.md
new file mode 100644
index 0000000..9af1b0a
--- /dev/null
+++ b/README-extra.md
@@ -0,0 +1,14 @@
+### Extra PostgreSQL Notes
+
+PostgreSQL should have been installed automatically as part of the installation of Debian 12.
+
+see /usr/share/doc/postgresql-common for some documentation 
+
+If, for some reason, that installation is incomplete, it is best to re-install PostgreSQL in your Debian 12.
+
+```shell
+sudo apt update
+sudo apt install postgresql postgresql-contrib
+```
+
+
diff --git a/README.md b/README.md
index e5c00a6..7a3bb2b 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,13 @@ Make sure you have the necessary prerequisites installed (tested on Debian 12
 Bookworm) and `~/.local/bin` in your `$PATH`
 variable:
 
+Those prerequisites include:
+git -- of course
+PostgreSQL -- see README-extra.md
+Hydra -- see hydra_config/README.md
+
+Further items are installed here:
+
 ```shell
 sudo apt update
 sudo apt install make mkcert python3-pip python3-venv golang-go yarnpkg
@@ -38,8 +45,10 @@ a configuration file and, usually, certificates.
 The first that must be performed are the instructions found in the "hydra_config"
 sub-directory.  
 
-    In that one, you must create a certificate and key pair using mkcert, 
-    set your database password, and generate a secret key for Hydra.
+    In that one, you must first install Hydra before you continue.
+
+    Next, create a certificate and key pair using mkcert, set your database 
+    password, and generate a secret key for Hydra.
 
     Following that, you need to create the Hydra configuration file, hydra.yaml.
 
@@ -48,7 +57,7 @@ sub-directory.
     values returned from that command.
 
 Next, go in to the cacert_resources sub-directory and follow the directions 
-in that README.md.
+in that README.md regarding installing nodejs and webpack.
 
 Third, go in to the oidc_app sub-directory.
 
@@ -83,8 +92,18 @@ needed by this system.
 Use `make` to build the web app resources and applications:
 
 
+### Install the language translation tool
+
 ```shell
 go install github.com/nicksnyder/go-i18n/v2/goi18n@latest
+```
+
+
+### Build the applications
+
+Use `make` to build the web app resources and applications:
+
+```shell
 make
 ```
 
@@ -115,7 +134,7 @@ ansible-playbook 01_install_cacert_oidc.yml
 ```
 
 Note: If ansible-playbook fails early in the process with "sudo: a password is required," 
-then confirm that your user has sudo privileges and execute that command like
+then confirm that your user has sudo privileges and execute the `ansible-playbook` command like:
 
 ```shell
 ansible-playbook -K 01_install_cacert_oidc.yml
@@ -123,7 +142,7 @@ ansible-playbook -K 01_install_cacert_oidc.yml
 
 ### Vagrant setup
 
-You can also use [Vagrant](https://www.vagrantup.com/) with the
+Instead of Ansible, you can also use [Vagrant](https://www.vagrantup.com/) with the
 libvirt-provider. The included Vagrantfile is configured to apply the
 ansible-playbook to the Vagrant managed virtual machine.
 
@@ -134,6 +153,11 @@ vagrant ssh -- cat .local/share/mkcert/rootCA.pem | sudo tee /usr/local/share/ca
 sudo update-ca-certificates
 ```
 
+
+========
+
+## Finally
+
 Note: You may also want to configure your browser to trust the CA certificate
 in `/usr/local/share/ca-certificates/mkcert-vagrant-oidc.crt`. If you do not
 add this trust configuration you will get browser warnings for an unknown
@@ -141,10 +165,11 @@ certificate authority.
 
 ## Testing your local setup
 
-After running "make", in each of the sub-directories except cacert_resources and 
-hydra_config you will find an executable file.  You must execute each of these 
-commands, using multiple terminal windows, so that they are each running 
-in individual terminals.
+After running "make" and "ansible-playbook," Hydra and oidc-idp will both be running.
+
+To run the rest of the components, in each of two new terminal windows, execute 
+"oidc_app/demo-app" and "oidc_registration/cacert-oidc-registration".
+
 
 ### Test the authorization server