improve setup documentation

This commit is contained in:
Michael Hönnig 2024-09-13 06:29:37 +02:00
parent 45994b2f48
commit 0fb3ecb9da

View File

@ -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: 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 - 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) (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/`. - 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*. - 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: 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' source .aliases # creates some comfortable bash aliases, e.g. 'gw'='./gradlew'
gw # initially downloads the configured Gradle version into the project 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: # if the container has not been built yet, run this:
pg-sql-run # downloads + runs PostgreSQL in a Docker container on localhost:5432 pg-sql-run # downloads + runs PostgreSQL in a Docker container on localhost:5432
# if the container has been built already, run this: # if the container has been built already, run this:
pg-sql-start 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 gw bootRun # compiles and runs the application on localhost:8080
# the following command should reply with "pong": # 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: Initially, pull an image compatible to current PostgreSQL version of Hostsharing:
docker pull postgres:15.5-bookworm
<big>**&#9888;**</big> <big>**&#9888;**</big>
If we switch the version, please also amend the documentation as well as the aliases file. Thanks! 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) ##### 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) [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. 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). 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 ## 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: 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 ```shell
cat .config/containers/storage.conf mkdir -p ~/.config/containers/
cat ~/.config/containers/storage.conf
[storage] [storage]
driver = "vfs" driver = "vfs"
graphRoot = "/tmp/containers/storage" 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: 1. In a local shell. in which you want to run the tests, set some environment variables:
```shell ```shell
# sudo ln -s $HOME/.docker/run/docker.sock /var/run/docker.sock
# or:
export DOCKER_HOST="unix:///run/user/$UID/podman/podman.sock" export DOCKER_HOST="unix:///run/user/$UID/podman/podman.sock"
# and:
export TESTCONTAINERS_RYUK_DISABLED=true export TESTCONTAINERS_RYUK_DISABLED=true
``` ```