Skip to content

Commit

Permalink
feat(devel): update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@pmoscode
pmoscode committed Jul 3, 2023
1 parent 70392a3 commit 74fdb21
Showing 1 changed file with 55 additions and 25 deletions.
80 changes: 55 additions & 25 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,46 +4,74 @@ The Managed Identity Wallets (MIW) service implements the Self-Sovereign-Identit

# Developer Documentation

To run MIW locally, this section describes the tooling as well as
the local development setup.
To run MIW locally, this section describes the tooling as well as the local development setup.

There are two possible flows, which can be used for development:

1. **local**: Run the postgresql and keycloak server inside docker. Start MIW from within your IDE (recommended for actual development)
2. **docker**: Run everything inside docker (use to test or check behavior inside a docker environment)

## Tooling

Following tools the MIW development team used successfully:

| Area | Tool | Download Link | Comment |
|----------|----------|-------------------------------------------------|---------------------------------------------------------------------------------------------------|
| IDE | IntelliJ | https://www.jetbrains.com/idea/download/ | Additionally the [envfile plugin](https://plugins.jetbrains.com/plugin/7861-envfile) is suggested |
| IDE | IntelliJ | https://www.jetbrains.com/idea/download/ | Use [envfile plugin](https://plugins.jetbrains.com/plugin/7861-envfile) to use the **local** flow |
| Build | Gradle | https://gradle.org/install/ |
| Runtime | Docker | https://www.docker.com/products/docker-desktop/ | |
| Database | DBeaver | https://dbeaver.io/ |
| IAM | Keycloak | https://www.keycloak.org/ | |

## Local Development Setup
## Development Setup

1. Run keycloak and database server using [docker-compose.yaml](dev-assets%2Fdid-web%2Fdocker-compose.yaml)
2. Create personal access token(classic) with `read:packages` access (ref: https://github.com/settings/tokens/new)
3. set ORG_GRADLE_PROJECT_githubUserName and ORG_GRADLE_PROJECT_githubToken values
in [dev.env](dev-assets%2Fdid-web%2Fdev.env)
4. Setup [dev.env](dev-assets%2Fdid-web%2Fdev.env) values either in application.yaml or in IDE
5. Run [ManagedIdentityWalletsApplication.java](src%2Fmain%2Fjava%2Forg%2Feclipse%2Ftractusx%2Fmanagedidentitywallets%2FManagedIdentityWalletsApplication.java) in IDE
6. Open API doc on http://localhost:8080
7. Click on Authorize on swagger UI and on the dialog click again on Authorize.
8. Login with username=catena-x and password=password
### Prerequisites

## Build application locally
To simplify the dev environment, [Taskfile](https://taskfile.dev) is used as a task executor. You have to install it first.

Build with test cases
Before executing any of th tasks, you have to choose your flow (_local_ or _docker_). _local_ is default.
To change that, you need to edit the variable **ENV** in the _Taskfile.yaml_.

```
./gradlew build
```
After that, run `task check-prereqs` to see, if any other required tool is installed or missing. If something is missing, a link to the install docs is provided.

Build without test cases
Now, you have to adjust the _env_ files (located in _dev-assets/env-files_). To do that, copy every file to the same 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. Everything else can remain as it is.
- **env.docker**: Setup everything to get ready for flow "docker". You need to fill in the passwords. Everything else can remain as it is.

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 add,
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)

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 like `SKIP_GRADLE_TASKS_PARAM="" #"-x jacocoTestCoverageVerification -x test"`

After every execution (either _local_ or _docker_ flow), run the matching "stop" task (e.g.: `task docker:start-app` -> `task docker:stop-app`)

When you just run `task` without parameters, you will see all tasks available.

### local

1. Run `task docker:start-middleware` and wait until it shows "(main) Running the server in development mode. DO NOT use this configuration in production." in the terminal
2. Run `task app:build` to build the MIW application
3. Run [ManagedIdentityWalletsApplication.java](src/main/java/org/eclipse/tractusx/managedidentitywallets/ManagedIdentityWalletsApplication.java) via IDE and use the local.env file to populate environment vars (e.g. EnvFile plugin for IntelliJ)
4. Run `task app:get-token` and copy the token (including "BEARER" prefix) (Mac users have the token already in their clipboard :) )
5. Open API doc on http://localhost:8000 (or what port you configured in the _env.local_ file)
6. Click on Authorize on swagger UI and on the dialog paste the token into the "value" input
7. Click on "Authorize" and "close"
8. MIW is up and running

### docker

1. Run `task docker:start-app` and wait until it shows " Started ManagedIdentityWalletsApplication in ... seconds"
2. Run `task app:get-token` and copy the token (including "BEARER" prefix) (Mac users have the token already in their clipboard :) )
3. Open API doc on http://localhost:8000 (or what port you configured in the _env.local_ file)
4. Click on Authorize on swagger UI and on the dialog paste the token into the "value" input
5. Click on "Authorize" and "close"
6. MIW is up and running

```
./gradlew build -i -x test
```

## Test Coverage

Expand All @@ -55,16 +83,16 @@ The generated HTML report can be found under `jacoco-report/html/`
To generate the report run the command

```
./gradlew jacocoTestReport
task app:test-report
```

To check the coverage run the command

```
./gradlew jacocoTestCoverageVerification
task app:coverage
```

Currently the minimum is 80%
Currently, the minimum is 80% coverage.

## Common issues and solutions during local setup

Expand Down Expand Up @@ -129,6 +157,8 @@ This process ensures that any issues with the database schema are resolved by re
2. Policies can be validated dynamically as per
request while validating VP and
VC. [Check this for more details](https://docs.walt.id/v/ssikit/concepts/verification-policies)
3. When you are using MacOS and the MIW docker container won't start up, you can enable the docker-desktop feature "Use Rosetta for x86/amd64 emulation on Apple Silicon" in your Docker settings
(under "features in development")

## Reference of external lib

Expand Down

0 comments on commit 74fdb21

Please sign in to comment.