diff --git a/README.md b/README.md
index 1c1b0e7..aed75ba 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,17 @@
 # Vegasco Server
 
-Backend for the vegasco (***VE***hicle ***GAS*** ***CO***nsumption) application.
+Backend for the vegasco (**VE**hicle **GAS** **CO**nsumption) application.
 
 ## Getting Started
 
 ### Configuration
 
 | Configuration            | Description                                                                                                 | Default                                                    | Required |
-|--------------------------|-------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|----------|
-| JWT:MetadataUrl          | The oidc meta data url                                                                                      | -                                                          | true     |
-| JWT:ValidAudience        | The valid audience of the JWT token.                                                                        | -                                                          | true     |
-| JWT:NameClaimType        | The claim type of the user's name claim.                                                                    | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name | false    |
-| JWT:AllowHttpMetadataUrl | Whether to allow the meta data url to have http as protocol. Always true when `ASPNETCORE_ENVIRONMENT=true` | false                                                      | false    |
+|--------------------------|---------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|----------|
+| JWT:MetadataUrl          | The oidc meta data url                                                                                        | -                                                          | true     |
+| JWT:ValidAudience        | The valid audience of the JWT token.                                                                          | -                                                          | true     |
+| JWT:NameClaimType        | The claim type of the user's name claim. For keycloak, using `preferred_username` is often the better choice. | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name | false    |
+| JWT:AllowHttpMetadataUrl | Whether to allow the meta data url to have http as protocol. Always true when `ASPNETCORE_ENVIRONMENT=true`   | false                                                      | false    |
 
 The application uses the prefix `Vegasco_` for environment variable names. The prefix is removed when the application reads the environment variables and duplicate entries are overwritten by the environment variables. 
 
@@ -56,3 +56,12 @@ As appsettings.json (or a environment specific appsettings.*.json):
   }
 }
 ```
+
+### Running the application
+
+The solution uses Aspire to orchestrate the application. Specifically, it introduces sensible service defaults, including but not limited to OpenTelemetry,
+creates a Postgres database as a docker container, and starts the WebApi with the correct configuration to communicate with the database.
+
+Ensure you have an identity provider set up, for example Keycloak, and configured the relevant options described above.
+
+Then, to run the application, ensure you have Docker running, then run the `Vegasco.Server.AppHost` launch profile.