Configuration

Configuration sources

Gnomeshade can be configured from:

These sources are layered on top of each other in that order, meaning that if all configuration sources contain the same configuration key, the last one will be used. For example, if

are set, the final value will be Information. NB Each array index is a separate key, so if, for example, there are 2 items in an array in appsettings.json and the first is also set in an environment variable, the second value from appsettings.json will remain. For more detailed documentation, see Microsoft documentation.

Applying changes

Some configuration sources support automatic reloading on changes during runtime, for example the appsettings.json files. Some configuration, such as Oidc and OAuth, is only read and applied on startup, so these will still require a restart in order to apply. However, other configuration such as Logging is automatically applied during runtime, so it's possible to change the minimum log levels without restarting.

Admin user

Gnomeshade requires and initial admin user. The default username is Admin, but the password needs to be specified. Here's an example configuration section: 

"Admin": {
	"Password": "******"
}

Database

Gnomeshade currently supports PostgreSQL from version 11 up to version 16beta1 and SQLite. The database provider can be selected using the Database:Provider key, and as PostgreSQL is the preferred database for production use, it is the default value. For PostgreSQL connection string parameters see Npgsql documentation; for SQLite see Microsoft documentation.

Here's an example configuration for PostgreSQL: 
"ConnectionStrings": {
	"Gnomeshade": "Host=localhost; Port=5432; Database=gnomeshade; Username=gnomeshade; Password=******;"
}

Migrations

Database migrations are automatically applied on server startup.

Authentication

Local accounts

Gnomeshade supports creating user accounts with multi-factor authentication. While it's always possible to use the web UI with username/password login, in order to use the API from client apps additional configuration is needed: 

"Jwt": {
	"ValidAudience": "http://localhost:8080",
	"ValidIssuer": "http://localhost:8080",
	"Secret": "E5G90jPHVfDdo3eNUX0q8h7fnazir3HR6QPe3P82McvpTJsAbmttO2kTOwhU22DE"
}

ValidAudience/ValidIssuer should be endpoint the server is listening on.

External providers

Gnomeshade supports using OIDC compliant external identity providers such as Keycloak. Here's an example configuration section with a realm realm-name: 

"Oidc": {
	"Keycloak": {
		"ServerRealm": "https://keycloak.home/realms/realm-name",
		"Metadata": "https://keycloak.home/realms/realm-name/.well-known/openid-configuration",
		"ClientId": "gnomeshade",
		"ClientSecret": "******"
	}
}

You can configure multiple OIDC providers by adding multiple such sections under the Oidc key. NB Changing the configuration section name, Keycloak in the example, will break any existing linked accounts using that provider.

Keycloak

You will need to create a confidential client (meaning it has a client secret), specifying your configured endpoint as a valid redirect URI. The example contains the default value. Gnomeshade also expects the access token have the audience set to the client id. In order to do that in Keycloak, you will need to create a new mapper for the client. Here's an example of the configuration that you will need to change for a new client in Keycloak:

  • Access Type = confidential
  • Valid Redirect URIs = http://localhost:8080/*
  • Mapper:
    • Mapper Type = Audience
    • Included Client Audience = {ClientId}
    • Add to access token = true

GitHub

Gnomeshade also supports using GitHub as an external identity provider. It's under the OAuth section instead of Oidc, because it GitHub currently does not support OIDC. Since some of the configuration for GitHub is already known, it's a little shorter: 

"OAuth": {
	"GitHub": {
		"ClientId": "5cde36402ea04bb5bdb1",
		"ClientSecret": "******"
	}
}

Web server

Here's an example configuration for production use according to Mozilla's modern compatability guide: 

"Kestrel": {
	"Endpoints": {
		"Https": {
			"Url": "https://gnomeshade.home:443",

			"CheckCertificateRevocation": true,
			"ClientCertificateMode": "Optional",
			"SslProtocols": ["Tls13"],
		}
	},
	"Certificates": {
		"Default": {
			"Path": "/path/to/certificate.p12",
			"Password": "******"
		}
	}
},
"Tls": {
	"CipherSuites": [
		"TLS_AES_128_GCM_SHA256",
		"TLS_AES_256_GCM_SHA384",
		"TLS_CHACHA20_POLY1305_SHA256"
	]
}

In order to be a bit more backwards compatible you can stick with intermediate compatability, by changing SslProtocols to ["Tls13", "Tls12"] and removing the Tls section. If the Tls section is not set, the system default cipher suites will be used.

For more detailed information on how to configure the Kestrel web server see the Microsoft documentation

Nordigen

Gnomeshade can automatically import transactions from your bank accounts via Nordigen. Using it requires register an account for free, and create a new secret. NB All secrets for a single Nordigen account have the same access. In order to have a development/testing secret which does not have access to production data, you need to create another Nordigen account, for which you can use a +alias. Here's an example configuration section: 

"Nordigen": {
	"SecretId": "da20e745-5292-4765-874e-1d0a1a4ee25a",
	"SecretKey": "******"
}

Paperless

Gnomeshade can automatically import purchases from linked documents from paperless-ngx. Here's an example configuration section: 

"Paperless": {
	"BaseAddress": "https://paperless.home/",
	"Token": ""******""
}

For information on how to create an API token see paperless documentation.

Open telemetry

Gnomeshade supports sending traces, metrics and logs to an OpenTelemetry compatible collector. Here's the default configuration (version is automatically set to the release version): 

"OpenTelemetry": {
	"Enabled": "true",
	"ServiceName": "Gnomeshade",
	"ServiceVersion": "1.0.0.0",
	"ExporterEndpoint": "http://localhost:4317",
	"ExportProtocol": "Grpc"
}

Signals can be exported in both Grpc and HttpProtobuf protocols. In practice it should only be required to set the ExporterEndpoint, and ExportProtocol if needed. 

"OpenTelemetry": {
	"ExporterEndpoint": "https://otel-colletor.home:4317"
}