Config
Categories:
Configuration Sources
Configuration is performed using a JSON/Jsonnet configuration file, environment variables, and command line arguments. Configurations from one source will override previous sources, i.e. environment variables override configuration files, command line arguments override environment variables.
Command Line
Every configuration key can be set using -x <a_config_key1>="a value" -x <a_config_key2>="another value"
, i.e. -x cli_logLevel=debug -x cli_logFormat=kv
. Config values can also be set using JSON, i.e. -x cli='{"logLevel": "debug"}'
Command line values override all other sources.
Environment Variables
Every configuration key can be set using homechart_section_key=a value
or HOMECHART_section_key=a value
, i.e. homechart_cli_logLevel=debug
. A special environment variable, homechart_config
can be used to specify a complete JSON/Jsonnet configuration.
Environment Variables override a configuration file.
Configuration File
A configuration file be formatted using JSON or Jsonnet. Homechart looks for homechart.jsonnet
by default, ascending the directory tree to find it. See the Jsonnet reference for more information. Configuration files are rendered at startup, allowing you to use dynamic Jsonnet functions to dynamically alter the config, i.e.:
local getRecord(type, name, fallback=null) = std.native('getRecord')(type, name, fallback);
local level = getRecord('txt', 'level.candid.dev');
{
cli: [
logLevel: level,
],
}
You can view the rendered configuration by running homechart config
.
Configuration Values
app
adminEmailAddresses
(recommended)
List of strings, email addresses which will have admin access to Homechart for their account.
Default: []
baseURL
(recommended)
String, base URL for Homechart, mostly used by notifications.
Default: "https://web.homechart.app"
cacheTTLMinutes
Number, number of minutes to keep entries in cache.
Default: 15
demo
Boolean, allow users to create demo logins, mostly used by web.homechart.app. Easy way to try out Homechart.
Default: false
disableTasks
Boolean, disable any background tasks (sending notifications, cleaning up old data) from running on this instance.
Default: false
keepCalendarEventDays
Number, number of days to retain Calendar Events after their end date.
Default: 90
keepCookMealPlanDays
Number, number of days to retain Cook Meal Plans after their scheduled date.
Default: 90
keepDeletedDays
Number, number of days to keep deleted data (Notes, Recipes).
Default: 30
keepHealthLogDays
Number, number of days to retain Health Logs.
Default: 90
keepNotesPageVersions
Number, number of Notes Page Versions to keep.
Default: 10
keepPlanTasksDays
Number, number of days to keep completed tasks.
Default: 90
motd
String, informational message to display on the UI for all users.
Default: ""
port
Number, listening port for Homechart. Setup port forwarding to this port to expose Homechart externally.
Default: 3000
proxyAddress
String, Upstream IPv4 or IPv6 address of a trusted proxy. See the Single Sign-On (SSO) guide for usage details.
Default: ""
proxyHeaderEmail
String, proxy header that should be associated with an account email address. See Single Sign-On (SSO) guide for usage details.
Default: ""
proxyHeaderName
String, proxy header that should be associated with an account name. See Single Sign-On (SSO) guide for usage details.
Default: ""
rateLimiterRate
String, maximum number of requests over a specific time to public endpoints. Prevents brute force attacks. Takes the format of (number-H/M/S) where H=hour, M=minute, S=Second. The default, 15-H, means 15 requests per hour.
Default: "15-H"
rollupBudgetTransactionsBalanceMonths
Number, number of months before a Budget Transaction is rolled up into a starting balance.
Default: 48
rollupBudgetTransactionsSummaryMonths
Number, number of months before a Budget Transaction is rolled up into monthly summaries.
Default: 12
sessionExpirationDefaultSeconds
Number, time between non-Remember Me sessions expiring, in seconds.
Default: 3600
sessionExpirationRememberSeconds
Number, time between Remember Me sessions expiring, in seconds.
Default: 7776000
signupDisabled
(recommended)
Boolean, disables new account signups. Accounts can still be created/invited under the Admin > Accounts. Self-hosted instances should enable this after they have setup their household.
Default: false
tlsCertificate
(recommended)
String, path to a SSL/TLS certificate file. Should work for the domain in your baseURL. If set, along with tlsKey, Homechart will listen for HTTPS connections only. HTTPS is necessary for certain Homechart functionality, you should enable HTTPS within Homechart or your reverse proxy.
Default: ""
tlsKey
(recommended)
String, path to a SSL/TLS private key file. Should work for the domain in your baseURL. If set, along with tlsCertificate, Homechart will listen for HTTPS connections only. HTTPS is necessary for certain Homechart functionality, you should enable HTTPS within Homechart or your reverse proxy.
Default: ""
cli
configPath
String, path to the configuration file. If a filename without a path is specified, Rot will search parent directories for the filename and use the first one found.
Default: "homechart.jsonnet"
configReloadSec
Number of seconds to periodically reload the config and reload the application, if > 0.
Default: 0
configWatch
Boolean, if true then the configPath
will be watched for changes. On a change, the application will be reloaded.
Default: false
logFormat
String, log format to use for logging: human, kv, or raw.
Default: "human"
logLevel
String, log level to use for logging: none, debug, info, or error.
Default: "info"
macros
A map of macros to simplify and template CLI arguments. An example macro looks like this:
{
"cli": {
"macro": {
"mymacro": {
"argumentsRequired": [
"argument1"
],
"flags": {
"d": {
"usage": "D flag usage!"
},
},
"template": "config",
"usage": "Mymacro usage!",
}
}
}
}
This will add the macro, mymacro
to the CLI.
Default: {}
argumentsRequired
A list of arguments that are required for the macro.
Default: []
argumentsOptional
A list of arguments that are optional for the macro.
Default: []
flags
A map of flags for the macro.
Default: {}
default
A list of strings for the default value of the flag.
Default: []
options
A list of strings the flag can be set to.
Default: []
placeholder
String, the placeholder name for the flag if it accepts a value.
Default: ""
usage
String, the usage instructions for the flag.
Default: ""
template
String, the Go template syntax that will be rendered, appended to the CLI, and ran. The Go template can use these custom functions:
{{ getArg i int f string }}
Get an argument at positioni
or return fallbackf
.{{ getEnv e string f string }}
Get an environment variablee
or return fallbackf
.{{ getFlag f string }}
Get the flag values forf
. For flags with a placeholder, this will be an array of string values, otherwise it will be a boolean.{{ join s []string sep string }}
Join arrays
with separatorsep
.
Default: []
usage
String, the usage documentation for a macro.
Default: ""
noColor
Boolean, disables colored log output.
Default: false
noPaging
Boolean, disables paging of log output using less
.
Default: false
cache
memoryMaxSizeMB
Number of megabytes the memory cache can use. When it exceeds this amount, it will start removing cache entries.
Default: 256
ttlSeconds
Number of seconds until a cache entry is expired and removed.
Default: 1800
(30 minutes)
type
String, type of cache provider. Current options are:
database
memory
none
None will disable all caching.
Default: memory
database
maxConnections
Number of max connections to the database to open.
Default: 25
maxIdleConnections
Number of idle connections to the database.
Default: 5
maxLifetimeMinutes
Number of minutes to keep a connection to the database open for.
Default: 5
uri
String, the database URI to connect with. Varies depending on database:
- PostgreSQL:
postgresql://username:password@hostname:port/database
Default: ""
http
listenAddress
String, the listen address and port number for the service.
Default: ":3000"
rateLimitKey
String, a HTTP header key that can be provided using x-rate-limit-key
to bypass rate limiting.
Default: ""
rateLimitPatterns
Map of paths and rate limits. Rate limits are configured as count-duration-status
, e.g. 5-1h
means 5 requests every 1 hour. Status is an HTTP status code, the rate limiter will apply if the response is greater than the status code, e.g. 5-1h-400
will apply if the response status code is > 400. If the rate limit is an empty string (""
), it will be disabled for that path.
Default: Run homechart config | homechart jq .http.rateLimitPatterns
tlsCertificateBase64
String, base64 encoded PEM certificate for HTTPS.
Default: ""
tlsCertificatePath
String, path to a PEM certificate for HTTPS.
Default: ""
tlsKeyBase64
String, base64 encoded PEM key for HTTPS.
Default: ""
tlsKeyPath
String, path to a PEM key for HTTPS.
Default: ""
xForwardedTrustedCIDRs
A list of subnets or CIDRs that will be trusted for sending X-Forwarded-For headers. If an IP address in the X-Forwarded-For header matches one of these subnets, the client IP will be the left most address before the matched IP. This should be the host or network of a trusted proxies like NGINX or Traefik.
Default: ""
jsonnet
Configuration toggles for disabling Jsonnet Native Functions. Some of these functions are disabled by default–namely anything that could perform an external call, like running a command, or performing HTTP or DNS requests. These should only be enabled for Jsonnet files you trust, as they could lead to data exfiltration or worse.
disableGetArch
Disable the getArch
function.
Default: false
disableGetCmd
Disable the getCmd
function.
Default: true
disableGetConfig
Disable the getConfig
function.
Default: false
disableGetEnv
Disable the getEnv
function.
Default: false
disableGetFile
Disable the getFile
function.
Default: false
disableGetFileHTTP
Disable the getFileHTTP
function.
Default: true
disableGetOS
Disable the getOS
function.
Default: false
disableGetPath
Disable the getPath
function.
Default: false
disableGetRecord
Disable the getRecord
function.
Default: true
oidc
OIDC is a map of OIDC issuer names to OIDC configurations. See Setup Homechart SSO for more information.
Default: {}
authURL
String, the endpoint for OAuth. Can be discovered from oidcIssuerURL
.
Default: ""
caCertificateBase64
String, the CA certificate used to communicate with the issuer. Useful with private OIDC servers without public certificates.
Default: ""
clientID
String, the ID shared with clients for OAuth requests. Required.
Default: ""
clientSecret
String, the secret shard with clients for OAuth requests. Required.
Default: ""
codeChallengeMethodsSupported
List of strings, the supported algorithms for OIDC code challenges. Can be discovered from oidcIssuerURL
.
Default: ""
displayName
String, the name that will be displayed in the UI for the OIDC issuer.
Default: ""
icon
String, a URL for an icon to display for the OIDC issuer. If this issuer has a name of google
or microsoft
, an icon will be provided by Homechart.
Default: ""
jwksKeys
List of strings, a list of public keys for an OIDC issuer. Can be discovered from oidcIssuerURL
.
Default: ""
jwksURI
String, a URL for retrieving JWKS keys for an OIDC issuer. Can be discovered from oidcIssuerURL
.
Default: ""
issuerURL
String, the issuer URL to be compared with the issuer
of the token. Can be discovered from oidcIssuerURL
.
Default: ""
oidcIssuerURL
String, URL to retrieve issuer configurations. Should be the base path without /.well-known/openid-configuration
, i.e. https://accounts.google.com
.
Default: ""
scopes
List of strings, a list of scopes to request. If empty, will be set to “openid” and “email”. Homechart requires sub
and email
claims in an ID token to successfully authenticate a user using OIDC.
Default: ""
tokenURL
String, the URL to retrieve tokens. Can be discovered from oidcIssuerURL
.
Default: ""
userInfoEndpoint
String, the URL to retrieve user info. Can be discovered from oidcIssuerURL
.
Default: ""
smtp
Homechart can use a SMTP server to send notifications to your household members.
fromAddress
String, email address to send from. Required to make SMTP work.
Default: ""
hostname
String, hostname to use when connecting to SMTP server.
Default: ""
password
String, password to use when connecting to SMTP server.
Default: ""
port
Number, port to use when connecting to SMTP server.
Default: 587
replyTo
String, email address to have users send to when replying.
Default: ""
username
String, username to use when connecting to SMTP server.
Default: ""
webPush
Homechart can use Web Push to send push notifications from Homechart to your devices. Homechart communicates directly to web push services provided by Apple, Google, Mozilla and other standards-compliant endpoints. Additionally, all of the data in the push notification is encrypted between your server and the client–the web push services can’t read it.
You need to generate the VAPID private and public keys to use Web Push. This can be done from the command line, e.g.:
$ ./homechart_linux_amd64 generate-vapid
{
"privateKey": "VEIYXV6qF_enUzycyQYdplDUgi05UM4lPh_FTzYmwX8",
"publicKey": "BNh2dabXjc2N8mctezlEm5pd1-1m_kkVZpdNYJl5gtRtdmKNIZvA6IZwYEYSy5UmVr5N7Bt9y9qKCLTp1sc_89c"
}
Or using a container:
$ docker run -it --rm ghcr.io/candiddev/homechart generate-vapid
{
"privateKey": "VEIYXV6qF_enUzycyQYdplDUgi05UM4lPh_FTzYmwX8",
"publicKey": "BNh2dabXjc2N8mctezlEm5pd1-1m_kkVZpdNYJl5gtRtdmKNIZvA6IZwYEYSy5UmVr5N7Bt9y9qKCLTp1sc_89c"
}
This command will output the private and public keys you’ll use in the configuration sections below.
vapidPrivateKey
String, the privateKey value from running generate-vapid
.
Default: ""
vapidPublicKey
String, the publicKey value from running generate-vapid
.
Default: ""