Calio/docs/UNRAID.md
Elijah 80fc48b9f1
All checks were successful
Verify and publish Calio container / build-and-push (push) Successful in 1m2s
Add barcode and nutrition label scanning
Barcode scanning
- Scan barcode in the food sheet reads UPC-A/E and EAN-13/8 live from
  the camera with ZXing WebAssembly (bundled, precached, CSP allows
  wasm), with photo and typed-digit fallbacks
- Lookups check saved foods first (offline), then local copies of USDA
  FoodData Central Branded Foods and Open Food Facts, then the live
  Open Food Facts API; API answers and misses are cached
- Server imports refresh in a low-priority child process: USDA when a
  new archive is published, Open Food Facts weekly by streaming its CSV
  export; each import builds a new table and swaps it in atomically
- Every available nutrient is kept: foods and entries gain optional
  barcode (GTIN-14) and extra nutrients, shown under More nutrients and
  included in JSON exports
- Settings shows the size, date and any error for each product copy

Label scanning
- Scan label sends a downscaled photo to the server, read with
  PaddleOCR PP-OCRv5 (server detection, English recognition) on ONNX
  Runtime CPU, about 1.3 s median
- Parser handles US/Canadian, linear, Spanish and EU per-100 g panels,
  tilted photos, OCR misspellings and %DV cross-checks
- Models are pinned and checksum-verified at image build time

Container
- Runtime moves to Debian slim for ONNX Runtime's glibc build; other
  platforms' binaries are pruned
- Smoke tests now read a fixture label inside the container
- README and Unraid docs cover disk use, network access and refresh

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 13:41:44 -07:00

74 lines
7.9 KiB
Markdown

# 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.
1. In your Forgejo account's **Settings → Applications**, generate a token with `write:package` permission.
2. 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.
3. 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.
4. 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](../unraid/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:
```sh
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.
If you use Nginx Proxy Manager, leave **Cache Assets** off for this host. It caches every `.js` file for hours regardless of the app's `no-cache` headers, which delays app updates. Calio already caches its own versioned assets on devices. (Current builds also load the service worker from the extension-less `/sw`, so such a cache cannot block updates, but a stale cache still wastes a day on older clients.)
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 and the OCR models.
The same directory also holds `products.sqlite`, the barcode database (about 1.6 GB, briefly up to about 3.5 GB while a refresh is built, plus a 450 MB USDA download in `tmp/` about twice a year). Keep appdata on a share with room for that. The file is a cache and needs no backup. The container needs outbound HTTPS to `fdc.nal.usda.gov`, `static.openfoodfacts.org` (redirects to Amazon S3) and `world.openfoodfacts.org`.
Before updating, create a consistent backup from the Unraid terminal:
```sh
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](../README.md#persistent-data-updates-and-backups) 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. Devices then update themselves: the app checks for a new version each time it returns to the foreground, downloads it in the background, and switches over at a moment that cannot interrupt you (while it is in the background, or just after you open it). It waits while edits are unsynced or a sheet is open. An **Update** prompt is also shown for switching immediately.
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](https://docs.unraid.net/unraid-os/using-unraid-to/run-docker-containers/managing-and-customizing-containers/), [Forgejo container registry](https://forgejo.org/docs/v11.0/user/packages/container/), and [Study's reference pipeline](https://git.elijahkuntz.com/Elijah/Study/src/branch/main/.forgejo/workflows).