NutriTrace

Trace Every Bite

A self-hosted personal nutrition tracker.
No accounts, no telemetry, no cloud sync unless you opt in.

Jump to: What it is · Features · Install · Env vars · Docs

iOS fund: the Trace apps have no iOS app yet, because building one needs a Mac and an iPhone. See the goal or chip in. Self-hosting stays free either way.

---

What NutriTrace is

NutriTrace runs as a single Docker container on your own hardware, with a PWA for the browser and a native Android app for your phone. No accounts on external services, no data leaving your network, no subscriptions.

Principles

• Self-hosting is and will remain free. The server, PWA, and source code will never be paywalled.
• No trackers, no analytics, no telemetry. NutriTrace doesn't phone home; your usage is invisible to anyone but you.
• Your data stays on your hardware. No central server, no cloud sync that can read it; nothing leaves your network unless you opt into a third-party integration (OFF, USDA, Fitbit, etc.).
• Open source under AGPL-3.0. Every line that touches your data is readable.

Features

• Diary + meal logging. Configurable meal slots, per-meal ⋮ menu, Split Recipe, IF tracker widget. Full guide.
• Foods, meals, recipes. Personal database, source filter chips, OFF + USDA quality signals (v1.0.3), Scan Label AI OCR. Full guide.
• Goals + Adaptive TDEE. Fixed/Dynamic/Adaptive modes, 7,700 kcal/kg regression math. Full guide.
• Wellness integrations (4). Fitbit (via Google Health), Withings, Garmin, Health Connect, plus Trace-computed Sleep/Readiness/Resilience scores. Full guide.
• Activity + Intermittent Fasting. Manual workouts + IF widget with presets and streaks. Full guide.
• Open Food Facts. Cloud + local Parquet mirror for air-gap. Full guide.
• USDA + Mealie. Free API key USDA lookups + Mealie recipe import. Full guide.
• Trace AI. Reads your diary, meals, wellness, fasting streaks, and Adaptive TDEE state; can log a food, propose one from a photo (you confirm), or add an activity entry, all conversationally. 16 tools total. Smart Log voice/text, propose_food photo flow. Full guide.
• Federation API. /api/v1/* scoped Bearer tokens for CT + LT + external clients. Full guide.
• Model Context Protocol (MCP). Expose your diary, goals, and foods to external AI agents (Claude Desktop, Cursor, Codex) via the standard MCP Streamable HTTP transport. Off by default; opt in with MCP_ENABLED=1. Read-only in Phase 1. Full guide.
• Migrations. MyFitnessPal (with nomad64 scraper), Lose It, Cronometer, Waistline. Full guide.
• Multi-user + OIDC SSO. Authentik/Keycloak/Pocket ID/Authelia/Google/Auth0. Full guide.
• Native Android app. Offline mode or server-sync, WorkManager native reminders. Full guide.

Apps

• Web (PWA). Runs in any modern browser; add to home screen for full-screen use.
• Android. Native Capacitor build; works standalone or connected to your NutriTrace server. Signed APK on the Releases page.
• iOS. Not currently available (requires Mac + Apple Developer account; see Support).

Install

Published to two registries with identical tag sets: ghcr.io/traceapps/nutritrace (primary) and traceapps/nutritrace on Docker Hub (mirror). The snippet below uses GHCR; swap in traceapps/nutritrace:latest if that suits your setup.

Minimum viable docker-compose.yml:

services:
  nutritrace:
    image: ghcr.io/traceapps/nutritrace:latest
    container_name: nutritrace
    ports:
      - "3001:3001"
    volumes:
      - ./data/db:/data/db
      - ./data/uploads:/data/uploads
    environment:
      - DB_PATH=/data/db/nutritrace.db
      - UPLOADS_PATH=/data/uploads
      - JWT_SECRET=change-me-to-a-long-random-string
      # OIDC_ISSUER=https://auth.example.com  # optional single-provider SSO
    restart: unless-stopped

Generate a JWT secret:

openssl rand -base64 48

Start it:

docker compose up -d

Open http://localhost:3001 and the first-run wizard will walk you through user management and creating your admin account. Skipping user management runs the app in single-user mode.

Full compose recipes with SMTP, Docker secrets (*_FILE), reverse-proxy examples, and multi-provider OIDC at docs/getting-started/compose/. Tag policy (:latest, :1, :1.0, :1.0.0, :dev, legacy :1.0.0-rc.N) in DEPLOY.md.

Pre-release testers can grab the rolling dev-latest APK; occasional milestone builds also get numbered -devNN pre-releases. See DEPLOY.md for details.

Env vars

Full list (Docker secrets *_FILE variants, air-gap OFF_LOCAL_ONLY, per-provider AI knobs, all OIDC_* options) at docs/self-hosting/env-vars/. SMTP and AI can also be set in the Settings UI; env vars take priority and lock those fields.

Request logging

API request logs include a client/server correlation ID, method, path, response status, duration, outcome, and observed wire-body bytes. Uploaded images and frontend assets are not request-logged. Content-Length is reported separately as an untrusted declared_bytes value and is never substituted for bytes actually observed. Oversized JSON requests return HTTP 413 with request_id, observed size_bytes (or null), declared_bytes, and limit_bytes fields.

LOG_LEVEL=trace enables fine-grained internal trace calls, but request content remains off unless TRACE_REQUEST_BODIES=1 is also set. Minimal byte counting happens before body-size enforcement; body inspection happens only after parsing and access checks. Selected request bodies, including sync pushes, use bounded traversal with credential and setting-value redaction, URL sanitization, inline data: URL summaries, and the TRACE_BODY_MAX_BYTES output cap. Query strings are omitted. Bodies can still contain private diary and health data; enable body tracing only temporarily and do not publish the resulting logs without reviewing them.

The app sends X-Request-ID to the server and records the same ID in verbose client diagnostics. The server returns the ID on responses, so a failing app request can be matched directly to its server log. Invalid logging configuration fails at startup instead of silently falling back.

Data persistence

Two host directories bind-mount:

• Database (DB_PATH). SQLite file.
• Uploads (UPLOADS_PATH). Food/meal photos and server-side backups (uploads/backups/).

Nothing else needs to persist; the container is stateless beyond these two volumes.

Updating

docker compose pull
docker compose up -d

The database schema migrates automatically on startup.

Tech stack

Trace family

Part of the TraceApps family. Sister apps: CookTrace for recipes and pantry, LiftTrace for weightlifting. Full docs for all three at traceapps.github.io/docs.

Translations

NutriTrace is translated with Weblate, a free web platform for libre translation projects. No coding required — pick your language, translate the strings, submit. Missing keys fall back to English at runtime, so partial translations are safe to release.

Start translating at hosted.weblate.org/projects/nutritrace/. See CONTRIBUTING.md for domain-specific guidance (regulatory nutrition terms, proper nouns, tone).

Roadmap, changelog, contributing, license

• See ROADMAP.md for what's next.
• CHANGELOG.md tracks per-release changes.
• Contributions welcome; see CONTRIBUTING.md for coding conventions, translation workflow, and the volunteer thread.
• Licensed under AGPL-3.0, entire codebase including the Android app source.

Support

NutriTrace is free to self-host and always will be. No paid tier, nothing behind a donation, no telemetry. It's built and maintained by one person.

The current goal is iOS. None of the Trace apps run properly on an iPhone, because building and testing for iOS needs Apple hardware, plus the developer accounts for both app stores. That comes to about $1,300, and the itemised breakdown is on the Support page.

Helping doesn't have to cost anything: starring the repo, reporting bugs with detail, and translating all count, and stars are how self-hosted projects get found.

Credits

NutriTrace was inspired by two self-hosted nutrition trackers:

• Waistline by David Healey. A privacy-focused Android nutrition diary that proved a great open-source nutrition tracker is possible.
• SparkyFitness by CodeWithCJ. A self-hosted fitness and nutrition tracker that influenced the wellness integrations and goal-tracking approach.

Disclaimer

NutriTrace is not medical, health, or nutrition-professional software. It does not provide medical advice, diagnosis, treatment, or personalized nutrition prescriptions. Food entries, calorie and macro tracking, Trace AI suggestions, Smart Log parsing, Scan Label output, Goal Insights, Adaptive TDEE recommendations, wellness scores, and any analytical output are for informational and self-tracking purposes only.

Nutrition decisions can interact with medical conditions (diabetes, eating disorders, food allergies, pregnancy, breastfeeding, pediatric needs, kidney or liver disease, metabolic disorders) in ways this app cannot assess. Consult a qualified healthcare professional, registered dietitian, or licensed nutritionist before starting a new eating plan, calorie target, or making significant dietary changes.

Trace AI answers can be incorrect or incomplete; treat them as a starting point, not a substitute for human judgment or professional advice. Food nutrition data from Open Food Facts is community-curated and may contain inaccuracies. Use at your own risk.