vegasco/README.md

# Vegasco Server

Vegasco (**VE**hicle **GAS** **CO**nsumption) application.

Includes the backend (`src/Vegasco.Server.Api`) and the frontend (`src/Vegasco-Web`). Utilizes [Aspire](https://learn.microsoft.com/en-us/dotnet/aspire/get-started/aspire-overview).

## 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. 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. 

Example:

- `foo=bar1`
- `Vegasco_foo=bar2`

Results in:

- `foo=bar2`
- `Vegasco_foo=bar2`

Configuration hierarchy in environment variables is usually denoted using a colon (`:`). But because on some systems the colon character is a reserved character, you can use a double underscore (`__`) as an alternative. The application will replace the double underscore with a colon when reading the environment variables.

Example:

The environment variable `foo__bar=value` (as well as `Vegasco_foo__bar=value`) will be converted to `foo:bar=value` in the application.

### Configuration examples

As environment variables:

```env
Vegasco_JWT__Authority=https://example.authority.com
Vegasco_JWT__Audience=example-audience
Vegasco_JWT__Issuer=https://example.authority.com/realms/example-realm/
Vegasco_JWT__NameClaimType=preferred_username
```

As appsettings.json (or a environment specific appsettings.*.json):

**Note: the `Vegasco_` prefix is only for environment variables**

```json
{
  "JWT": {
    "Authority": "https://example.authority.com/realms/example-realm",
    "Audience": "example-audience",
    "Issuer": "https://example.authority.com/realms/example-realm/",
    "NameClaimType": "preferred_username"
  }
}
```

### 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 Api 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 either the `http` or `https` launch profile of the `Vegasco.Server.AppHost` project.