Server Configuration

There are two methods for configuring the sever. Either by using a configuration file, or environment variables. Select between the two tabs to show examples of which source you require.

Configuration Sources

TOML

There are a few default locations that the server will look for configuration files

/etc/warecache/config.toml
/etc/warecache/config.d/
~/.local/config/warecache/config.toml
~/.local/config/warecache/config.d/
./wcd_config.toml

The more local the file is, the higher the precedence in settings. The config.d directories allow splitting configuration across multiple files (e.g., one per section). An example configuration file is shown below.

[general]
debug = true

[company]
name = "My Company"

[log]
output="std"
level="debug"
file="test.log"

[log.filters]
sqlx = "warn"
actix_web = "info"

[api]
port = 8118
address = '0.0.0.0'
externurl= 'localhost'
adminuser = 'admin'
adminpass = 'CHANGE_ME_PASSWORD'
ratelimit = true
ratelimitinterval = 4
ratelimitrequests = 5

[db]
address = 'localhost'
port = 5432
user = "wcd_items"
pass = "CHANGE_ME_PASSWORD"
db = "wc_items"
pool_size = 16
enable_profiling = false

[userdb]
address = 'localhost'
port = 5433
user = "wcd_users"
pass = "CHANGE_ME_PASSWORD"
db = "wc_users"
connections = 5

[mqtt]
address = 'warecache.example.com'
port = 8883
clientid = "example-server"
keepalive = 30
certpath = "./certs/client.crt"
keypath = "./certs/client.key"
rootcapath = "./certs/ca.crt"
cakeypath = "./certs/ca.key"
recv_workers = 2
sub_workers = 1
pub_workers = 1

[sentry]
dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
enabled = false
environment = "production"
samplerate = 1.0

[plugins]
directory = "/usr/share/warecache/plugins"
hot_reload = true
default_interval_secs = 86400

[analytics]
debounce_secs = 60

[oidc]
enabled = true

[[oidc.providers]]
name = "keycloak"
issuer = "https://keycloak.example.com/realms/warecache"
client_id = "warecache-api"
client_secret = "your-client-secret"
default_role = "guest"
auto_provision = true
groups_claim = "groups"
org_claim = "org_id"

[oidc.providers.group_role_map]
admin = ["warecache-admins", "/management"]
default = ["/engineering", "/operations"]
guest = ["/interns"]

Environment

Environment variables will overwrite configuration settings. The format for environment variables is the prefix WCD, with each configuration group and then individual setting. The delimiter is _.

An example variable for the api listen address is WCD_API_ADDRESS

Settings

General

Generic settings

Debug

Enables or disables debug mode.

Setting

tomlenv

[general]
debug = BOOL

WCD_GENERAL_DEBUG=BOOL

Acceptable values

Value	Description
True	Enable Debug mode
False	Disable Debug mode

log

Settings for output logs. The output can be to a file, to stdout, or syslog. If if the output is set to file, then the file setting must also be configured.

Output

Setting

tomlenv

[log]
output="string"

WCD_LOG_OUTPUT="string"

Acceptable values

Value	Description
std	Log to STDIO
file	Log to file
syslog	Log to syslog

Level

Settings for log levels. Each level incoroprates the prior levels. Use this setting to filter out unwanted messages in the logs, or to debug issues.

Setting

tomlenv

[log]
level="string"

WCD_LOG_LEVEL="string"

Acceptable values

Value	Description
error	Enable Error messages
warn	Enable Warning messages and above
info	Enable Info messages and above
debug	Enable Debug messages and above

File

Optional setting. It is only required when using the output log of file. It should be a path to the file; relative or absolute.

Setting

tomlenv

[log]
file="string"

WCD_LOG_FILE="/path/to/file"

Acceptable values

Value	Description
File Path	Path to file

Filters

Per-module log level overrides. Sensible defaults are built-in for noisy crates (sqlx=warn, actix_web=info, hyper=warn, etc.) so you only need to specify overrides here.

Setting

toml

[log.filters]
sqlx = "warn"
actix_web = "info"

Acceptable values

Value	Description
String	Log level for the module (error, warn, info, debug)

API

API specific settings

Address

The address that the API should listen to. This can be an IP address or FQDN.

Setting

tomlenv

[api]
address="string"

WCD_API_ADDRESS="string"

Acceptable values

Value	Description
String	IP Address or FQDN

Port

The port the API service should listen to.

Setting

tomlenv

[api]
port = 30

WCD_API_PORT="/path/to/file"

Acceptable values

Value	Description
Integer	Port number

External URL

The external URL that the API service should expect. This is required for CORS. The URL used here should be identical to the one that is used for creating the certificates.

Setting

tomlenv

[api]
externurl="string"

WCD_API_EXTERNURL="string"

Acceptable values

Value	Description
String	IP Address or FQDN

Admin User

Default admin username. This will only be set once; it cannot be changed after the initial creation.

Setting

tomlenv

[api]
adminuser="string"

WCD_API_ADMINUSER="string"

Acceptable values

Value	Description
String	Admin username

Admin Password

Default admin password. This will only be set once; it cannot be changed after the initial creation. Please ensure that this password is secure and there is no default password.

Setting

tomlenv

[api]
adminpass="string"

WCD_API_ADMINPASS="string"

Acceptable values

Value	Description
String	Admin password

Rate Limit

Enable rate limiting on unauthenticated endpoints.

Setting

tomlenv

[api]
ratelimit = BOOL

WCD_API_RATELIMIT=BOOL

Acceptable values

Value	Description
True	Enable rate limiting
False	Disable rate limiting

Rate Limit Interval

Seconds per request for rate limiting.

Setting

tomlenv

[api]
ratelimitinterval = 4

WCD_API_RATELIMITINTERVAL=4

Acceptable values

Value	Description
Integer	Interval in seconds

Rate Limit Requests

Burst size for rate limiting (max requests per interval).

Setting

tomlenv

[api]
ratelimitrequests = 5

WCD_API_RATELIMITREQUESTS=5

Acceptable values

Value	Description
Integer	Maximum requests per interval

DB

Item Database settings

Address

The item database address. Can be a FQDN, or ip address.

Setting

tomlenv

[db]
address="string"

WCD_DB_ADDRESS="string"

Acceptable values

Value	Description
String	IP Address or FQDN

Port

The item database port.

Setting

tomlenv

[db]
port = 30

WCD_DB_PORT="/path/to/file"

Acceptable values

Value	Description
Integer	Port number

Username

The username to authenticate with the item database.

Setting

tomlenv

[db]
user="string"

WCD_DB_USER="string"

Acceptable values

Value	Description
String	Username

Password

The password to authenticate with the item database.

Setting

tomlenv

[db]
pass="string"

WCD_DB_PASS="string"

Acceptable values

Value	Description
String	Password

Database Name

The database name for the item database.

Setting

tomlenv

[db]
db="string"

WCD_DB_DB="string"

Acceptable values

Value	Description
String	Database Name

Pool Size

The number of connections in the database connection pool.

Setting

tomlenv

[db]
pool_size = 16

WCD_DB_POOL_SIZE=16

Acceptable values

Value	Description
Integer	Number of pool connections

Enable Profiling

Enable the pg_stat_statements extension for query profiling.

Setting

tomlenv

[db]
enable_profiling = BOOL

WCD_DB_ENABLE_PROFILING=BOOL

Acceptable values

Value	Description
True	Enable profiling
False	Disable profiling

UserDB

User Account Database settings

Address

The user database address. Can be a FQDN, or ip address.

Setting

tomlenv

[userdb]
address="string"

WCD_USERDB_ADDRESS="string"

Acceptable values

Value	Description
String	IP Address or FQDN

Port

The user database port.

Setting

tomlenv

[userdb]
port = 30

WCD_USERDB_PORT="/path/to/file"

Acceptable values

Value	Description
Integer	Port number

Username

The username to authenticate with the user database.

Setting

tomlenv

[userdb]
user="string"

WCD_USERDB_USER="string"

Acceptable values

Value	Description
String	Username

Password

The password to authenticate with the user database.

Setting

tomlenv

[userdb]
pass="string"

WCD_USERDB_PASS="string"

Acceptable values

Value	Description
String	Password

Database Name

The database name for the user database.

Setting

tomlenv

[userdb]
db="string"

WCD_USERDB_DB="string"

Acceptable values

Value	Description
String	Database Name

Connections

The number of connections in the user database connection pool.

Setting

tomlenv

[userdb]
connections = 5

WCD_USERDB_CONNECTIONS=5

Acceptable values

Value	Description
Integer	Number of pool connections

MQTT

MQTT Connection Settings

Address

The MQTT server address. Can be a FQDN or an ip address.

Setting

tomlenv

[mqtt]
address="string"

WCD_MQTT_ADDRESS="string"

Acceptable values

Value	Description
String	IP Address or FQDN

Port

The MQTT server port. Should be 8883 for secured connections. All branded warecache devices support encrypted MQTT connections. Be weary of security risks without secured connections.

Setting

tomlenv

[mqtt]
port = 30

WCD_MQTT_PORT="/path/to/file"

Acceptable values

Value	Description
Integer	Port number

Client ID

The client name for the server to use when connecting to the MQTT server. It will appear in the MQTT server logs for reference.

Setting

tomlenv

[mqtt]
clientid="string"

WCD_MQTT_CLIENTID="string"

Acceptable values

Value	Description
String	Client ID

Keepalive

The required keepalive ping to the MQTT server from the client. Some MQTT servers will disconnect if the proper keepalive is not set.

Setting

tomlenv

[mqtt]
keepalive = 30

WCD_MQTT_KEEPALIVE="/path/to/file"

Acceptable values

Value	Description
Integer	Keepalive in seconds

Client Certificate

The x509 certificate that the server uses to authenticate with the MQTT server.

Setting

tomlenv

[mqtt]
certpath="string"

WCD_MQTT_CERTPATH="/path/to/file"

Acceptable values

Value	Description
File Path	Path to file

Client Key

The x509 key that the server uses to authenticate with the MQTT server.

Setting

tomlenv

[mqtt]
keypath="string"

WCD_MQTT_KEYPATH="/path/to/file"

Acceptable values

Value	Description
File Path	Path to file

Root Certificate Authority

The root certificate authority that signed the client certificate.

Setting

tomlenv

[mqtt]
rootcapath="string"

WCD_MQTT_ROOTCAPATH="/path/to/file"

Acceptable values

Value	Description
File Path	Path to file

Root Certificate Authority Key

The x509 key for the root certificate authority

Setting

tomlenv

[mqtt]
cakeypath="string"

WCD_MQTT_CAKEYPATH="/path/to/file"

Acceptable values

Value	Description
File Path	Path to file

Subscription Workers

Number of worker threads for receiving MQTT messages.

Setting

tomlenv

[mqtt]
sub_workers = 1

WCD_MQTT_SUB_WORKERS=1

Acceptable values

Value	Description
Integer	Number of worker threads

Receive Workers

Number of worker threads for processing incoming MQTT messages.

Setting

tomlenv

[mqtt]
recv_workers = 2

WCD_MQTT_RECV_WORKERS=2

Acceptable values

Value	Description
Integer	Number of worker threads

Publish Workers

Number of worker threads for sending outgoing MQTT messages.

Setting

tomlenv

[mqtt]
pub_workers = 1

WCD_MQTT_PUB_WORKERS=1

Acceptable values

Value	Description
Integer	Number of worker threads

Sentry

Sentry (crash reporting) specific settings

DSN

Sentry provided URL for project

Setting

tomlenv

[sentry]
dsn="string"

WCD_SENTRY_DSN="string"

Acceptable values

Value	Description
String	Sentry DSN URL

Enabled

Enable or disable the sentry reporting.

Setting

tomlenv

[sentry]
enabled = BOOL

WCD_SENTRY_ENABLED=BOOL

Acceptable values

Value	Description
True	Enable Sentry tracking
False	Disable Sentry tracking

Environment

Sentry project name/environment

Setting

tomlenv

[sentry]
environment="string"

WCD_SENTRY_ENVIRONMENT="string"

Acceptable values

Value	Description
String	Environment name (e.g., development, staging, production)

Sample Rate

Reporting rate in percentage. Will report the percentage of errors defined.

Setting

tomlenv

[sentry]
samplerate = 1.0

WCD_SENTRY_SAMPLERATE="float"

Acceptable values

Value	Description
Float	Sampling rate from 0.0 (none) to 1.0 (all)

Company

Company/organization configuration.

Name

The company or organization name.

Setting

tomlenv

[company]
name="string"

WCD_COMPANY_NAME="string"

Acceptable values

Value	Description
String	Company name

Plugins

Plugin system configuration.

Hot Reload

Enable hot reloading of plugins. When enabled, changes to plugins are picked up automatically without restarting the server.

Setting

tomlenv

[plugins]
hot_reload = BOOL

WCD_PLUGINS_HOT_RELOAD=BOOL

Acceptable values

Value	Description
True	Enable hot reloading
False	Disable hot reloading

Default Interval

The default sync interval for plugins in seconds.

Setting

tomlenv

[plugins]
default_interval_secs = 86400

WCD_PLUGINS_DEFAULT_INTERVAL_SECS=86400

Acceptable values

Value	Description
Integer	Interval in seconds

Analytics

Analytics background processing configuration.

Debounce

Debounce period in seconds after a wake-up event before recomputing project costs.

Setting

tomlenv

[analytics]
debounce_secs = 60

WCD_ANALYTICS_DEBOUNCE_SECS=60

Acceptable values

Value	Description
Integer	Debounce period in seconds

OIDC

OpenID Connect authentication configuration. When enabled, users can authenticate via external identity providers.

Enabled

Enable or disable OIDC authentication.

Setting

tomlenv

[oidc]
enabled = BOOL

WCD_OIDC_ENABLED=BOOL

Acceptable values

Value	Description
True	Enable OIDC authentication
False	Disable OIDC authentication

Providers

A list of OIDC provider configurations. Each provider is defined as an entry in the [[oidc.providers]] array.

Provider Settings

Each provider entry supports the following settings:

Name

The provider name used for identification.

toml

[[oidc.providers]]
name="string"

Issuer

The OIDC issuer URL.

toml

[[oidc.providers]]
issuer="string"

Client ID

The OIDC client ID.

toml

[[oidc.providers]]
client_id="string"

Client Secret

The OIDC client secret.

toml

[[oidc.providers]]
client_secret="string"

Default Role

The default role assigned when no group mapping matches. Defaults to guest.

toml

[[oidc.providers]]
default_role="string"

Auto Provision

Automatically create users on first OIDC login.

toml

[[oidc.providers]]
auto_provision = BOOL

Groups Claim

The ID token claim used for group memberships. Defaults to groups.

toml

[[oidc.providers]]
groups_claim="string"

Organization Claim

Optional ID token claim for organization/tenant ID.

toml

[[oidc.providers]]
org_claim="string"

Group Role Map

Mapping of roles to groups. Hierarchical matching is supported for path-style groups (e.g., /engineering also matches /engineering/firmware).

toml

[oidc.providers.group_role_map]
admin = ["warecache-admins", "/management"]
default = ["/engineering", "/operations"]
guest = ["/interns"]