Running OpenTodo on Unraid
OpenTodo is one container with one appdata folder and no required settings. The template (opentodo.xml in OpenTodo's template repository) fills in everything.
On this page
Install#
OpenTodo is listed in Community Applications. Open the Apps tab, search for OpenTodo, click Install, check the settings below and click Apply.
Without the Apps tab (Community Applications not installed), add the template by hand. In Unraid's terminal (>_ in the top bar):
wget -O /boot/config/plugins/dockerMan/templates-user/my-OpenTodo.xml \
https://raw.githubusercontent.com/pixari/opentodo-unraid/main/templates/opentodo.xmlThen open Docker → Add Container, choose OpenTodo under User templates and continue as above.
Open the WebUI from the container's menu. The first visitor creates the owner account; after that, the owner invites people (sign-up is closed).
Settings#
| Setting | Default | What it does |
|---|---|---|
| Web UI port | 8080 |
The port on your server. Change the left side only if 8080 is taken. |
| Data | /mnt/user/appdata/opentodo |
The database, attachments and backups. Everything OpenTodo stores is here. |
| 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. |
Under Show more settings: open sign-up, trusted proxies, push notifications, session length, trash retention, the largest import and the log level. Every other OPENTODO_* variable from the configuration table can be added with Add another Path, Port, Variable….
Permissions#
The image runs as user 65532 and has no shell, so it does not use PUID, PGID or UMASK; adding them changes nothing. Unraid's appdata share is writable by everyone by default, which is all it needs. If the container stops right after it starts and its log mentions the database ("unable to open database file", "readonly database" or "permission denied"), the folder is not writable for it. Either give the folder to that user:
chown -R 65532:65532 /mnt/user/appdata/opentodoor run the container as Unraid's usual nobody:users: add --user 99:100 under Extra Parameters (advanced view) and run chown -R 99:100 /mnt/user/appdata/opentodo.
https and reverse proxies#
On the server's address (http://192.168.1.10:8080) 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, SWAG, Caddy, Traefik) or use Tailscale Serve on the Unraid server, then set Base URL to that https address. If the proxy sits behind Cloudflare's proxy, set Trusted proxies to cloudflare. More on proxies in Running with Docker.
Tailscale#
Leave the container's Use Tailscale switch off. Unraid adds Tailscale to a container by running a shell script inside it that installs packages and downloads Tailscale at every start; the OpenTodo image has no shell and no package manager (it is built that way to stay small and hard to attack), so with the switch on the container does not start and its log shows exec /opt/unraid/tailscale: no such file or directory.
Use Tailscale on the Unraid server itself instead. It gives OpenTodo an https address on your tailnet, with a certificate, without changing the container:
Install and sign in to Tailscale on Unraid (see Unraid's Tailscale guide). In the Tailscale admin console, under DNS, turn on MagicDNS and HTTPS Certificates.
In Unraid's terminal (>_ in the top bar), publish the container's Web UI port (here
8080; use the left side of your Web UI port setting) on the tailnet over https:tailscale serve --bg --https=8443 http://localhost:8080The command prints the address, for example
https://tower.example-tailnet.ts.net:8443. It stays on after a restart;tailscale serve --https=8443 offremoves it. Port8443keeps Unraid's own web interface free; any free port works.Set Base URL to that address (
https://tower.example-tailnet.ts.net:8443) and apply.
Open OpenTodo at that address from every device on your tailnet. Installing the app, push notifications, passkeys and end-to-end encryption then work. With Base URL set, open OpenTodo only at that address: from newer releases on, a page opened at another address (the server's LAN address, say) cannot sign in.
Updates and backups#
The template uses the stable image, which every release moves: Check for Updates in the Docker tab shows each new release, Update installs it, and migrations run on start. There are no down-migrations, so back up the appdata folder first (see below). To stay on one release line and take only its fixes, change Repository to ghcr.io/pixari/opentodo:0.6 (or pin one version, 0.6.1) in the container's settings.
Back up /mnt/user/appdata/opentodo with the Appdata Backup plugin, or turn on scheduled backups in Settings → Server (they are written to backups/ in the same folder, or to S3 or WebDAV). See Backups.
Troubleshooting#
- The app says Offline and nothing you add is saved on a plain-http address: OpenTodo 0.6.0 and earlier needed https for this. Update the container.
- The Web UI link opens the wrong port: Unraid builds it from the Web UI port; check the left side of that setting.
- The container does not start and its log says
exec /opt/unraid/tailscale: no such file or directory: the container's Use Tailscale switch is on. Turn it off and use Tailscale on the Unraid server instead.