{"slug": "show-hn-self-hosted-coffee-app-for-tracking-espresso-shots-with-ai-assistance", "title": "Show HN: Self-hosted coffee app for tracking espresso shots, with AI assistance", "summary": "Developer michidk released Roastbook, a self-hosted coffee journal app that uses AI to extract bean details from bag photos and research roasters, machines, and brew recommendations. The app runs on the user's own PostgreSQL and storage behind their own auth proxy, and its AI features require setting an OPENAI_API_KEY while everything else works without one. Roastbook deploys via Docker Compose for a home server or a Helm chart for a cluster, with a read-only demo running on bundled sample data.", "body_md": "**The AI-native coffee journal you actually own.**\n\n  Photograph the bag. Log the brew. Keep every gram of data on your own\n  infrastructure.\n\n[**Live demo**](https://roastbook.vercel.app/)\n   · \n  [Quick start](#-quick-start)\n   · \n  [Documentation](#-documentation)\n   · \n  [Design system](/michidk/roastbook/blob/main/DESIGN.md)\n\nTip\n\n**Try it in ten seconds.** The\n[read-only demo](https://roastbook.vercel.app/) runs entirely from bundled\nsample data — no account, no database, nothing to install.\n\nRoastbook is a self-hosted home for your brews, beans, recipes, café visits, roasters, brewing methods, and gear — and it fills itself in for you.\n\n- 📷 **Photograph a bag** and Roastbook reads the label: origin, region, farm,\nvariety, process, roast level, roast date, tasting notes.\n- 🔎 **Type a roaster's name** and it researches the website, location, and\nbackground.\n- ⚙️ **Add an espresso machine** and it looks up documented capabilities and\nfactory defaults from exact-model manuals and manufacturer sources.\n\nEvery accepted value keeps its source, and factory facts stay separate from your current setup.\n\nLogging coffee should take seconds, not minutes. Log a brew with dose, yield, and time and you are done; the depth is there when you want it, not in your face when you don't. Roastbook runs equally well on the phone in your hand at the machine and on the desktop where you dig through the numbers afterwards.\n\n- 🎚️ **Simple first, deep when you ask.** Each brewing method shows only the\nfields that apply to it, so an espresso form is not a pour-over form. A quick\nentry takes three numbers.\n- 🔬 **Serious when you want to be.** Pre-infusion time and pressure, brew\npressure, flow rate, brew temperature, grind setting, tamp force, basket,\npuck screen, and paper filter position per brew — plus typed capabilities for\neach equipment type and revisioned espresso-machine settings that preserve\nold brew context.\n- 📈 **Numbers that answer questions.** A year-long coffee activity calendar and\nfilterable statistics connect brew quality to beans, methods, taste,\nconsistency, timing, gear, and cost, while parameter charts show what a change\nto grind, dose, or pressure actually did.\n- 📱 **Mobile and desktop, both first-class.** Large touch targets and compact\ncards next to the machine; full data tables, charts, and maps at the desk,\nplus a`⌘`` K` command palette for jumping anywhere without\nthe mouse.\n- 🤖 **AI-native, not AI-bolted-on.** Research and extraction are wired into the\nforms you already use and return typed, validated fields you confirm before\nanything is saved.\n- 🔒 **Yours, end to end.** Self-hosted on your own PostgreSQL and your own\nstorage, behind your own auth proxy. No accounts, no telemetry, no upsell.\n- 📓 **A journal, not just a log.** Beans, roasters, gear, recipe templates,\nbrewing methods, and café visits keep every brew's full story structured.\n- 🚀 **Deploys in one command.** Docker Compose for a home server, a Helm chart\nfor a cluster.\n\nNote\n\nSet `OPENAI_API_KEY` and these turn on. Everything else works without it.\n\n- **Label scanning** — extract full bean details from a photo of the bag.\n- **Bean research** — fill in origin, process, roast level, and tasting notes\nfrom the roaster's own sources.\n- **Roaster research** — resolve official website, Instagram, location, and a\nfactual profile.\n- **Machine research** — pull sourced capabilities and factory espresso settings\nfor your specific model, with strict rules against weak evidence, pump-rating\nguesses, or values from similar machines.\n- **Brew recommendations** — compare a new-brew draft or one specific logged\nbrew with up to 50 brews for the same bean, method, and exact gear setup, then\nget a confidence-rated opinion that recognizes when recent brews are already\ngood, or proposes one explained adjustment or controlled experiment.\n- **Request debugging** — review lifetime token usage and estimated token cost,\nthen inspect every raw AI input, response event, error, and unparsed output\nfrom Settings.\n\nEvery AI call is optional, server-side only, rate-limited, schema-validated, and recorded in PostgreSQL for local debugging. Image logs retain metadata such as MIME type and byte count, not the image payload itself.\n\nImportant\n\n**On the roadmap: an MCP server**, so your own agents can read and write your\ncoffee log directly — ask what your last ten Gesha brews had in common, or\nhave an assistant log this morning's espresso for you.\n\n## **The complete feature list**\n\n- Log brews with dose, yield, time, equipment, overall and sensory ratings, and flavor notes.\n- Load a recipe as editable template values, create recipes from scratch, duplicate variants, or reuse a brew's values in a new or existing recipe. Brews keep their own snapshot and are never linked back to the template.\n- A recipe can set a target brew time, which the brew timer then counts against.\n\n- Tailor the taste profile in settings: switch the overall rating, each sensory factor, flavor tags, and tasting notes on or off. Disabled inputs disappear from rating forms and from every place they were shown.\n- Or pick the simple taste profile, which replaces the individual factors with one sour-to-bitter scale — sour points at under-extraction and bitter at over-extraction, the usual first dial-in move.\n\n- Catalog beans, roasters, brewing methods, coffee shops, and typed gear details, and group equipment into reusable gear sets that fill new brew and recipe equipment fields in one tap.\n- Track café visits and explore visited locations on a map.\n- Configure drink and milk types in Settings, assign drink types to brewing methods to keep new-brew choices relevant, then record the finished drink and its applicable milk choice on both brews and café visits.\n- Keep a Places list of saved cafés, from favorites to a want-to-visit wishlist.\n\n- Review filterable brew and café trends, quality, consistency, taste, rhythm, exploration, recipe performance, gear usage, and costs.\n- Scan labels and research beans, roasters, and sourced machine properties with AI, with local request logs and token-cost estimates.\n\n- Search beans, cafés, and gear directly; jump to any page; start a new brew,\nbean, or visit; and switch theme from the command palette (`⌘`` K` or`Ctrl`` K` ).\n\n- Store media locally or in S3-compatible object storage.\n- Gate self-hosted deployments with the Hodor reverse proxy.\n- Explore a database-free, read-only demo backed by ephemeral PGlite seed data.\n\nA modern, boring-where-it-counts TypeScript stack with full-stack type safety from the database row to the rendered field:\n\n| Layer | Choice | \n|---|---|\n| Runtime and package manager | Bun 1.3.14 | \n| Full-stack framework | TanStack Start with server functions | \n| Routing | TanStack Router, file-based and fully typed | \n| UI | React 19, shadcn/ui, Radix and Base UI, Tailwind CSS v4 | \n| Icons and maps | Lucide, MapLibre GL | \n| Database | PostgreSQL when self-hosted; ephemeral PGlite for the demo | \n| Media storage | Local filesystem or any S3-compatible bucket | \n| AI | TanStack AI with any OpenAI-compatible endpoint | \n| Validation | Zod at every boundary, including environment variables | \n| Tooling | Vite, Biome, Knip, `bun test` | \n| Deployment | Docker Compose or Helm, fronted by the Hodor auth proxy | \n\nServer-only concerns — database access, storage providers, AI calls, and secrets — never cross into browser code, and configuration is validated lazily on first use, reporting the affected variable names.\n\nDocker Compose starts PostgreSQL, applies committed migrations, starts Roastbook, and exposes it through Hodor.\n\n```\ncp .env.example .env\n# Replace HODOR_PASSWORD and HODOR_SECRET in .env.\n# Generate a signing secret with: openssl rand -hex 32\ndocker compose up --build\n```\n\nOpen [http://localhost:3000](http://localhost:3000) after the database migration completes.\n\nRoastbook uses Bun 1.3.14. With PostgreSQL available at the `DATABASE_URL` from\n`.env`:\n\n```\nbun install --frozen-lockfile\ncp .env.example .env\nbun run dev\n```\n\nThe unauthenticated development server listens on [http://localhost:3000](http://localhost:3000).\nIt applies pending migrations before accepting requests, repeats the check on\nVite configuration reloads, and watches for newly generated migrations while\nrunning.\n\n## **All available commands**\n\n| Command | Purpose | \n|---|---|\n| `bun run dev` | Apply migrations and start the watched development server | \n| `bun run check` | Check source formatting, lint, and Markdown | \n| `bun run typecheck` | Run TypeScript without emitting files | \n| `bun run test` | Run tests; report unavailable integrations as skipped | \n| `bun run test:integration` | Require PostgreSQL and S3 integration tests | \n| `bun run lint:deadcode` | Find unused code and dependencies with Knip | \n| `bun run build` | Build production assets | \n| `bun run build:demo` | Build the database-free Vercel demo | \n| `bun run verify` | Run the complete local quality gate | \n| `bun run db:generate` | Generate a Drizzle migration after a schema change | \n| `bun run db:migrate` | Apply committed migrations | \n| `bun run db:studio` | Open Drizzle Studio | \n| `bun run db:seed` | Seed the same fictional dataset as the public demo | \n| `bun run storage:orphans` | Report media drift without changing data | \n\n| Guide | What is inside | \n|---|---|\n| [Development and testing](/michidk/roastbook/blob/main/docs/development.md) | Workflow, tests, tooling | \n| [Configuration reference](/michidk/roastbook/blob/main/docs/configuration.md) | Every environment variable | \n| [Read-only demo mode](/michidk/roastbook/blob/main/docs/demo-mode.md) | How the PGlite demo is built | \n| [Deployment](/michidk/roastbook/blob/main/docs/deployment.md) | Docker, Helm, security boundary | \n| [Design system](/michidk/roastbook/blob/main/DESIGN.md) | Layout contract and UI conventions | \n| [Helm chart reference](/michidk/roastbook/blob/main/charts/README.md) | Chart values and defaults | \n\n```\nsrc/routes/          TanStack Router file routes and server endpoints\nsrc/components/      Shared application and domain UI\nsrc/components/ui/   shadcn/ui primitives\nsrc/lib/server/      Server-side domain operations\nsrc/lib/storage/     Local and S3-compatible storage providers\nsrc/db/              Drizzle schema and database connection\ndrizzle/             Committed migrations and metadata\ncharts/              Helm chart\n```\n\nWarning\n\n`src/routeTree.gen.ts` is generated. Run `bun run generate-routes` instead of\nediting it manually.\n\n  Open-source software for people who care about coffee. ☕\n\n[Try the demo](https://roastbook.vercel.app/) ·\n  [Star it on GitHub](https://github.com/michidk/roastbook)", "url": "https://wpnews.pro/news/show-hn-self-hosted-coffee-app-for-tracking-espresso-shots-with-ai-assistance", "canonical_source": "https://github.com/michidk/roastbook", "published_at": "2026-09-14 13:06:05+00:00", "updated_at": "2026-09-14 13:19:54.129861+00:00", "lang": "en", "topics": ["ai-products", "ai-tools", "developer-tools"], "entities": ["Roastbook", "michidk", "PostgreSQL", "Docker Compose", "Helm", "OPENAI_API_KEY", "OpenAI"], "alternates": {"html": "https://wpnews.pro/news/show-hn-self-hosted-coffee-app-for-tracking-espresso-shots-with-ai-assistance", "markdown": "https://wpnews.pro/news/show-hn-self-hosted-coffee-app-for-tracking-espresso-shots-with-ai-assistance.md", "text": "https://wpnews.pro/news/show-hn-self-hosted-coffee-app-for-tracking-espresso-shots-with-ai-assistance.txt", "jsonld": "https://wpnews.pro/news/show-hn-self-hosted-coffee-app-for-tracking-espresso-shots-with-ai-assistance.jsonld"}}