diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 000000000..d0e948a0d --- /dev/null +++ b/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` diff --git a/README.md b/README.md index 85bd88f3c..ed34132b1 100644 --- a/README.md +++ b/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 diff --git a/dev-assets/docker-environment/docker-compose.yaml b/dev-assets/docker-environment/docker-compose.yaml index a2873cf45..ba28cf286 100644 --- a/dev-assets/docker-environment/docker-compose.yaml +++ b/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 diff --git a/dev-assets/env-files/env.docker.dist b/dev-assets/env-files/env.docker.dist index 12aed3d56..b4b3e8e6d 100644 --- a/dev-assets/env-files/env.docker.dist +++ b/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 diff --git a/dev-assets/env-files/env.local.dist b/dev-assets/env-files/env.local.dist index 3f9459316..721bd9d32 100644 --- a/dev-assets/env-files/env.local.dist +++ b/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 diff --git a/dev-assets/scripts/get_Token.sh b/dev-assets/scripts/get_Token.sh index de719990f..46c172d4f 100755 --- a/dev-assets/scripts/get_Token.sh +++ b/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' \ No newline at end of file +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"