Self-hostingVersion 0.9.0

Running OpenTodo on TrueNAS

OpenTodo is one container with one data folder and no required settings. It runs on TrueNAS Community Edition 24.10 and later, which run apps with Docker.

On this page

OpenTodo is not in the TrueNAS Apps catalogue yet: the app has been prepared for TrueNAS's community train but not accepted. Until it is, install it with Install via YAML as below.

Install with Install via YAML#

Create a dataset for the data, for example tank/apps/opentodo (Datasets → Add Dataset, preset Apps). Under Edit Permissions, make the user and group apps (568) its owner, with write access.
Open Apps → Discover Apps, click the ⋮ menu next to Custom App and choose Install via YAML.

Name the app opentodo, paste the following, change the path to your dataset, and click Save:

services:
  opentodo:
    image: ghcr.io/pixari/opentodo:0.9.0
    user: "568:568"
    restart: unless-stopped
    ports:
      - "30530:8080"
    environment:
      OPENTODO_BASE_URL: ""
      OPENTODO_SETUP_TOKEN: ""
    volumes:
      - /mnt/tank/apps/opentodo:/data

Open http://<your-truenas-address>:30530. The first visitor creates the owner account; after that, the owner invites people (sign-up is closed).

The image has a health check of its own (it has no shell, so it runs /opentodo healthcheck), and TrueNAS shows the app as healthy once it answers.

Install from the Apps catalogue#

Once OpenTodo is listed: Apps → Discover Apps, search for OpenTodo, click Install, check the settings below and click Install. TrueNAS creates the data dataset (ixVolume) and sets its owner for you, and the Web UI button opens the app.

Setting	Default	What it does
Base URL	empty	Leave empty when you open OpenTodo by the server's address. Behind a reverse proxy, set the https address people open, for example `https://todo.example.com`.
Setup Token	empty	Optional, 16+ characters. Set it when the server is reachable from the internet, so a stranger cannot create the owner account first.
Allow Sign-up	off	On lets anyone who can reach the server create an account.
Trusted Proxies	empty	The reverse proxies whose `X-Forwarded-For` is trusted, or `cloudflare`. Set it only when every request comes through them.
Additional Environment Variables	none	Any other `OPENTODO_*` variable from the configuration table.
User ID / Group ID	568 / 568	The user OpenTodo runs as and that owns its files (`apps`).
WebUI Port	30530	The port on your server. OpenTodo listens on it directly.
Data Storage	ixVolume	Where the database, attachments and backups live, mounted on `/data`. Choose Host Path to use a dataset of your own.

Permissions#

The image runs as user 65532 by default, but the binary runs as any user that can write /data; both setups above run it as apps (568). If the app stops right after it starts and its log mentions the database ("unable to open database file", "readonly database" or "permission denied"), the dataset is not writable for that user: give apps ownership of it under Datasets → Edit Permissions (or, from the shell, chown -R 568:568 /mnt/tank/apps/opentodo).

https and reverse proxies#

On the server's address (http://192.168.1.10:30530) tasks, projects, sync, sharing and attachments work. Installing the app on a phone, working offline, push notifications, passkeys and end-to-end encryption need https, because browsers only allow them there. Put OpenTodo behind a reverse proxy with a certificate (Nginx Proxy Manager or Caddy from the Apps catalogue, Traefik) or use Tailscale's https, then set Base URL (OPENTODO_BASE_URL) to that https address. Keep it empty on plain http: an https Base URL opened over plain http breaks signing in. If the proxy sits behind Cloudflare's proxy, set Trusted Proxies to cloudflare. More on proxies in Running with Docker.

Updates and backups#

The app names one release (0.9.0), never a moving tag. With Install via YAML, change the tag in the app's YAML (Edit) to the new release and save; TrueNAS pulls it and restarts the app. From the catalogue, TrueNAS shows Update on the app when the catalogue has a new version (its maintainers bump it after each OpenTodo release). Migrations run on start and there are no down-migrations, so back up first.

Everything OpenTodo stores is in its dataset (or ixVolume). Protect it with periodic snapshots and replication or a Cloud Sync task, or turn on scheduled backups in Settings → Server (written to backups/ in the same folder, or to S3 or WebDAV). See Backups.

Edit this page on GitHub