fix: improve readme

Signed-off-by: Mirko Mollik <mirkomollik@gmail.com>

README.md

@@ -5,37 +5,55 @@ Instead of building a framework for wallets in one programming language, this re
 
 # Setup
 
-## Running
-
-- Copy the `.env.example` file to `.env` and optionally modify the values.
-- Run `docker compose up` to start a database and the issuer/holder/verifier/backend services as well as a keycloak instance.
-  - If you have already have a keycloak instance, set `KEYCLOAK_AUTH_URL` accordingly and run 
-  `docker compose up --scale postgres-keycloak=0 --scale keycloak=0`.
-- Configure Keycloak
-    - If you use the local one
-      - Open http://localhost:8080/ 
-      - Login with the credentials set in the env file
-      - Create a new Realm from `./keycloak/realm-export.json`
-      - Goto http://localhost to open the wallet ui
-      - Login
-      - Register a new user
+## Running - Docker
+To run the docker compose setup, copy the `.env.example` to `.env` in the root folder. Modify the values if required.
+Run `docker compose up -d` to start a database and the issuer/holder/verifier/backend services as well as a keycloak instance. It will downlaod the images from the docker registry. In case you want to run your modified apps, run `docker compose build` to build the images locally.
+
+Known limitations: right now running it locally via docker can cause some problems since `localhost` is used to interact with some services.
+
+## Running - NPM
+To work in developpment mode, you can start the services via `pnpm`. It's possible to run all of them via `pnpm` or some via `docker`.
+
+To run the application with `pnpm`, you need to enable corepack by `corepack enable`.
+
+
+## Keycloak
+You can start a local instance of keycloak to manage user authentication for the cloud wallet. When you start keycloak for the first time, it will install the realm wallet located in the `config/keycloak/realm-export.json`. In case you want to use another keycloak instance, you can import the realm there. It should also be possible to use any other OIDC system.
+
+In the default realm settings, there is no restirction to the origin of the requests and registration is open for everyone. There is also no implementation of keycloak or cloud wallet events like creating or deleting a user object.
+
+The configuration of the pwa client is mounted from the `config/holder/config.js` file. Mount the config into the container and don't forget to modify it when it's hosted online.
 
 ## Development
 
 To install all dependencies needed to run the apps locally, install [pnpm](https://pnpm.io/) and run `pnpm install` in the root folder.
+Before you need to install `pnpm` to work with this repository. After this run `pnpm install` in the root folder to install all dependencies for all apps.
+
+There are some jobs in the `package.json` like `build`, `clean` and `lint`. App specifc jobs are found in the app folders.
 
 # Apps
+This project is a monorepo managed by `pnpm`. All apps are under the apps folder, there is no shared code between the apps right now.
+
+## Issuer
+The issuer app is a rest api, supporting the oid4vci protocol. Right now there is only one demo credential available. Start the issuer with `pnpm run dev`. Don't forget to have an `.env` file in the folder to configure the application, it will not use the `.env` file in the root folder.
 
-# Issuer
-The issuer app is a rest api, supporting the oid4vci protocol. Right now there is only one demo credential available. Start the issuer with `pnpm run dev`.
+## Verifier
+The verifier app is a rest api, supporting the oid4vcp protocol. The verifier can verify the demo credential from the issuer. Start the verifier with `pnpm run dev`. Don't forget to have an `.env` file in the folder to configure the application, it will not use the `.env` file in the root folder.
 
-# Verifier
-The verifier app is a rest api, supporting the oid4vcp protocol. The verifier can verify the demo credential from the issuer. Start the verifier with `pnpm run dev`.
+## Wallent clients
+This repository includes two clients. One is a progressive web app, the other one is a chrome browser extension. Both are managed via angular and share the same code base.
 
-# Browser Plugin
-The command `pnpm run start:dev` in the `browser-wallet` folder will watch on the build files. To use this plugin in the chrome browser during development, go to `chrome://extensions/` and enable developer mode. Then click on `Load unpacked` and select the `dist/wallet-extension` folder in the `browser-wallet` folder. To get the updates active, you need to reopen the plugin in the browser (hitting refresh on the plugin page is not required).
+Since the backend is following the openAPI specification, an SDK to interact with it can be generated by running `pnpm run api`.
+
+### PWA Client
+The command `pnpm run start:pwa` will run the application in the watch mode. It will start a webserver on port `localhost:4200` and reload when you changed the code. The configuration is managed in the `assets/config` folders. This approach allows a dynamic config since it can be mounted into the docker container without the need of recompiling it.
+
+### Browser Plugin
+The command `pnpm run start:extension` in the `holder` folder will watch on the build files. To use this plugin in the chrome browser during development, go to `chrome://extensions/` and enable developer mode. Then click on `Load unpacked` and select the `dist/browser-extension` folder in the `browser-extension` folder. To get the updates active, you need to reopen the plugin in the browser (hitting refresh on the plugin page is not required).
 
 Angular is using the webpack compiler instead of the modern esbuild. This is required since we need to build multiple file like the main and background file and right now it is not possible to pass a custom esbuild config to angular.
 
-# Backend
-All endpoints are available via the `http://localhost:3000` address. A swagger endpoint is available at `http://localhost:3000/api` where you can authenticate with your keycloak user credentials.
+## Backend
+All endpoints are available via the `http://localhost:3000` address. A swagger endpoint is available at `http://localhost:3000/api` where you can authenticate with your keycloak user credentials. Don't forget to have an `.env` file in the folder to configure the application, it will not use the `.env` file in the root folder.
+
+You can either use a postgres or sqlite database. In case of using postgres, there is one defined in the `docker-compose.yml` in the root folder. Don't forget to sync the credentials in the root `.env` file and the one in the backend folder to get a successfull connection.

apps/backend/.env.example

@@ -1,6 +1,6 @@
 # Keycloak config
 KEYCLOAK_AUTH_URL=https://keycloak.yanacocha.fit.fraunhofer.de
-KEYCLOAK_REALM=wallet-ssi
+KEYCLOAK_REALM=wallet
 KEYCLOAK_CLIENT_ID=swagger
 
 # DB config

apps/backend/src/auth/auth.module.ts

@@ -32,6 +32,7 @@ export const KEYCLOAK_VALIDATION_SCHEMA = {
           policyEnforcement: PolicyEnforcementMode.PERMISSIVE,
           //TODO: set this to online
           tokenValidation: TokenValidation.OFFLINE,
+          //TODO: maybe setting verifyTokenAudience could work with the localhost problem
         }) as KeycloakConnectOptions,
     }),
   ],

config/holder/config.js

@@ -1,6 +1,6 @@
 globalThis.environment = {
   backendUrl: 'http://localhost:3000',
-  keycloakHost: 'http://localhost:8080',
+  keycloakHost: 'http://host.docker.internal:8080',
   keycloakClient: 'browser',
   keycloakRealm: 'wallet',
   demoIssuer: 'http://localhost:3001',

docker-compose.yml

@@ -33,6 +33,7 @@ services:
         '--spi-theme-static-max-age=-1',
         '--spi-theme-cache-themes=false',
         '--spi-theme-cache-templates=false',
+        '--import-realm',
       ]
     depends_on:
       - 'postgres-keycloak'
@@ -45,9 +46,9 @@ services:
       KC_HOSTNAME_URL: $KEYCLOAK_HOSTNAME_URL
       KEYCLOAK_ADMIN: $KEYCLOAK_ADMIN
       KEYCLOAK_ADMIN_PASSWORD: $KEYCLOAK_ADMIN_PASSWORD
-      KEYCLOAK_IMPORT: /tmp/import/realm-export.json
+      KEYCLOAK_IMPORT: /opt/keycloak/data/import/realm-export.json
     volumes:
-      - ./config/keycloak/realm-export.json:/tmp/import/realm-export.json
+      - ./config/keycloak/realm-export.json:/opt/keycloak/data/import/realm-export.json
     ports:
       - '8080:8080'
 
@@ -82,7 +83,8 @@ services:
       PORT: $ISSUER_PORT
     volumes:
       - issuer_tmp:/app/tmp
-    network_mode: host
+    ports:
+      - 3001:3000
 
   verifier:
     image: ghcr.io/cre8/wallet/verifier
@@ -109,7 +111,8 @@ services:
       dockerfile: docker/node.Dockerfile
       args:
         - PROJECT=backend
-    network_mode: host
+    ports:
+      - 3000:3000
 
   holder:
     image: ghcr.io/cre8/wallet/holder

package.json

@@ -1,7 +1,7 @@
 {
   "name": "wallet",
   "version": "1.0.0",
-  "description": "",
+  "description": "A monorepo including multiple apps for SSI",
   "scripts": {
     "build": "pnpm run -r build",
     "clean": "pnpm run -r clean && rm -rf node_modules",