general README update

maybe it needs a review

README.md

@@ -1,35 +1,53 @@
-docker files and integrations
+# docker deployment of IdHub and tools
 
-# idhub
+## About the pilots that this repository deploys
 
-## build
+- xo9b:
+    - motivation: one idhub connects to the other using OIDC4VP flow
+    - components: idhub1, idhub2
+- setem:
+    - motivation: a user from org 1 connects to org 2 to get a discount code
+    - components: idhub1, idhub2
+- lafede:
+    - motivatiion: a user gets a verifiable credential presentation from idhub, optionally could be signed also using EIDAS1
+    - components: idhub1
+- pangea:
+    - motivation:
+        - a user from org 1 connects to org 1 services
+        - a user from org 1 connects to org 2 services
+    - components: idhub1, idhub2, goauthentik services, orchestra (with also nginx api rproxy), musician
+- test: intended for software quality such as testing, CI/CD, etc.
 
-```sh
-# clone or get latest versions of repos
-./pull-repos.sh
-# rebuild idhub locally
-./idhub_build.sh
-```
+## Installation
 
-in production, use `./idhub_build.sh prod` to enable detaching
+Considering debian stable distribution (Debian 12 bookworm)
 
-TODO: incorporate to general docker compose
+- [install docker](https://docs.docker.com/engine/install/debian/#install-using-the-convenience-script), docker compose plugin is recommended, in debian stable this is `docker-compose-plugin`.
+- make: some of the actions are declared in `Makefile`, you will need `sudo apt install make`.
+- figlet: display large texts, better visibility when running all the pilots together `sudo apt install figlet`.
 
-# deploy everything in localhost
+## Deployment
 
-note: right now the same applies for localhost and reachable deployments
+Execute `./build__all.sh` to run all the pilots, that includes building locally all the docker images and deploying its docker compose (each pilot has its `docker-compose__pilot-example.yml`).
+
+Or run a specific pilot with `./build__pilot-example.sh`.
+
+All the scripts are written in POSIX Shell. I hope they are easy enough and structured to be adapted to your needs.
+
+## Development
+
+You can use these docker images for developing the software. This repo is targeted on integrating, deploying and testing the IdHub tools. You can do the same with the other tools, the trick used is to override the docker's directory with a local directory. Example found on all pilots instances
 
 ```
-docker compose up
+    volumes:
+      - ./idhub1__pilot-example:/opt/idhub
 ```
 
-# building and deploying new docker images
+If you are developing IdHub, all the instances generate a copy of the target repository such as `idhub1__pilot-example`, which you can modify there, and the changes will apply to the deployment
 
-```
-make docker
-```
+In the `.env` there are some variables intended to be used for debugging purposes
 
-# dev
+### Commands that you might like
 
 if you want to enter a shell inside a new container:
 
@@ -42,3 +60,5 @@ if you want to enter a shell on already running container:
 ```
 docker exec -it ${target_docker_image} bash
 ```
+
+Where `target_docker_image` contains the ID of the container you want to run (see `docker ps` or `docker ps -a`)