6.8 KiB
Calio on Unraid
Forgejo builds the image. Install and update it with Unraid's standard Docker interface; Docker Compose is not required.
Publish the first image
The existing unraid-runner uses the required ubuntu-latest label. Its job environment needs Docker CLI/daemon access, as in the Study build pipeline. Calio installs Node 24 during the job.
- In your Forgejo account's Settings → Applications, generate a token with
write:packagepermission. - In the Calio repository, open Settings → Actions → Secrets and add
FORGEJO_PAT. This matches Study's secret name. A Study-only secret must also be added to Calio, or supplied at an organization scope that includes Calio. - Push the Calio source. Check the repository's Actions page for the completed workflow. Tests, the application build, and both container smoke tests must pass before publishing.
- The first successful main build publishes
git.elijahkuntz.com/elijah/calio:latest. Ensure the resulting package is public if Unraid should pull without registry credentials. If using a private package, authenticate Unraid's Docker daemon to the registry with a separate package-read token.
The token's account defaults to the repository owner, Elijah. Set repository variable REGISTRY_USERNAME only if using another account that has permission to publish to this owner. Tokens are used at runtime and never baked into the image.
All branch and tag pushes are built. Successful pushes publish a full commit SHA tag, main also promotes latest, and valid v* tags add a version alias. PRs only verify. Publishing does not restart the running app.
Add the container
Use Docker → Add Container and fill in the following values. Alternatively, copy calio.xml to /boot/config/plugins/dockerMan/templates-user/my-calio.xml on Unraid and select the Calio user template.
| Field | Value |
|---|---|
| Name | calio |
| Repository | git.elijahkuntz.com/elijah/calio:latest |
| Network | bridge, or your reverse proxy's shared Docker network |
| Container port | 3000/TCP |
| Host port | 3080 (choose another unused port if necessary) |
| Container path | /data (read/write) |
| Host path | /mnt/user/appdata/calio |
Variable APP_ORIGIN |
Your exact public HTTPS origin, e.g. https://calio.example.com, without a trailing slash |
Variable CALIO_USERNAME |
Your single sign-in username |
Variable CALIO_PASSWORD |
A unique password of at least 12 characters |
Variable COOKIE_SECURE |
true |
Variable TZ |
America/Phoenix, or your timezone |
| Extra Parameters (Advanced View) | --user=99:100 --cap-drop=ALL --security-opt=no-new-privileges |
| WebUI (Advanced View) | The same public HTTPS origin as APP_ORIGIN |
Keep Privileged off. The template uses Unraid's nobody:users identity (99:100). Create the dedicated appdata directory and give that identity ownership before starting. For a new installation using exactly the default path, run in the Unraid terminal:
mkdir -p /mnt/user/appdata/calio
chown 99:100 /mnt/user/appdata/calio
chmod 770 /mnt/user/appdata/calio
These commands affect only Calio's directory. If you choose another path, use that path instead. Calio does not implement PUID/PGID environment variables: Docker's --user selects the identity. If migrating existing data, ensure its database and sidecar files are also writable by the chosen identity while Calio is stopped. The standalone image otherwise defaults to UID 1000.
Configure your HTTPS reverse proxy to forward all paths to http://<Unraid-IP>:3080, or http://calio:3000 on a shared Docker network. Leave /api intact. Open the public HTTPS address for sign-in and PWA installation. The upstream HTTP port alone does not provide the secure cookies or service worker origin needed by a phone PWA.
On iPhone, use Safari → Share → Add to Home Screen. On Android, use Chrome → Install app / Add to home screen. Sign in online once and allow the initial sync to finish before testing offline use.
Update without losing data
Keep /mnt/user/appdata/calio mapped to /data on every recreation. It holds the SQLite database, persistent sessions and backups; the image holds only application code.
Before updating, create a consistent backup from the Unraid terminal:
docker exec calio node server/backup.js /data/backups/before-update.sqlite
docker cp calio:/data/backups/before-update.sqlite ./calio-backup.sqlite
Use a new backup filename each time and copy it off the server. Do not copy only the live calio.sqlite file while Calio is writing: committed data can still be in its WAL sidecar. See the README for restoration and device-cache considerations.
After a successful main build, select Check for Updates → Update on Unraid's Docker page. Unraid pulls latest and recreates the container with the saved port, path and variable settings. The PWA offers its own Update prompt after reconnecting; queued offline edits must sync before accepting it.
For a specific build, replace :latest in the repository field with its full commit SHA or published version tag. Database schema checks prevent an older app from opening a newer unsupported schema; a rollback across schema changes may need the matching database backup.
References: Unraid container management, Forgejo container registry, and Study's reference pipeline.