improve setup documentation

README.md

@@ -51,9 +51,12 @@ Everything is tested on _Ubuntu Linux 22.04_ and _MacOS Monterey (12.4)_.
 To be able to build and run the Java Spring Boot application, you need the following tools:
 
 - Docker 20.x (on MacOS you also need *Docker Desktop* or similar) or Podman
-- optionally: PostgreSQL Server 15.5-bookworm 
+- if you use Podman, explicitly fetch the Docker-image for PostgreSQL Server 15.5-bookworm:
+  `podman pull docker.io/postgres:15.5-bookworm` 
   (see instructions below to install and run in Docker)
 - The matching Java JDK at will be automatically installed by Gradle toolchain support to `~/.gradle/jdks/`.
+- named-checkzone needs to be installed for some tests and to run fully the application:
+    `sudo apt install bind9-utils`
 - You also might need an IDE (e.g. *IntelliJ IDEA* or *Eclipse* or *VS Code* with *[STS](https://spring.io/tools)* and a GUI Frontend for *PostgreSQL* like *Postbird*.
 
 If you have at least Docker and the Java JDK installed in appropriate versions and in your `PATH`, then you can start like this:
@@ -62,14 +65,17 @@ If you have at least Docker and the Java JDK installed in appropriate versions a
     
     source .aliases # creates some comfortable bash aliases, e.g. 'gw'='./gradlew'
     gw              # initially downloads the configured Gradle version into the project
-
+     
-    gw test         # compiles and runs unit- and integration-tests
-    
     # if the container has not been built yet, run this:
     pg-sql-run      # downloads + runs PostgreSQL in a Docker container on localhost:5432
     # if the container has been built already, run this:
     pg-sql-start
+    # this step was mostly to test if Docker/Podman wirks (and introduce these aliases), so you can stop PostgreSQL again:
+    pg-sql-stop
 
+    gw-test         # compiles and runs unit- and integration-tests
+   
+    
     gw bootRun      # compiles and runs the application on localhost:8080
 
     # the following command should reply with "pong":
@@ -111,7 +117,7 @@ But the easiest way to run PostgreSQL is via Docker.
 
 Initially, pull an image compatible to current PostgreSQL version of Hostsharing:
 
-    docker pull postgres:15.5-bookworm 
+    
 
 <big>**&#9888;**</big>
 If we switch the version, please also amend the documentation as well as the aliases file. Thanks! 
@@ -256,7 +262,7 @@ If not, you need to install some tooling.
 
 ##### for IntelliJ IDEA (or derived products)
 
-1. Activate the bundled Jebrains Markdown PlantUML Extension via
+1. Activate the bundled Jetbrains Markdown PlantUML Extension via
     [File | Settings | Languages & Frameworks | Markdown](jetbrains://idea/settings?name=Languages+%26+Frameworks--Markdown)  
 2. Install the Jetbrains Mermaid plugin: https://plugins.jetbrains.com/plugin/20146-mermaid, it also works embedded in Markdown files.
 
@@ -304,15 +310,6 @@ To increase the amount of test data, increase the number of generated customers
 
 If you already have data, e.g. for customers 0..999 (thus with reference numbers 10000..10999) and want to add another 1000 customers, amend the for loop to 1000...1999 and also uncomment and amend the `CONTINUE WHEN` or `WHERE` conditions in the other test data generators, using the first new customer reference number (in the example that's 11000).
 
-### For Historization
-
-The historization is not yet integrated into the *Liquibase*-scripts.
-You can explore the prototype as follows:
-
-- start with an empty database
-  (the example tables are currently not compatible with RBAC),
-- then run `historization.sql` in the database,
-- finally run `examples.sql` in the database.
 
 ## Coding Guidelines
 
@@ -589,7 +586,8 @@ sudo apt-get -y install podman
 It is possible to move the storage directory to /tmp, e.g. to increase performance or to avoid issues with NFS mounted home directories:
 
 ```shell
-cat .config/containers/storage.conf
+mkdir -p ~/.config/containers/
+cat ~/.config/containers/storage.conf
 [storage]
 driver = "vfs"
 graphRoot = "/tmp/containers/storage"
@@ -611,7 +609,10 @@ These commands are also available in `.aliases` as `podman-start`.
 1. In a local shell. in which you want to run the tests, set some environment variables:
 
 ```shell
+# sudo ln -s $HOME/.docker/run/docker.sock /var/run/docker.sock
+# or:
 export DOCKER_HOST="unix:///run/user/$UID/podman/podman.sock"
+# and:
 export TESTCONTAINERS_RYUK_DISABLED=true
 ```