docs: add local stack examples [skip ci] (#939)

Signed-off-by: Pat Losoponkul <[email protected]> Signed-off-by: Hyperledger Bot <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Hyperledger Bot <[email protected]>
hyperledger · Jul 12, 2024 · ee2c239 · ee2c239
1 parent fa5121a
commit ee2c239
Show file tree

Hide file tree

Showing 24 changed files with 246 additions and 118 deletions.
diff --git a/examples/.nickel/caddy.ncl b/examples/.nickel/caddy.ncl
@@ -25,7 +25,7 @@ in
                 handle_path /didcomm* {
                   reverse_proxy %{args.agent.host}:%{std.to_string args.agent.didcommPort}
                 }
-                handle_path /prism-agent* {
+                handle_path /agent* {
                   reverse_proxy %{args.agent.host}:%{std.to_string args.agent.restPort}
                 }
                 handle_path /keycloak* {

diff --git a/examples/.nickel/stack.ncl b/examples/.nickel/stack.ncl
@@ -159,7 +159,7 @@ in
                     agentDb = makeSharedDbConfig "agent",
                     node = { host = "node" },
                     didcommServiceUrl = "http://%{hosts.caddy}:%{std.to_string args.port}/didcomm",
-                    restServiceUrl = "http://%{hosts.caddy}:%{std.to_string args.port}/prism-agent",
+                    restServiceUrl = "http://%{hosts.caddy}:%{std.to_string args.port}/agent",
                     apikeyEnabled = args.apikeyEnabled,
                   }
                   & (
@@ -200,12 +200,12 @@ in
                       version = V.hurl,
                       hurlDir = "../.shared/hurl/simple_realm",
                       variables = {
-                        HURL_KEYCLOAK_BASE_URL = "http://%{hosts.keycloak}:8080",
-                        HURL_KEYCLOAK_ADMIN_USER = "admin",
-                        HURL_KEYCLOAK_ADMIN_PASSWORD = "admin",
-                        HURL_KEYCLOAK_REALM = "identus",
-                        HURL_KEYCLOAK_CLIENT_ID = "agent",
-                        HURL_KEYCLOAK_CLIENT_SECRET = "agent-secret",
+                        HURL_keycloak_base_url = "http://%{hosts.keycloak}:8080",
+                        HURL_keycloak_admin_user = "admin",
+                        HURL_keycloak_admin_password = "admin",
+                        HURL_keycloak_realm = "identus",
+                        HURL_keycloak_client_id = "agent",
+                        HURL_keycloak_client_secret = "agent-secret",
                       }
                     },
               }

diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,74 @@
+# How to run examples
+
+## Prerequisites
+
+- docker-compose version >= `2.23.1`
+
+## Running examples
+
+Most of the examples should follow the same pattern.
+Simply go to each example directory and spin up the docker-compose of each example.
+
+```bash
+cd <EXAMPLE_DIR>
+docker-compose up
+```
+
+If some example requires a different command, it should be provided in its own local README.
+
+Once finished, `docker-compose down --volumes` can be used to clean docker volumes to avoid unexpected behavior for the next run.
+
+## Examples
+
+| example             | description                                                               |
+|---------------------|---------------------------------------------------------------------------|
+| `st`                | single-tenant configuration without external services (except database)   |
+| `st-multi`          | 3 instances of single-tenant configuration                                |
+| `st-vault`          | single-tenant with Vault for secret storage                               |
+| `st-oid4vci`        | single-tenant agent with Keycloak as external Issuer Authorization Server |
+| `mt`                | multi-tenant configuration using built-in IAM                             |
+| `mt-keycloak`       | multi-tenant configuration using Keycloak for IAM                         |
+| `mt-keycloak-vault` | multi-tenant configuration using Keycloak and Vault                       |
+
+## Testing examples
+
+Some example directories may contain a sub-directory called `hurl`.
+Hurl is a CLI tool for testing HTTP requests and can be installed according to [this documentation](https://hurl.dev/docs/installation.html).
+If the example contains a sub-directory named `hurl`, the example can be tested against HTTP calls with the following commands.
+
+```bash
+cd ./hurl
+hurl --variables-file ./local *.hurl --test
+```
+
+# Contributing
+
+All of the docker-compose files in examples are generated using [Nickel](https://nickel-lang.org/).
+They are defined in a shared `.nickel` directory and generated using the `build.sh` script.
+
+## Prerequisites
+
+- [Nickel](https://nickel-lang.org/) version >= `1.5` installed
+
+## Generate example compose files
+
+To generate the docker-compose config for all examples, run
+
+```bash
+cd .nickel
+./build.sh
+```
+
+## Updating example compose files
+
+To update the configuration, simply edit the `*.ncl` config in the `.nickel` directory and regenerate the docker-compose files.
+
+## Adding new examples
+
+To add a new example with docker-compose file, simply create a new configuration key in the `root.ncl` and add a new entry in the `build.sh` script.
+You may need to create the target example directory if it does not already exist.
+
+## Example with bootstrapping script
+
+If any example requires initialize steps, it should be made part of the docker-compose `depends_on` construct.
+Ideally, infrastructure bootstrapping should be automatic (database, IAM), but not necessarily application bootstrapping (tenant onboarding).
diff --git a/examples/mt-keycloak-vault/README.md b/examples/mt-keycloak-vault/README.md
@@ -0,0 +1,16 @@
+## Configuration
+
+| Exposed Service                 | Description              |
+|---------------------------------|--------------------------|
+| `localhost:8080/prism-agent`    | Multi-tenant Cloud Agent |
+| `localhost:8080/keycloak/admin` | Keycloak                 |
+| `localhost:8200`                | Vault                    |
+
+__Keycloak__
+
+- Admin user `admin`
+- Admin password `admin`
+
+__Vault__
+
+- Root token `admin`
diff --git a/examples/mt-keycloak-vault/compose.yaml b/examples/mt-keycloak-vault/compose.yaml
@@ -5,7 +5,7 @@ configs:
         handle_path /didcomm* {
           reverse_proxy agent-default:8090
         }
-        handle_path /prism-agent* {
+        handle_path /agent* {
           reverse_proxy agent-default:8085
         }
         handle_path /keycloak* {
@@ -46,10 +46,10 @@ services:
       POLLUX_DB_PASSWORD: postgres
       POLLUX_DB_PORT: '5432'
       POLLUX_DB_USER: postgres
-      POLLUX_STATUS_LIST_REGISTRY_PUBLIC_URL: http://caddy-default:8080/prism-agent
+      POLLUX_STATUS_LIST_REGISTRY_PUBLIC_URL: http://caddy-default:8080/agent
       PRISM_NODE_HOST: node
       PRISM_NODE_PORT: '50053'
-      REST_SERVICE_URL: http://caddy-default:8080/prism-agent
+      REST_SERVICE_URL: http://caddy-default:8080/agent
       SECRET_STORAGE_BACKEND: vault
       VAULT_ADDR: http://vault-default:8200
       VAULT_TOKEN: admin
@@ -103,12 +103,12 @@ services:
     - /hurl/*.hurl
     - --test
     environment:
-      HURL_KEYCLOAK_ADMIN_PASSWORD: admin
-      HURL_KEYCLOAK_ADMIN_USER: admin
-      HURL_KEYCLOAK_BASE_URL: http://keycloak-default:8080
-      HURL_KEYCLOAK_CLIENT_ID: agent
-      HURL_KEYCLOAK_CLIENT_SECRET: agent-secret
-      HURL_KEYCLOAK_REALM: identus
+      HURL_keycloak_admin_password: admin
+      HURL_keycloak_admin_user: admin
+      HURL_keycloak_base_url: http://keycloak-default:8080
+      HURL_keycloak_client_id: agent
+      HURL_keycloak_client_secret: agent-secret
+      HURL_keycloak_realm: identus
     image: ghcr.io/orange-opensource/hurl:4.2.0
     volumes:
     - ../.shared/hurl/simple_realm:/hurl

diff --git a/...keycloak-vault/tests/01_create_users.hurl → ...-keycloak-vault/hurl/01_create_users.hurl b/...keycloak-vault/tests/01_create_users.hurl → ...-keycloak-vault/hurl/01_create_users.hurl
@@ -66,7 +66,7 @@ HTTP 200
 issuer_access_token: jsonpath "$.access_token"
 
 # Create Issuer wallet
-POST {{ agent_url }}/prism-agent/wallets
+POST {{ agent_url }}/agent/wallets
 Authorization: Bearer {{ issuer_access_token }}
 {
   "name": "issuer-wallet"
@@ -85,7 +85,7 @@ HTTP 200
 holder_access_token: jsonpath "$.access_token"
 
 # Create Holder wallet
-POST {{ agent_url }}/prism-agent/wallets
+POST {{ agent_url }}/agent/wallets
 Authorization: Bearer {{ holder_access_token }}
 {
   "name": "holder-wallet"
@@ -104,7 +104,7 @@ HTTP 200
 verifier_access_token: jsonpath "$.access_token"
 
 # Create Verifier wallet
-POST {{ agent_url }}/prism-agent/wallets
+POST {{ agent_url }}/agent/wallets
 Authorization: Bearer {{ verifier_access_token }}
 {
   "name": "verifier-wallet"

diff --git a/.../mt-keycloak-vault/tests/02_jwt_flow.hurl → ...s/mt-keycloak-vault/hurl/02_jwt_flow.hurl b/.../mt-keycloak-vault/tests/02_jwt_flow.hurl → ...s/mt-keycloak-vault/hurl/02_jwt_flow.hurl
@@ -39,7 +39,7 @@ verifier_access_token: jsonpath "$.access_token"
 # Prerequisites
 ##############################
 # Issuer create DID
-POST {{ agent_url }}/prism-agent/did-registrar/dids
+POST {{ agent_url }}/agent/did-registrar/dids
 Authorization: Bearer {{ issuer_access_token }}
 {
   "documentTemplate": {
@@ -54,10 +54,10 @@ Authorization: Bearer {{ issuer_access_token }}
 }
 HTTP 201
 [Captures]
-issuer_did: jsonpath "$.longFormDid" regex "(did:prism:[a-z0-9]+):.+$"
+issuer_did: jsonpath "$.longFormDid" # regex "(did:prism:[a-z0-9]+):.+$"
 
 # Holder create DID
-POST {{ agent_url }}/prism-agent/did-registrar/dids
+POST {{ agent_url }}/agent/did-registrar/dids
 Authorization: Bearer {{ holder_access_token }}
 {
   "documentTemplate": {
@@ -78,7 +78,7 @@ holder_did: jsonpath "$.longFormDid" regex "(did:prism:[a-z0-9]+):.+$"
 # Issuance Connection
 ##############################
 # Inviter create connection
-POST {{ agent_url }}/prism-agent/connections
+POST {{ agent_url }}/agent/connections
 Authorization: Bearer {{ issuer_access_token }}
 {
   "label": "My Connection"
@@ -89,7 +89,7 @@ raw_invitation: jsonpath "$.invitation.invitationUrl" regex ".*_oob=(.*)$"
 issuer_connection_id: jsonpath "$.connectionId"
 
 # Invitee accept connection
-POST {{ agent_url }}/prism-agent/connection-invitations
+POST {{ agent_url }}/agent/connection-invitations
 Authorization: Bearer {{ holder_access_token }}
 {
   "invitation": "{{ raw_invitation }}"
@@ -99,7 +99,7 @@ HTTP 200
 holder_connection_id: jsonpath "$.connectionId"
 
 # Wait for inviter connection status
-GET {{ agent_url }}/prism-agent/connections/{{ issuer_connection_id }}
+GET {{ agent_url }}/agent/connections/{{ issuer_connection_id }}
 Authorization: Bearer {{ issuer_access_token }}
 [Options]
 retry: -1
@@ -108,7 +108,7 @@ HTTP 200
 jsonpath "$.state" == "ConnectionResponseSent"
 
 # Wait for invitee connection status
-GET {{ agent_url }}/prism-agent/connections/{{ holder_connection_id }}
+GET {{ agent_url }}/agent/connections/{{ holder_connection_id }}
 Authorization: Bearer {{ holder_access_token }}
 [Options]
 retry: -1
@@ -120,7 +120,7 @@ jsonpath "$.state" == "ConnectionResponseReceived"
 # Issuance
 ##############################
 # Issuer create credential offer
-POST {{ agent_url }}/prism-agent/issue-credentials/credential-offers
+POST {{ agent_url }}/agent/issue-credentials/credential-offers
 Authorization: Bearer {{ issuer_access_token }}
 {
   "claims": {
@@ -138,7 +138,7 @@ issuer_cred_record_id: jsonpath "$.recordId"
 didcomm_issuing_thid: jsonpath "$.thid"
 
 # Holder wait for OfferReceived state
-GET {{ agent_url }}/prism-agent/issue-credentials/records
+GET {{ agent_url }}/agent/issue-credentials/records
 Authorization: Bearer {{ holder_access_token }}
 [QueryStringParams]
 thid: {{ didcomm_issuing_thid }}
@@ -151,15 +151,15 @@ jsonpath "$.contents[0].protocolState" == "OfferReceived"
 holder_cred_record_id: jsonpath "$.contents[0].recordId"
 
 # Holder accept a credential-offer
-POST {{ agent_url }}/prism-agent/issue-credentials/records/{{ holder_cred_record_id }}/accept-offer
+POST {{ agent_url }}/agent/issue-credentials/records/{{ holder_cred_record_id }}/accept-offer
 Authorization: Bearer {{ holder_access_token }}
 {
   "subjectId": "{{ holder_did }}"
 }
 HTTP 200
 
 # Holder wait for CredentialReceived state
-GET {{ agent_url }}/prism-agent/issue-credentials/records/{{ holder_cred_record_id }}
+GET {{ agent_url }}/agent/issue-credentials/records/{{ holder_cred_record_id }}
 Authorization: Bearer {{ holder_access_token }}
 [Options]
 retry: -1
@@ -168,7 +168,7 @@ HTTP 200
 jsonpath "$.protocolState" == "CredentialReceived"
 
 # Issuer wait for CredentialSent state
-GET {{ agent_url }}/prism-agent/issue-credentials/records/{{ issuer_cred_record_id }}
+GET {{ agent_url }}/agent/issue-credentials/records/{{ issuer_cred_record_id }}
 Authorization: Bearer {{ issuer_access_token }}
 [Options]
 retry: -1
@@ -180,7 +180,7 @@ jsonpath "$.protocolState" == "CredentialSent"
 # Presentation Connection
 ##############################
 # Inviter create connection
-POST {{ agent_url }}/prism-agent/connections
+POST {{ agent_url }}/agent/connections
 Authorization: Bearer {{ verifier_access_token }}
 {
   "label": "My Connection"
@@ -191,7 +191,7 @@ raw_invitation: jsonpath "$.invitation.invitationUrl" regex ".*_oob=(.*)$"
 verifier_connection_id: jsonpath "$.connectionId"
 
 # Invitee accept connection
-POST {{ agent_url }}/prism-agent/connection-invitations
+POST {{ agent_url }}/agent/connection-invitations
 Authorization: Bearer {{ holder_access_token }}
 {
   "invitation": "{{ raw_invitation }}"
@@ -201,7 +201,7 @@ HTTP 200
 holder_connection_id: jsonpath "$.connectionId"
 
 # Wait for inviter connection status
-GET {{ agent_url }}/prism-agent/connections/{{ verifier_connection_id }}
+GET {{ agent_url }}/agent/connections/{{ verifier_connection_id }}
 Authorization: Bearer {{ verifier_access_token }}
 [Options]
 retry: -1
@@ -210,7 +210,7 @@ HTTP 200
 jsonpath "$.state" == "ConnectionResponseSent"
 
 # Wait for invitee connection status
-GET {{ agent_url }}/prism-agent/connections/{{ holder_connection_id }}
+GET {{ agent_url }}/agent/connections/{{ holder_connection_id }}
 Authorization: Bearer {{ holder_access_token }}
 [Options]
 retry: -1
@@ -222,7 +222,7 @@ jsonpath "$.state" == "ConnectionResponseReceived"
 # Presentation
 ##############################
 # Verifier create presentation request
-POST {{ agent_url }}/prism-agent/present-proof/presentations
+POST {{ agent_url }}/agent/present-proof/presentations
 Authorization: Bearer {{ verifier_access_token }}
 {
   "connectionId": "{{ verifier_connection_id }}",
@@ -238,7 +238,7 @@ verifier_presentation_id: jsonpath "$.presentationId"
 didcomm_presentation_thid: jsonpath "$.thid"
 
 # Holder wait for RequestReceived state
-GET {{ agent_url }}/prism-agent/present-proof/presentations
+GET {{ agent_url }}/agent/present-proof/presentations
 Authorization: Bearer {{ holder_access_token }}
 [QueryStringParams]
 thid: {{ didcomm_presentation_thid }}
@@ -251,7 +251,7 @@ jsonpath "$.contents[0].status" == "RequestReceived"
 holder_presentation_id: jsonpath "$.contents[0].presentationId"
 
 # Holder accept presentation request
-PATCH {{ agent_url }}/prism-agent/present-proof/presentations/{{ holder_presentation_id }}
+PATCH {{ agent_url }}/agent/present-proof/presentations/{{ holder_presentation_id }}
 Authorization: Bearer {{ holder_access_token }}
 {
   "action": "request-accept",
@@ -260,7 +260,7 @@ Authorization: Bearer {{ holder_access_token }}
 HTTP 200
 
 # Holder wait for PresentationSent state
-GET {{ agent_url }}/prism-agent/present-proof/presentations
+GET {{ agent_url }}/agent/present-proof/presentations
 Authorization: Bearer {{ holder_access_token }}
 [QueryStringParams]
 thid: {{ didcomm_presentation_thid }}
@@ -271,7 +271,7 @@ HTTP 200
 jsonpath "$.contents[0].status" == "PresentationSent"
 
 # Verfiier wait for PresentationVerified state
-GET {{ agent_url }}/prism-agent/present-proof/presentations
+GET {{ agent_url }}/agent/present-proof/presentations
 Authorization: Bearer {{ verifier_access_token }}
 [QueryStringParams]
 thid: {{ didcomm_presentation_thid }}

diff --git a/examples/mt-keycloak-vault/tests/local → examples/mt-keycloak-vault/hurl/local b/examples/mt-keycloak-vault/tests/local → examples/mt-keycloak-vault/hurl/local
diff --git a/examples/mt-keycloak/README.md b/examples/mt-keycloak/README.md
@@ -0,0 +1,11 @@
+## Configuration
+
+| Exposed Service                 | Description              |
+|---------------------------------|--------------------------|
+| `localhost:8080/prism-agent`    | Multi-tenant Cloud Agent |
+| `localhost:8080/keycloak/admin` | Keycloak                 |
+
+__Keycloak__
+
+- Admin user `admin`
+- Admin password `admin`