ThompsonNye
4c00f868c7
All checks were successful
continuous-integration/drone/push Build is passing
70 lines
3.5 KiB
Markdown
70 lines
3.5 KiB
Markdown
# 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.
|