Running OpenTodo on Portainer
OpenTodo is one container with one volume and no required settings. Its Portainer app template fills in the image, the port, the volume and the restart policy.
On this page
Install#
In Portainer, open Settings → App Templates, paste this URL into URL and save:
https://raw.githubusercontent.com/pixari/opentodo/main/deploy/portainer/portainer-template.jsonThis replaces the list of templates Portainer shows. Note the previous URL if you want to switch back later.
Open your environment, go to App Templates and pick OpenTodo.
Check the settings below and click Deploy the container.
OpenTodo is not yet in the community list Lissy93/portainer-templates; once it is, people who load that list find it there as well.
Without templates, the same container is:
docker run -d --name opentodo --restart unless-stopped \
-p 8080:8080 -v opentodo-data:/data ghcr.io/pixari/opentodo:stableFirst visit#
Open http://<your-host>:8080 right after deploying. The first visitor creates the owner account; if you set a setup token, the setup screen asks for it. After that, sign-up is closed and the owner invites people.
Settings#
| Setting | Default | What it does |
|---|---|---|
| Setup token | empty | Optional, 16+ characters (for example from openssl rand -hex 16). Set it when others can reach the server, so a stranger cannot create the owner account first. |
| Public https address | empty | OPENTODO_BASE_URL. Leave it 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. |
| Open sign-up | Closed | Open lets anyone who can reach the server create an account. |
| Trusted proxies | empty | Reverse proxies whose X-Forwarded-For is trusted, or cloudflare. Set it only when every request comes through them. |
The port (8080) can be changed on the host side under Advanced options. Other OPENTODO_* variables from the configuration table can be added there as environment variables.
https and reverse proxies#
On http://<your-host>: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, Caddy, Traefik) or use Tailscale's https, then set the public https address. Do not set an https:// address while you open OpenTodo over plain http: the session cookie becomes secure-only and sign-in fails. More in Running with Docker.
Updates and backups#
The template uses the stable image, which every release moves. To update, open the container, click Recreate and turn on Re-pull image. The volume is kept and migrations run on start. There are no down-migrations, so back up first. To stay on one release line, recreate the container with the image ghcr.io/pixari/opentodo:0.6 (or one version, 0.6.1).
Everything OpenTodo stores (the database, attachments and its own backups) is in the volume Portainer created for /data; find it in the container's Volumes section. Back it up from the host, or turn on scheduled backups in OpenTodo's Settings → Server (written to backups/ in the same volume, or to S3 or WebDAV). See Backups.
Troubleshooting#
- Sign-in does not stick: the public https address is set but you open OpenTodo over plain http. Clear it and recreate the container.
- The container stops right after it starts: its log names the setting, for example a setup token shorter than 16 characters.