Calio/README.md
Elijah 6fc0a01c56
All checks were successful
Verify and publish Calio container / build-and-push (push) Successful in 1m4s
first commit
2026-10-20 19:04:12 -07:00

13 KiB

Calio

A single-user, self-hosted nutrition journal. PWA first, with a responsive desktop layout, light/dark/system themes, configurable accent colors, and no third-party analytics, fonts, or nutrition services. Dark mode uses neutral near-black and charcoal surfaces; choose a preset or custom accent under Settings → Look & feel, then save preferences. Accent preferences sync between devices and remain available offline.

Included

  • Daily calorie vessel with colliding physics bubbles, week navigation, meal journal, editable entries, fractional servings. New bubbles drop from the top as calories increase.
  • Saved foods and reusable plates. Logging a plate creates an atomic batch of independent food entries. Logs retain a nutrition snapshot when library foods change.
  • Independently enabled calorie, protein, carbohydrate, fat, fiber, sugar and sodium goals.
  • Weight journal in lb or kg; internally stored in kg. Multiple weigh-ins are retained, with the latest measurement per day used in charts.
  • 7 / 30 / 90 / 365 day nutrition and weight trends. Unlogged days are excluded from intake averages.
  • Markdown, CSV and JSON export with date range, nutrient and weight selections. Markdown is designed for LLM analysis. Data is downloaded locally, never submitted to an LLM. Save preferences to remember the export format, range preset and selections.
  • Password authentication, IndexedDB offline journal/outbox, a precached app shell, automatic foreground/reconnect sync, and explicit PWA update prompts.

Barcode lookup and nutrition-label OCR are deferred. This release uses manual nutrition entry and saved foods. It does not include Apple Watch integration, HealthKit, fasting, reminders or water tracking; those screenshot features were not part of the requested core.

Deploy on Unraid

Forgejo builds and publishes the image; Unraid runs it through Docker → Add Container. Compose is optional and is not required for deployment. Follow the Unraid setup guide, or import the Docker template.

Use repository git.elijahkuntz.com/elijah/calio:latest, container port 3000 (suggested host port 3080), and a persistent mapping from /mnt/user/appdata/calio to /data. Set APP_ORIGIN to the exact HTTPS origin, without a trailing slash, CALIO_USERNAME to your username, and CALIO_PASSWORD to a unique password of at least 12 characters. There is no registration screen or default password. The template runs as Unraid's 99:100; the mapped directory must be writable by that user. The image's standalone default is UID 1000.

Forward your HTTPS reverse proxy to http://<Unraid-IP>:3080, or to calio:3000 on a shared Docker network. All paths, including /api, must reach Calio. Open the public HTTPS address and sign in once while online. On iPhone, use Safari → Share → Add to Home Screen. On Android, use Chrome's Install app / Add to home screen. Desktop browsers work too.

The registry image becomes available after the source is pushed and the first publishing workflow succeeds. See the Forgejo setup below for the required registry secret.

HTTPS is required for installed-device service workers and secure authentication cookies. COOKIE_SECURE=false is accepted only when APP_ORIGIN uses localhost or 127.0.0.1; use it solely for local tests. Production defaults to Secure, HttpOnly, SameSite=Strict cookies.

For an optional local source trial, copy .env.example to .env, set a password, APP_ORIGIN=http://localhost:3000 and COOKIE_SECURE=false, then run docker compose up -d --build and visit http://localhost:3000. These local settings cannot be used to install from a phone over a LAN IP.

Credentials and secrets

The server supports CALIO_PASSWORD, CALIO_PASSWORD_FILE, CALIO_PASSWORD_HASH, or CALIO_PASSWORD_HASH_FILE. File variants accept Docker secrets. A hash avoids retaining a plaintext password in container configuration. Generate a salted scrypt hash by piping a password into npm run --silent password (stdin only). Do not put real passwords in shell history.

When using a hash, replace the CALIO_PASSWORD container variable with CALIO_PASSWORD_HASH. For a file, mount it read-only and set the appropriate _FILE variable to its container path. .env and runtime data are ignored by Git.

Sessions expire after 30 days and persist in SQLite. Changing credentials does not revoke existing sessions automatically. To invalidate all sessions, stop the app and delete the rows from the sessions table using a SQLite tool, then restart. The public login is rate limited to 10 requests per 15 minutes per connection IP; behind a proxy this conservatively shares the limit across clients. The app does not trust arbitrary forwarded-IP headers.

Persistent data, updates and backups

SQLite lives at /data/calio.sqlite, mapped to /mnt/user/appdata/calio on Unraid. Keep this directory and mapping when replacing the image. The optional Compose setup uses a named calio-data volume instead. Schema migrations are versioned and transactional; an older app refuses to open a newer schema.

Before updating, make a consistent backup while Calio is running:

docker exec calio node server/backup.js /data/backups/before-update.sqlite
docker cp calio:/data/backups/before-update.sqlite ./calio-backup.sqlite

Choose a new filename for each backup. VACUUM INTO captures a consistent SQLite snapshot, including committed writes in WAL; copying only the live main database file is not a safe backup. Keep a copy off the server. Nutrition exports are useful for analysis but are not full database backups (they omit library data, tombstones and sessions).

Use Unraid's Check for Updates → Update to pull the new latest image and recreate the container with its saved settings. Forgejo publishes images; it does not automatically update or restart Unraid. You can pin the repository field to a full commit SHA or a published v* version tag for repeatable deployment. The PWA will offer Update after loading online; accepting it changes app code without clearing IndexedDB. Pending local changes must sync before applying an update.

To restore a database backup: stop Calio, preserve the current data directory, replace calio.sqlite with the backup, and remove the old calio.sqlite-wal and calio.sqlite-shm sidecars while stopped. Preserve ownership for the configured container user (99:100 with the Unraid template; 1000:1000 by default), then restart. A server-only restore does not remove newer records already cached on devices: those may sync back. For a deliberate rollback, export pending device changes first, clear this site's device storage on each device, then sign in and fetch the restored journal. Do not clear device storage before saving unsynced entries.

Offline and conflict behavior

  • After the first authenticated sync, the complete journal, settings, food library and plates are held in IndexedDB. The complete current day can be reopened, edited, logged and exported offline.
  • An IndexedDB transaction saves each local mutation and its outbox entry together. A plate's entries are saved as one transaction. Requests acknowledge only the exact versions sent, so a local edit made during a sync remains queued.
  • Sync runs on app start, reconnect, return to the foreground, and once a minute while visible. It does not depend on iOS background sync support. If a server is unavailable, entries remain on-device and a retry status is shown.
  • Independent record additions merge. Edits to the same record use the latest device edit timestamp; exact ties use an ordinal payload comparison for the same result on all devices. Settings are one record, so the latest complete settings edit wins. Deletions are retained as tombstones so stale devices cannot resurrect records. Requests are retried idempotently.
  • Keep device clocks accurate. Edits over five minutes ahead of the server are rejected with a visible sync error; they remain on-device and can be exported. Once the server clock catches up they can sync. This avoids a bad device clock permanently outranking normal edits.
  • An expired session preserves the local journal and asks for sign-in to resume server sync. Explicit sign-out requires pending changes to sync, then removes this device's journal. The offline cache is accessible to someone with access to this unlocked browser/device; it is not an encrypted vault.
  • Browser storage can be cleared or evicted by the OS. Calio requests persistent storage, but the browser decides whether to grant it. Sync and backups remain the durable record. Check the sync status before clearing browser data or leaving a device.
  • Each sync currently exchanges the complete record set. This keeps the single-user implementation auditable and caches all history; very large multi-year journals may eventually benefit from incremental pagination.

Bubble motion

Tap Enable tilt beneath the calorie circle to allow device orientation. On iPhone, Safari asks for motion/orientation permission from that tap; the public site must use HTTPS. The app remembers the choice for the current page session and does not transmit sensor readings. Portrait, landscape and upside-down positions are mapped to the screen's gravity direction. Devices without sensors, or with permission denied, retain downward gravity and the Give a nudge control.

The circle uses a bounded Matter.js simulation: bubbles collide with each other and the circular wall, new calorie bubbles drop from the top, and removing calories removes the corresponding particles. Bubbles draw smaller than their collision boundaries, creating a small visible gap between them. A full hexagonal packing defines the 100% capacity; near a full vessel, the numeric readout moves below the circle so it does not hide dots. The particle count caps at the daily goal; over-goal calories still show the exact excess and a red ring. With the calorie goal disabled, the display uses a fixed 2,500 kcal visual scale. The animation sleeps when settled, pauses in hidden tabs, and honors the device's reduced-motion preference with a still arrangement. The graphic is an approximate visual; the numeric calorie total is authoritative.

Forgejo CI and container registry

.forgejo/workflows/build.yml runs on every branch/tag push, pull request and manual dispatch. It installs locked dependencies, runs tests and a production build, builds the Docker image, and runs scripts/container-smoke.js with both the image default user and Unraid's 99:100. The smoke test uses temporary containers/volumes, verifies auth and static assets, and recreates the container to verify journal/session persistence. Probes run inside the container, so socket-mounted runners do not depend on host port forwarding.

The workflow matches the existing Docker-capable unraid-runner label, ubuntu-latest, and uses the same secret name as the Study pipeline:

  • In Forgejo account Settings → Applications, create a token with write:package permission. In Calio Settings → Actions → Secrets, save it as FORGEJO_PAT. A secret configured only on Study is not automatically available to Calio. Keep the token out of source files and chat.
  • Optionally set repository variable REGISTRY_USERNAME if the token owner differs from the repository owner.
  • Ensure the registry is enabled at git.elijahkuntz.com and the runner can reach Docker Hub/GitHub actions and npm.
  • Every successful push publishes git.elijahkuntz.com/elijah/calio:<full-commit-SHA>.
  • Successful default-branch (main) builds also update :latest. Before promotion, the workflow checks the remote branch head to avoid promoting an already superseded build.
  • Valid v* tags also publish a version alias, such as :v0.1.0. Other branches and release tags do not overwrite :latest.
  • Pull requests verify without publishing or requiring registry credentials. Deleted refs are skipped. Manual dispatch uses the same publication rules as a push.
  • Each workflow run uses a unique local image tag, keeping concurrent builds separate. The workflow does not deploy to or restart your server.

The repository configuration is ready, but a successful live publish still requires FORGEJO_PAT and the initial source push. No token, registry publication or server deployment has been performed locally.

Develop and verify

Node 24+ is required for built-in SQLite. npm ci installs the lockfile. npm test covers authentication, validation, deterministic merges, tombstones, persistence, and client outbox handling.

For a production preview, run npm run build, configure the same environment variables above, then npm start. For live UI editing, run npm run dev:server on port 3000 and npm run dev on port 5173, with APP_ORIGIN=http://localhost:5173 and COOKIE_SECURE=false. Vite proxies /api; the service worker is registered only in production builds.

npm test
npm run build
docker build -t calio:local .
node scripts/container-smoke.js calio:local
node scripts/container-smoke.js calio:local --unraid

App code is in src/, shared schemas/merge rules in shared/, and the Express/SQLite server in server/. The handwritten service worker is generated from production asset hashes by scripts/build-sw.js. Icons are committed PNGs; scripts/generate-icons.ps1 regenerates them on Windows without external assets.