Configuration

Day Planner is configured with environment variables. Set them in .env next to the Docker Compose file, or in your platform’s settings. If a required variable is missing or invalid, every page shows Configuration needed instead of the app.

Variables marked secret must never be shared or committed. Day Planner never logs them or shows their values.

Required

DATABASE_URL

The Postgres database. The Docker Compose file builds it from POSTGRES_PASSWORD.

Type: PostgreSQL connection URL
Required: Always
Secret: yes
Example: DATABASE_URL=postgresql://dayplanner:password@db:5432/day_planner

POSTGRES_PASSWORD

Password for the bundled Postgres container. Any long random string.

Type: string
Required: With the Docker Compose file
Secret: yes

BETTER_AUTH_SECRET

Signs sessions, cookies and the setup cookie. Generate with openssl rand -base64 32. Use the same value on every container of one instance; changing it signs everyone out.

Type: string, 32+ characters
Required: Always (from version 1.0)
Secret: yes

BETTER_AUTH_URL

The public URL people open, without a path. Used for redirects, links in emails and the trusted-origin list.

Type: http(s) URL
Required: Always
Example: BETTER_AUTH_URL=https://tasks.example.com

First admin

ADMIN_EMAIL

With ADMIN_PASSWORD or ADMIN_PASSWORD_FILE, creates this admin at first start and skips the setup page. Ignored once any admin exists.

Type: email
Required: No

ADMIN_PASSWORD

Password for the first admin. Set only one of this and ADMIN_PASSWORD_FILE.

Type: string, 8–128 characters
Required: With ADMIN_EMAIL, unless ADMIN_PASSWORD_FILE is set
Secret: yes

ADMIN_PASSWORD_FILE

Reads the first admin’s password from a file, such as a Docker secret. One trailing newline is removed. The container won’t start if the file is missing or empty.

Type: file path
Required: No
Example: ADMIN_PASSWORD_FILE=/run/secrets/admin_password

SETUP_TOKEN

The token /setup asks for, instead of a generated one printed to the logs. Only used while no admin exists.

Type: string, 16+ characters
Required: No
Secret: yes

Network

PORT

Port the server listens on. In the Docker Compose file, the host port to publish.

Type: port number
Required: No
Default: 8303

TRUSTED_ORIGINS

Extra origins allowed to sign in, besides BETTER_AUTH_URL, such as a LAN address. Each needs its scheme.

Type: comma-separated URLs
Required: No
Example: TRUSTED_ORIGINS=http://192.168.1.20:8303

CLIENT_IP_HEADER

Where the visitor’s IP comes from, for rate limits. Use cf-connecting-ip behind Cloudflare only if the server can’t be reached except through Cloudflare.

Type: x-forwarded-for | cf-connecting-ip | x-real-ip
Required: No
Default: x-forwarded-for

TRUSTED_PROXIES

Your reverse proxies. With x-forwarded-for, the chain is read right to left past these addresses to find the visitor.

Type: comma-separated IPs or CIDR ranges
Required: No
Example: TRUSTED_PROXIES=172.16.0.0/12

Scaling

RATE_LIMIT_STORAGE

Where sign-in rate-limit counters live. memory suits one container. Use database with two or more, or each container counts on its own.

Type: memory | database
Required: No
Default: memory

RUN_MIGRATIONS_ON_START

Run database migrations when the container starts. With two or more containers, set false and run migrations once per deploy instead.

Type: true | false
Required: No
Default: true

OIDC_DISCOVERY_URL

The provider’s OpenID Connect discovery document. Set all three OIDC_ URL and client settings, or none.

Type: URL
Required: For external login
Example: OIDC_DISCOVERY_URL=https://id.example.com/.well-known/openid-configuration

OIDC_CLIENT_ID

Client ID from the provider.

Type: string
Required: For external login

OIDC_CLIENT_SECRET

Client secret from the provider.

Type: string
Required: For external login
Secret: yes

OIDC_PROVIDER_ID

Short id used in the callback URL. Register {BETTER_AUTH_URL}/api/auth/callback/{OIDC_PROVIDER_ID} with the provider.

Type: string
Required: No
Default: clerk
Example: OIDC_PROVIDER_ID=oidc

OIDC_PROVIDER_NAME

Shown on the button: “Sign in with {name}”.

Type: string
Required: No
Default: Clerk
Example: OIDC_PROVIDER_NAME=Example ID

Email

SMTP_URL

Sends password-reset and invitation emails. Without it or RESEND_API_KEY, reset asks people to contact the admin and invite links are shown to copy.

Type: SMTP URL
Required: No
Secret: yes
Example: SMTP_URL=smtps://user:password@smtp.example.com:465

RESEND_API_KEY

Sends password-reset and invitation emails through the Resend HTTP API. Takes precedence over SMTP_URL when both are set. Needs SMTP_FROM on your verified domain.

Type: API key
Required: No
Secret: yes
Example: RESEND_API_KEY=re_…

SMTP_FROM

Sender of those emails.

Type: email address, optionally with a name
Required: No
Default: Day Planner <no-reply@localhost>
Example: SMTP_FROM=Day Planner <tasks@example.com>

Other

DOCS_URL

Where the app’s help links point, for self-hosters keeping their own copy of the docs.

Type: URL
Required: No
Default: the public docs site

DAY_PLANNER_VERSION

Docker Compose file only: which published image version to run.

Type: image tag
Required: No
Default: latest
Example: DAY_PLANNER_VERSION=1.0.0

Legacy

These are being removed and don’t apply to new installs.

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

Removed: the app no longer reads Clerk settings.

Type: string
Required: No

CLERK_SECRET_KEY