Config

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_config_key=a value or HOMECHART_config_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. Underscores in config keys are used to represent nesting, i.e. cli_logLevel represents:

{
  "cli": {
    "logLevel": "debug"
  }
}

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. If combined with adminTrustedCIDRs,

Default: []

app_adminTrustedCIDRs (recommended)

List of IPv4 and IPv6 networks. If adminEmailAddresses is not specified, any account from these networks will be granted admin access to Homechart. If adminEmailAddresses is specified, it will limit the admin access granted for adminEmailAddresses to traffic originating from the networks specified.

Should be combined with xForwardedTrustedCIDRs to ensure the appropriate remote IP is being checked, otherwise this may grant admin access to anyone on the internet.

Default:

[
  "10.0.0.0/8",
  "127.0.0.1/32",
  "172.16.0.0/12",
  "192.168.0.0/16",
  "::1/128",
  "fd00::/8",
]

app_baseURL (recommended)

String, base URL for Homechart, mostly used by notifications.

Default: "https://web.homechart.app"

app_cacheTTLMinutes

Number, number of minutes to keep entries in cache.

Default: 15

app_disableSignup (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 initial account.

Default: false

app_disableTasks

Boolean, disable any background tasks (sending notifications, cleaning up old data) from running on this instance.

Default: false

app_disableWebConfig

Boolean, disables configuration via Web/HTTP.

Default: false

app_keepCalendarEventDays

Number, number of days to retain Calendar Events after their end date. Setting this to 0 disables Calendar Event cleanup.

Default: 180

app_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

app_keepDeletedDays

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

Default: 30

app_keepHealthLogDays

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

Default: 180

app_keepNotesPageVersions

Number, number of Notes Page Versions to keep.

Default: 10

app_keepPlanTasksDays

Number, number of days to keep completed tasks.

Default: 90

app_motd

String, informational message to display on the UI for all users.

Default: ""

app_port

Number, listening port for Homechart. Setup port forwarding to this port to expose Homechart externally.

Default: 3000

app_proxyAddress

String, Upstream IPv4 or IPv6 address of a trusted proxy. See the Single Sign-On (SSO) guide for usage details.

Default: ""

app_proxyHeaderEmail

String, proxy header that should be associated with an account email address. See Single Sign-On (SSO) guide for usage details.

Default: ""

app_proxyHeaderName

String, proxy header that should be associated with an account name. See Single Sign-On (SSO) guide for usage details.

Default: ""

app_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

app_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

app_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

app_sseTimeoutMinutes

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

Default: 10

app_sessionExpirationDefaultSeconds

Number, time between non-Remember Me sessions expiring, in seconds.

Default: 3600

app_sessionExpirationRememberSeconds

Number, time between Remember Me sessions expiring, in seconds.

Default: 7776000

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

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

cli_configReloadSec

Number of seconds to periodically reload the config and reload the application, if > 0.

Default: 0

cli_configWatch

Boolean, if true then the configPath will be watched for changes. On a change, the application will be reloaded.

Default: false

cli_logFormat

String, log format to use for logging: human, kv, or raw.

Default: "human"

cli_logLevel

String, log level to use for logging: none, debug, info, or error.

Default: "info"

cli_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: {}

cli_macros_[macro]_argumentsRequired

A list of arguments that are required for the macro.

Default: []

cli_macros_[macro]_argumentsOptional

A list of arguments that are optional for the macro.

Default: []

cli_macros_[macro]_flags

A map of flags for the macro.

Default: {}

cli_macros_[macro]_flags_[flag]_default

A list of strings for the default value of the flag.

Default: []

cli_macros_[name]_flags_[flag]_options

A list of strings the flag can be set to.

Default: []

cli_macros_[name]_flags_[flag]_placeholder

String, the placeholder name for the flag if it accepts a value.

Default: ""

cli_macros_[name]_flags_[flag]_usage

String, the usage instructions for the flag.

Default: ""

cli_macros_[name]_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: []

cli_macros_[name]_usage

String, the usage documentation for a macro.

Default: ""

cli_noColor

Boolean, disables colored log output.

Default: false

cli_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

cache_ttlSeconds

Number of seconds until a cache entry is expired and removed.

Default: 1800 (30 minutes)

cache_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

database_maxIdleConnections

Number of idle connections to the database.

Default: 5

database_maxLifetimeMinutes

Number of minutes to keep a connection to the database open for.

Default: 5

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

http_rateLimitKey

String, a HTTP header key that can be provided using x-rate-limit-key to bypass rate limiting.

Default: ""

http_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

http_tlsCertificateBase64

String, base64 encoded PEM certificate for HTTPS.

Default: ""

http_tlsCertificatePath

String, path to a PEM certificate for HTTPS.

Default: ""

http_tlsKeyBase64

String, base64 encoded PEM key for HTTPS.

Default: ""

http_tlsKeyPath

String, path to a PEM key for HTTPS.

Default: ""

http_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.

jsonnet_disableGetArch

Disable the getArch function.

Default: false

jsonnet_disableGetCmd

Disable the getCmd function.

Default: true

jsonnet_disableGetConfig

Disable the getConfig function.

Default: false

jsonnet_disableGetEnv

Disable the getEnv function.

Default: false

jsonnet_disableGetFile

Disable the getFile function.

Default: false

jsonnet_disableGetFileHTTP

Disable the getFileHTTP function.

Default: true

jsonnet_disableGetOS

Disable the getOS function.

Default: false

jsonnet_disableGetPath

Disable the getPath function.

Default: false

jsonnet_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: {}

oidc_[issuer_name]_authURL

String, the endpoint for OAuth. Can be discovered from oidcIssuerURL.

Default: ""

oidc_[issuer_name]_caCertificateBase64

String, the CA certificate used to communicate with the issuer. Useful with private OIDC servers without public certificates.

Default: ""

oidc_[issuer_name]_clientID

String, the ID shared with clients for OAuth requests. Required.

Default: ""

oidc_[issuer_name]_clientSecret

String, the secret shard with clients for OAuth requests. Required.

Default: ""

oidc_[issuer_name]_codeChallengeMethodsSupported

List of strings, the supported algorithms for OIDC code challenges. Can be discovered from oidcIssuerURL.

Default: ""

oidc_[issuer_name]_displayName

String, the name that will be displayed in the UI for the OIDC issuer.

Default: ""

oidc_[issuer_name]_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: ""

oidc_[issuer_name]_jwksKeys

List of strings, a list of public keys for an OIDC issuer. Can be discovered from oidcIssuerURL.

Default: ""

oidc_[issuer_name]_jwksURI

String, a URL for retrieving JWKS keys for an OIDC issuer. Can be discovered from oidcIssuerURL.

Default: ""

oidc_[issuer_name]_issuerURL

String, the issuer URL to be compared with the issuer of the token. Can be discovered from oidcIssuerURL.

Default: ""

oidc_[issuer_name]_oidcIssuerURL

String, URL to retrieve issuer configurations. Should be the base path without /.well-known/openid-configuration, i.e. https://accounts.google.com.

Default: ""

oidc_[issuer_name]_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: ""

oidc_[issuer_name]_tokenURL

String, the URL to retrieve tokens. Can be discovered from oidcIssuerURL.

Default: ""

oidc_[issuer_name]_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.

smtp_fromAddress

String, email address to send from. Required to make SMTP work.

Default: ""

smtp_hostname

String, hostname to use when connecting to SMTP server.

Default: ""

smtp_password

String, password to use when connecting to SMTP server.

Default: ""

smtp_port

Number, port to use when connecting to SMTP server.

Default: 587

smtp_replyTo

String, email address to have users send to when replying.

Default: ""

smtp_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.

webPush_vapidPrivateKey

String, the privateKey value from running generate-vapid.

Default: ""

webPush_vapidPublicKey

String, the publicKey value from running generate-vapid.

Default: ""