Config

Reference documentation for Homechart’s configuration
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

List of strings, email addresses which will have admin access to Homechart for their account.

Default: []

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

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. Setting this to 0 disables Calendar Event cleanup.

Default: 180

keepCookMealPlanDays

Number, number of days to retain Cook Meal Plans after their scheduled date. Setting this to 0 disables Cook Meal Plan cleanup.

Default: 180

keepDeletedDays

Number, number of days to keep deleted data (Notes, Cook Recipes, Secret Values). Setting this to 0 disables deleted data cleanup.

Default: 30

keepHealthLogDays

Number, number of days to retain Health Logs. Setting this to 0 disables Health Log cleanup.

Default: 180

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"

rollupBudgetMonthCategoriesMonths

Number, number of months before a Budget Category month detail is rolled up into the next Budget Category month. Setting to 0 disables category roll ups. Not rolling up categories may impact performance.

Default: 96

rollupBudgetTransactionsBalanceMonths

Number, number of months before a Budget Transaction is rolled up into a starting balance. Setting to 0 disables balance roll ups. Not rolling up transactions may impact performance.

Default: 96

rollupBudgetTransactionsSummaryMonths

Number, number of months before a Budget Transaction is rolled up into monthly summaries. Setting to 0 disables summary roll ups. Not rolling up transactions may impact performance.

Default: 48

sseTimeoutMinutes

Number, time that SSE requests will be removed due to inactivity, in minutes.

Default: 10

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

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

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: ""

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 position i or return fallback f.
  • {{ getEnv e string f string }}
    Get an environment variable e or return fallback f.
  • {{ getFlag f string }}
    Get the flag values for f. 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 array s with separator sep.

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: ""