Environment variables

Set them in deploy/production.env. The full list, with defaults, is in deploy/production.env.example and .env.example.

Variable

Default

Purpose

ALLOWED_HOSTS

(none: required)

Host names HouseCairn answers to, comma-separated.

CSRF_TRUSTED_ORIGINS

(none)

https:// origins of those host names.

HOUSECAIRN_BEHIND_TLS_PROXY

false

true behind a reverse proxy that sets X-Forwarded-Proto.

HOUSECAIRN_FORWARDED_ALLOW_IPS

127.0.0.1,::1

Addresses or networks of that proxy, comma-separated: only their forwarding headers count (see Reverse proxy).

SECRET_KEY

generated in /data/secret_key

Set it only to manage the key yourself.

DATABASE_URL

SQLite in /data

For example postgres://housecairn:<password>@postgres:5432/housecairn.

TIME_ZONE

UTC

Time zone of the instance.

HOUSECAIRN_SIGNUP_OPEN

false

Allow local sign-up from the web page; needs email. See Open sign-up.

HOUSECAIRN_SIGNUP_POW_BITS

16

Work of the anti-robot check of sign-up, from 8 to 24 bits.

HOUSECAIRN_SIGNUP_ALLOWED_DOMAINS, HOUSECAIRN_SIGNUP_BLOCKED_DOMAINS

(none)

Comma-separated domains that may, or may not, sign up.

ACCOUNT_EMAIL_VERIFICATION

optional, mandatory with open sign-up

Whether an address must be verified before sign-in.

HOUSECAIRN_CACHE_URL

locmemcache://housecairn

Cache of the rate-limit counters; dbcache://housecairn_cache shares them between web processes. See Rate limits.

OIDC_SERVER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET

(none)

Single sign-on through any OpenID Connect provider.

HOUSECAIRN_OIDC_SIGNUP, HOUSECAIRN_BOOTSTRAP_ADMIN_EMAIL

closed, (none)

Who may get an account through single sign-on.

EMAIL_HOST

(none)

Outgoing mail server (SMTP); email is off while it is empty. See Email.

EMAIL_USE_SSL, EMAIL_TIMEOUT

false, 15

TLS from the first byte; seconds to wait for the server. See Email.

HOUSECAIRN_SITE_URL

(none: set it in production)

Public address of the instance, such as https://home.example.com, used for links in emails. Empty: the address of the request, checked against ALLOWED_HOSTS; check --deploy warns when EMAIL_HOST is set without it.

HOUSECAIRN_INVITATION_LIFETIME_DAYS

7

Days an invitation link stays valid, from 1 to 90.

HOUSECAIRN_DOCS_URL

https://docs.housecairn.app

Address of this documentation, used by the help link of each screen.

HOUSECAIRN_WEB_WORKERS

2

Web server processes.

HOUSECAIRN_TASK_WORKERS

2

Task worker processes.

HOUSECAIRN_STOP_TIMEOUT

20

Seconds given to both to stop; keep it below Compose’s stop_grace_period.

HOUSECAIRN_PORT

8000

Port inside the container.

LOG_LEVEL

INFO

Application log level; logs go to the container output.

Set inside the image, not to be changed: HOUSECAIRN_DATA_DIR=/data, STATIC_ROOT=/app/static, DJANGO_SETTINGS_MODULE=housecairn.settings.

Email

HouseCairn sends email for invitations, address verification, password reset and security alerts. Set EMAIL_HOST to your SMTP server to turn it on, with EMAIL_PORT (587), EMAIL_HOST_USER, EMAIL_HOST_PASSWORD, EMAIL_USE_TLS (true), EMAIL_USE_SSL, EMAIL_TIMEOUT and DEFAULT_FROM_EMAIL. All of it is on the Email page, with what becomes of the features that need a mailbox when there is none.

Links in emails point to HOUSECAIRN_SITE_URL when it is set. Set it in production. Without it, a link takes the host of the request that triggered it: ALLOWED_HOSTS limits that to the names the instance answers to, but a proxy that lets a request choose its host, or several names in ALLOWED_HOSTS, can make a link point where you did not intend. manage.py check --deploy reports EMAIL_HOST set without HOUSECAIRN_SITE_URL.

PostgreSQL

SQLite is the default and is enough for a household. To use PostgreSQL, the example compose.yaml has a postgres service, started only with the postgres profile:

  1. cp deploy/postgres.env.example deploy/postgres.env and set a password.

  2. In deploy/production.env, set DATABASE_URL=postgres://housecairn:<password>@postgres:5432/housecairn.

  3. Uncomment depends_on in the housecairn service, then docker compose --profile postgres up -d.

An existing PostgreSQL server works too: set DATABASE_URL to it.

Edit this page on GitHub Report a problem with this page