Docs Self-host1.0.0

Configuration reference

No variable is required. The server starts with none set and every setting has a safe default. An invalid value stops startup with a message naming the variable.

On this page

Variables marked preset seed a setting once, on the first start; after that Settings decides. Variables marked locks override the setting and make its field read-only in Settings while they are set.

A test reads the code and fails when a variable is read but missing here, or listed here but never read.

Server and network
Accounts and sign-in
Features
Outgoing email
Email to task
Calendar sync clients
Backups
Demo and host mode
The ot command

Server and network#

Variable	Default	Example	Explained in
`OPENTODO_ADDR`	`:8080`	`127.0.0.1:8080`	Docker
`OPENTODO_PORT`	unset	`7610`	Docker: in the container it moves the process; in Compose's `.env` it only changes the published port
`OPENTODO_DATA_DIR`	`./data` (binary), `/data` (image)	`/var/lib/opentodo`	Handbook
`OPENTODO_BASE_URL`	unset, inferred from requests	`https://todo.example.com`	Behind a reverse proxy
`OPENTODO_TRUSTED_PROXIES`	loopback and private networks	`cloudflare`	Behind a reverse proxy
`OPENTODO_LOG_LEVEL`	`info`	`debug`	Monitoring

OPENTODO_BIND in the .env next to docker-compose.yml is read by Compose, not by the server: it sets the host address the port is published on (default 0.0.0.0).

Variable	Default	Example	Explained in
`OPENTODO_SETUP_TOKEN`	unset	a secret of 16+ characters	The setup code
`OPENTODO_SETUP_CODE`	`off`	`required`	The setup code
`OPENTODO_ALLOW_SIGNUP`	`false`	`true`	Docker
`OPENTODO_SESSION_DAYS`	`90`	`30`	Account security
`OPENTODO_OIDC_ISSUER`	unset (locks)	`https://auth.example.com/application/o/opentodo/`	Single sign-on
`OPENTODO_OIDC_CLIENT_ID`	unset (locks)	`opentodo`	Single sign-on
`OPENTODO_OIDC_CLIENT_SECRET`	unset (locks)	the client secret	Single sign-on
`OPENTODO_OIDC_DISPLAY_NAME`	unset (locks)	`Authentik`	Single sign-on
`OPENTODO_OIDC_SSO_ONLY`	unset (locks)	`true`	Single sign-on

Features#

Variable	Default	Example	Explained in
`OPENTODO_PUSH`	`on`	`off`	Push notifications
`OPENTODO_MCP`	unset, off (preset)	`true`	AI assistants (MCP)
`OPENTODO_MCP_WRITES`	unset, off (preset)	`true`	AI assistants (MCP)
`OPENTODO_CALDAV`	unset, off (preset)	`true`	Calendar apps (CalDAV)
`OPENTODO_CALENDAR_FEEDS`	unset, off (preset)	`true`	Calendar feeds
`OPENTODO_AUTOMATIONS`	unset, on (locks)	`off`	Automations
`OPENTODO_WEBHOOKS_ALLOW_PRIVATE`	unset, off (preset)	`true`	Webhooks
`OPENTODO_IMPORT_MAX_MB`	`20`	`100` (1–200)	Import formats
`OPENTODO_ATTACHMENTS_MAX_FILE_MB`	`25` (preset)	`100` (1–2048)	Attachments
`OPENTODO_ATTACHMENTS_QUOTA_MB`	`1024` (preset)	`0` (unlimited)	Attachments
`OPENTODO_TRASH_RETENTION_DAYS`	`30`	`0` (never purge)	Trash retention
`OPENTODO_MAPS`	`on`	`off`	Maps
`OPENTODO_MAPS_TILES_URL`	`https://tiles.openfreemap.org/styles/liberty`	your own style URL	Maps
`OPENTODO_MAPS_GEOCODER_URL`	`https://photon.komoot.io`	`http://photon:2322`	Maps
`OPENTODO_STT_URL`	unset, off (locks)	`http://speaches:8000`	Speech to text
`OPENTODO_STT_MODEL`	unset (locks)	`Systran/faster-whisper-small`	Speech to text
`OPENTODO_STT_KEY_FILE`	unset (locks)	`/run/secrets/stt_key`	Speech to text

Outgoing email#

HOST and FROM go together. Each one set locks its field in Settings → Server → Outgoing email.

Variable	Default	Example	Explained in
`OPENTODO_SMTP_HOST`	unset, off	`smtp.example.com:587`	Outgoing email
`OPENTODO_SMTP_SECURITY`	from the port	`starttls`	Outgoing email
`OPENTODO_SMTP_USER`	unset	`[email protected]`	Outgoing email
`OPENTODO_SMTP_PASSWORD`	unset	the password	Outgoing email
`OPENTODO_SMTP_PASSWORD_FILE`	unset	`/run/secrets/smtp_password`	Outgoing email
`OPENTODO_SMTP_FROM`	unset	`OpenTodo <[email protected]>`	Outgoing email

Email to task#

The first four go together and turn it on; setting only some stops startup.

Variable	Default	Example	Explained in
`OPENTODO_EMAIL_ADDRESS`	unset, off	`[email protected]`	Email to task
`OPENTODO_EMAIL_IMAP_HOST`	unset	`imap.example.com:993`	Email to task
`OPENTODO_EMAIL_IMAP_USER`	unset	`[email protected]`	Email to task
`OPENTODO_EMAIL_IMAP_PASSWORD`	unset	the password	Email to task
`OPENTODO_EMAIL_IMAP_PASSWORD_FILE`	unset	`/run/secrets/imap_password`	Email to task
`OPENTODO_EMAIL_IMAP_MAILBOX`	`INBOX`	`Tasks`	Email to task
`OPENTODO_EMAIL_POLL_SECONDS`	`60`	`300` (at least 15)	Email to task
`OPENTODO_EMAIL_PROCESSED`	`move:OpenTodo/Processed`	`delete`	Email to task

Calendar sync clients#

The id and a secret go together; set, they lock the client in Settings → Integrations → Calendar sync.

Variable	Default	Example	Explained in
`OPENTODO_GOOGLE_CLIENT_ID`	unset	`1234-abc.apps.googleusercontent.com`	Calendar sync
`OPENTODO_GOOGLE_CLIENT_SECRET`	unset	the client secret	Calendar sync
`OPENTODO_GOOGLE_CLIENT_SECRET_FILE`	unset	`/run/secrets/google_secret`	Calendar sync
`OPENTODO_MICROSOFT_CLIENT_ID`	unset	the application (client) id	Calendar sync
`OPENTODO_MICROSOFT_CLIENT_SECRET`	unset	the client secret value	Calendar sync
`OPENTODO_MICROSOFT_CLIENT_SECRET_FILE`	unset	`/run/secrets/microsoft_secret`	Calendar sync
`OPENTODO_MICROSOFT_TENANT`	`common`	`organizations`	Calendar sync

Backups#

All are presets, applied once when no backup settings exist yet.

Variable	Default	Example	Explained in
`OPENTODO_BACKUP_DESTINATION`	unset	`local`, `s3` or `webdav`	Backups
`OPENTODO_BACKUP_LOCAL_DIR`	`<data>/backups`	`/backups`	Backups
`OPENTODO_BACKUP_SCHEDULE`	unset	`daily`	Backups
`OPENTODO_BACKUP_TIME`	unset	`03:00`	Backups
`OPENTODO_BACKUP_WEEKDAY`	unset	`sunday`	Backups
`OPENTODO_BACKUP_KEEP`	unset	`14`	Backups
`OPENTODO_BACKUP_MAX_AGE_DAYS`	unset	`90`	Backups
`OPENTODO_BACKUP_COMPRESS`	unset	`true`	Backups
`OPENTODO_BACKUP_PASSPHRASE`	unset	a long passphrase	Backups
`OPENTODO_BACKUP_PASSPHRASE_FILE`	unset	`/run/secrets/backup_passphrase`	Backups
`OPENTODO_BACKUP_S3_ENDPOINT`	unset	`https://s3.eu-central-1.amazonaws.com`	Backups
`OPENTODO_BACKUP_S3_REGION`	unset	`eu-central-1`	Backups
`OPENTODO_BACKUP_S3_BUCKET`	unset	`opentodo-backups`	Backups
`OPENTODO_BACKUP_S3_PREFIX`	unset	`home/`	Backups
`OPENTODO_BACKUP_S3_ACCESS_KEY`	unset	the access key id	Backups
`OPENTODO_BACKUP_S3_SECRET_KEY`	unset	the secret key	Backups
`OPENTODO_BACKUP_S3_PATH_STYLE`	unset	`true`	Backups
`OPENTODO_BACKUP_WEBDAV_URL`	unset	`https://cloud.example.com/remote.php/dav/files/me/backups/`	Backups
`OPENTODO_BACKUP_WEBDAV_USERNAME`	unset	`me`	Backups
`OPENTODO_BACKUP_WEBDAV_PASSWORD`	unset	an app password	Backups
`OPENTODO_BACKUP_WEBDAV_ALLOW_HTTP`	unset	`true`	Backups

Demo and host mode#

Neither is needed to self-host.

Variable	Default	Example	Explained in
`OPENTODO_DEMO`	unset, off	`true`	Public demo instance
`OPENTODO_DEMO_MAX_SANDBOXES`	`500`	`100`	Public demo instance
`OPENTODO_DEMO_MAX_DB_MB`	`1024`	`512`	Public demo instance
`OPENTODO_HOST_URL`	unset, off	`https://example.cloud`	Host mode
`OPENTODO_HOST_TOKEN`	unset	a secret of 32+ characters	Host mode
`OPENTODO_HOST_OPERATOR_ADDR`	`127.0.0.1:8081`	`10.0.0.5:8081`	Host mode
`OPENTODO_HOST_IDLE_MINUTES`	`10`	`30`	Host mode
`OPENTODO_HOST_MAX_OPEN`	`500`	`1000`	Host mode
`OPENTODO_HOST_LIMITS`	unset	`db_mb=500,ops_per_hour=5000,members=10`	Host mode

The ot command#

Read by the ot client, not the server.

Variable	Default	Example	Explained in
`OPENTODO_URL`	the profile's server	`https://todo.example.com`	Command-line client
`OPENTODO_TOKEN`	the profile's token	`ot_…`	Command-line client
`OPENTODO_PROFILE`	`default`	`work`	Command-line client
`OPENTODO_CONFIG`	the user config directory	`/path/to/config.json`	Command-line client
`OPENTODO_WORKSPACE`	the default workspace	`Work`	Command-line client
`OPENTODO_READ_ONLY`	unset	`1`	Command-line client

Edit this page on GitHub