docs: add examples doc

examples/.nickel/build.sh

@@ -3,7 +3,6 @@ find . -name "*.ncl" | xargs -I _ nickel format _
 nickel export ./root.ncl -f yaml --field st > ../st/compose.yaml
 nickel export ./root.ncl -f yaml --field st-vault > ../st-vault/compose.yaml
 nickel export ./root.ncl -f yaml --field st-multi > ../st-multi/compose.yaml
-nickel export ./root.ncl -f yaml --field st-oidc4vc > ../st-oidc4vc/compose.yaml
 
 nickel export ./root.ncl -f yaml --field mt > ../mt/compose.yaml
 nickel export ./root.ncl -f yaml --field mt-keycloak > ../mt-keycloak/compose.yaml

examples/.nickel/caddy.ncl

@@ -33,6 +33,7 @@ in
                 handle_path /vault* {
                   reverse_proxy %{args.vault.host}:%{std.to_string args.vault.port}
                 }
+                respond 404
               }
             "%
         }

examples/.shared/hurl/simple_realm/01_init_realm.hurl

@@ -6,6 +6,8 @@ HTTP 200
 
 # Admin login
 POST {{ keycloak_base_url }}/realms/master/protocol/openid-connect/token
+[Options]
+retry: 60
 [FormParams]
 grant_type: password
 client_id: admin-cli

examples/README.md

@@ -0,0 +1,60 @@
+# 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.
+
+## 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|
+|`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|
+
+# 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).

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`

examples/mt-keycloak-vault/compose.yaml

@@ -14,6 +14,7 @@ configs:
         handle_path /vault* {
           reverse_proxy vault-default:8200
         }
+        respond 404
       }
 services:
   agent-default:

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`

examples/mt-keycloak/compose.yaml

@@ -14,6 +14,7 @@ configs:
         handle_path /vault* {
           reverse_proxy vault-default:8200
         }
+        respond 404
       }
 services:
   agent-default:

examples/mt/README.md

@@ -0,0 +1,5 @@
+## Configuration
+
+|Exposed Service|Description|
+|-|-|
+|`localhost:8080/prism-agent`|Multi-tenant Cloud Agent|

examples/mt/compose.yaml

@@ -14,6 +14,7 @@ configs:
         handle_path /vault* {
           reverse_proxy vault-default:8200
         }
+        respond 404
       }
 services:
   agent-default:

examples/st-multi/README.md

@@ -0,0 +1,7 @@
+## Configuration
+
+|Exposed Service|Description|
+|-|-|
+|`localhost:8080/prism-agent`|Single-tenant Cloud Agent#1 (issuer)|
+|`localhost:8081/prism-agent`|Single-tenant Cloud Agent#2 (holder)|
+|`localhost:8082/prism-agent`|Single-tenant Cloud Agent#3 (verifier)|

examples/st-multi/compose.yaml

@@ -14,6 +14,7 @@ configs:
         handle_path /vault* {
           reverse_proxy vault-holder:8200
         }
+        respond 404
       }
   caddyfile_issuer:
     content: |-
@@ -30,6 +31,7 @@ configs:
         handle_path /vault* {
           reverse_proxy vault-issuer:8200
         }
+        respond 404
       }
   caddyfile_verifier:
     content: |-
@@ -46,6 +48,7 @@ configs:
         handle_path /vault* {
           reverse_proxy vault-verifier:8200
         }
+        respond 404
       }
 services:
   agent-holder: