Merge pull request #174 from pmoscode/chore/update-readme

Update README.md, introduce INSTALL.md

INSTALL.md

@@ -0,0 +1,49 @@
+# Managed Identity Wallets
+
+If you just want to try out MIW (without any developer setup), then you can find a quick start guide here:
+
+(It will only work on macOS or GNU/Linux - For Windows,
+you need to use the [WSL](https://learn.microsoft.com/de-de/windows/wsl/install))
+
+- You need to install these tools:
+    - [Docker](https://docs.docker.com/desktop/) (or from your package manager)
+      -> Configure it to run without root permission
+    - Docker [compose plugin](https://docs.docker.com/compose/)
+    - [Taskfile](https://taskfile.dev)
+    - [jq](https://jqlang.github.io/jq/)
+- Clone this repo
+- (Optional) Checkout main (stable) or develop (latest), if not already checked out
+- Copy `dev-assets/env-files/env.docker.dist` to `dev-assets/env-files/env.docker`
+- Set these variables in `env.docker`
+    - POSTGRES_PASSWORD
+    - POSTGRES_PASSWORD_MIW
+    - KEYCLOAK_ADMIN_PASSWORD
+    - ENCRYPTION_KEY (32 random alphanumeric characters)
+    - GITHUB_USERNAME
+    - GITHUB_TOKEN
+- Follow the "docker" path of the "Development setup" to get it up and running:
+    1. Run `task docker:start-app` and wait until it shows "Started ManagedIdentityWalletsApplication in ... seconds"
+    2. Run `task app:get-token` in another shell and copy the token (including "BEARER" prefix) (Mac users have the token already in their clipboard :) )
+    3. Open API doc on http://localhost:8000
+    4. Click on Authorize on Swagger UI and on the dialog paste the token (incl. "Bearer") into the "value" input
+    5. Click on "Authorize" and "close"
+    6. MIW is up, running, and you are authorized to fire requests in the Swagger UI
+    7. If you're done, then run `task docker:stop-app` to clean up everything
+
+> [!IMPORTANT]  
+> To compile MIW,
+> you need a PAT with the permission `read:packages` to 
+> access `https://maven.pkg.github.com/catenax-ng/product-lab-ssi`.
+> 
+> That is, why you need to set `GITHUB_USERNAME` and `GITHUB_TOKEN`. Otherwise, you are not able to get the SSI-lib.
+
+> [!IMPORTANT]  
+> You need to use Java 17!
+
+> [!WARNING]
+> If you encounter some kind of database connection errors, then execute `task docker:stop-app`.
+> This will remove all existing Docker volumes, which may cause this error.
+
+> [!IMPORTANT]
+> Ensure you have exactly 32 random alphanumeric characters set 
+> for `ENCRYPTION_KEY` in `dev-assets/env-files/env.docker`

README.md

@@ -2,6 +2,10 @@
 
 The Managed Identity Wallets (MIW) service implements the Self-Sovereign-Identity (SSI) using `did:web`.
 
+# Usage
+
+See [INSTALL.md](INSTALL.md) 
+
 # Developer Documentation
 
 To run MIW locally, this section describes the tooling as well as the local development setup.
@@ -151,26 +155,27 @@ directory, but without ".dist" at the end.
 
 Description of the env files:
 
-- **env.local**: Setup everything to get ready for flow "local". You need to fill in the passwords.
-- **env.docker**: Setup everything to get ready for flow "docker". You need to fill in the passwords.
+- **env.local**: Set up everything to get ready for flow "local". You need to fill in the passwords. 
+- **env.docker**: Set up everything to get ready for flow "docker". You need to fill in the passwords.
 
-> **IMPORTANT**: ssi-lib is resolving DID documents over network. There are two endpoints that rely on this resolution:
+> **IMPORTANT**: ssi-lib is resolving DID documents over the network. There are two endpoints that rely on this resolution:
 > - Verifiable Credentials - Validation
 > - Verifiable Presentations - Validation
->
-> The following parameters must be added or changed in env.local or env.docker file to ensure that these endpoints work
-> as intended in local development environment:
-> Add: ENFORCE_HTTPS_IN_DID_RESOLUTION=false
-> Change: MIW_HOST_NAME from miw to localhost
-> Change: APPLICATION_PORT from 8000 to 80
-
-> **IMPORTANT**: When you are using MacOS and the MIW docker container won't start up (stuck somewhere or doesn't start
+>   
+> The following parameters are set in env.local or env.docker file per default:
+> ENFORCE_HTTPS_IN_DID_RESOLUTION=false
+> MIW_HOST_NAME=localhost
+> APPLICATION_PORT=80
+> If you intend to change them, the DID resolving may not work properly anymore!
+
+> **IMPORTANT**: When you are using macOS and the MIW docker container won't start up (stuck somewhere or doesn't start
 > at all), you can enable the docker-desktop feature "Use Rosetta for x86/amd64 emulation on Apple Silicon" in your
 > Docker settings (under "features in development"). This should fix the issue.
 
 In both env files (env.local and env.docker) you need to set *GITHUB_USERNAME* and *GITHUB_TOKEN* in order to be able to
 build the app, because the SSI lib is stored in a private repo (you also need the proper rights to access the repo).
-The access token need to have `read:packages` access. (ref: https://github.com/settings/tokens/new)
+The access token need to have `read:packages` access.
+(Ref: https://github.com/settings/tokens/new)
 
 Note: *SKIP_GRADLE_TASKS_PARAM* is used to pass parameters to the build process of the MIW jar. Currently, it skips the
 tests and code coverage, but speeds up the build time. If you want to activate it, just comment it out

dev-assets/docker-environment/docker-compose.yaml

@@ -28,7 +28,7 @@ services:
     env_file:
       - ../env-files/env.$DEV_ENVIRONMENT
     ports:
-      - "8000:8000"
+      - "$APPLICATION_PORT:$APPLICATION_PORT"
       - "8090:8090"
     networks:
       - miw-net

dev-assets/env-files/env.docker.dist

@@ -34,7 +34,8 @@ KEYCLOAK_REALM=miw_test
 VC_SCHEMA_LINK="https://www.w3.org/2018/credentials/v1, https://catenax-ng.github.io/product-core-schemas/businessPartnerData.json"
 VC_EXPIRY_DATE=01-01-2025
 SUPPORTED_FRAMEWORK_VC_TYPES="PcfCredential, SustainabilityCredential, QualityCredential, TraceabilityCredential, BehaviorTwinCredential, ResiliencyCredential"
-MIW_HOST_NAME=miw
+MIW_HOST_NAME=localhost
+ENFORCE_HTTPS_IN_DID_RESOLUTION=false
 
 ######### DON'T MODIFY ANYTHING BELOW THIS LINE !!! #########
 AUTH_SERVER_URL=http://keycloak:8080

dev-assets/env-files/env.local.dist

@@ -34,7 +34,8 @@ KEYCLOAK_REALM=miw_test
 VC_SCHEMA_LINK="https://www.w3.org/2018/credentials/v1, https://catenax-ng.github.io/product-core-schemas/businessPartnerData.json"
 VC_EXPIRY_DATE=01-01-2025
 SUPPORTED_FRAMEWORK_VC_TYPES="PcfCredential, SustainabilityCredential, QualityCredential, TraceabilityCredential, BehaviorTwinCredential, ResiliencyCredential"
-MIW_HOST_NAME=miw
+MIW_HOST_NAME=localhost
+ENFORCE_HTTPS_IN_DID_RESOLUTION=false
 
 ######### DON'T MODIFY ANYTHING BELOW THIS LINE !!! #########
 AUTH_SERVER_URL=http://localhost:8080

dev-assets/scripts/get_Token.sh

@@ -20,11 +20,11 @@
 # ********************************************************************************/
 #
 
-curl --location 'http://localhost:8080/realms/miw_test/protocol/openid-connect/token' \
-     --header 'Content-Type: application/x-www-form-urlencoded' \
-     --data-urlencode 'client_id=miw_private_client' \
-     --data-urlencode 'client_secret=miw_private_client' \
-     --data-urlencode 'grant_type=password' \
-     --data-urlencode 'username=catena-x' \
-     --data-urlencode 'password=password' \
-     | jq -r '.access_token'
+curl --location "http://localhost:8080/realms/miw_test/protocol/openid-connect/token" \
+     --header "Content-Type: application/x-www-form-urlencoded" \
+     --data-urlencode "client_id=miw_private_client" \
+     --data-urlencode "client_secret=miw_private_client" \
+     --data-urlencode "grant_type=password" \
+     --data-urlencode "username=catena-x" \
+     --data-urlencode "password=password" \
+     | jq -r ".access_token"