From 2367d1308f1363264767f3e72f5525780cdb8416 Mon Sep 17 00:00:00 2001
From: Markus Thielen <markus.thielen@basebox.io>
Date: Tue, 4 Apr 2023 18:34:26 +0200
Subject: [PATCH] README update

---
 README.md | 52 +++++++++++++++++++++++++++++++---------------------
 1 file changed, 31 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 6d77ac2..7b86650 100644
--- a/README.md
+++ b/README.md
@@ -2,29 +2,49 @@
 
 This project implements the *Hello World* of API-driven apps: a simple TODO app, built with Vue 3.
 
-
 The `bbconf` folder contains basebox config files, database schema, type maps etc. and scripts to run broker and dbproxy from within the `bbconf` directory.
 
-## Recommended IDE Setup
+These files assume that you extracted the [basebox distribution](https://basebox.io/download) next to this repository's root.
 
-[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur)
+Example:  
+Let's assume you create a `basebox` folder in your home directory, change into it, extract the basebox distribution archive in that folder and then clone the contents of this repository into the same folder:
+
+``` sh
+cd ~
+mkdir basebox
+cd basebox
+tar xf basebox-version-arch.tgz  # adopt this command to the basebox distribution archive you downloaded
+git clone --single-branch --depth 1 https://gitea.basebox.health/samples/vue-todo.git
+```
+
+If you follow these steps, the scripts in `bbconf` will work out of the box.
 
 ## Installation
 
 To install this app, you need
 
 * npm, node.js
-* A PostgreSQL server, preferably on the local host (simpler)
+* A PostgreSQL server, preferably on the local host (simpler, but not suitable for production)
 * basebox components (broker, dbproxy, bbc)
 * Keycloak
 
 ### PostgreSQL Preparation
 
-You need to create a user and a database for the todo app. The recommended way to run basebox is to have a dedicated Unix user for dbproxy that authenticates to PostgreSQL using Peer authentication. This way, no password for the DB user has to be stored anywhere. The Unix user's name must match the name of the PostgreSQL user. For more info, see the basebox installation instructions and [PostgreSQL documentation](https://www.postgresql.org/docs/current/auth-peer.html).
+> The following guide assumes you are installing under Debian or Ubuntu Linux; if you are on a Mac, please see our [PostgreSQL Primer](https://docs.basebox.io/getting-started/postgresql/) for some hints.
+
+You need to create a user and a database for the todo app. 
+
+> Please note:
+>
+> The recommended way to run basebox is to have a dedicated Unix user for dbproxy that
+> authenticates to PostgreSQL using Peer authentication. This way, no password for the
+> DB user has to be stored anywhere. The Unix user's name must match the name of the
+> PostgreSQL user. For more info, see the basebox installation instructions and 
+> [PostgreSQL documentation](https://www.postgresql.org/docs/current/auth-peer.html).
 
 For simplicity's sake, we are using a normal PostgreSQL user that authenticates using md5 authentication, thus requires a password, which is set in the dbproxy configuration file.
 
-´´´sh
+``` sh
 # Under (Debian) Linux, switch to the postgres user first:
 # sudo su postgres
 createuser -DRP bb_todo  # default password: basebox
@@ -38,31 +58,21 @@ Tell PostgreSQL that the `bb_todo` user connects to the database using md5 authe
 local   bb_todo         bb_todo                                 md5
 ```
 
+Make sure to add the line that starts with `local   bb_todo...` under the commented header that starts with `# TYPE...`. PostgreSQL uses the first line that matches, so having the new line on top makes sure no other line overrides it.
+
+
 Reload PostgreSQL config:
 
 ```sh
 systemctl postgresql reload
 ```
 
-If PostgreSQL is older than version 13, you need to enable the crypto extension explicitly:
-
-```sh
-# Under (Debian) Linux, switch to the postgres user first:
-# sudo su postgres
-psql bb_todo
-
-# At the # bb_todo prompt:
-SELECT gen_random_uuid();
-# If this prints a UUID, you're ok. If you get an error, do this:
-CREATE EXTENSION pgcrypto;
-# Might try the SELECT call again.
-```
-
 #### Database Schema
 
 This repository contains an already compiled SQL file that creates the database schema:
 
 ```sh
-psql -U bb_todo bb_todo < bbconf/todo_datamodel.sql
+psql -U bb_todo bb_todo < bbconf/todo_datamodel.sql  # Enter password when prompted.
 ```
 
+The database configuration and installation is now complete.