Cellarion Wine Registry

Cellarion

Cellarion is a hosted wine cellar app — a ready-to-use online service at cellarion.app. Create a free account and start tracking your bottles, organizing them into cellars and racks, searching a shared wine registry, getting sommelier-curated drink-window recommendations, and chatting with an AI sommelier about your collection. No installation, no server, no setup — just sign up and go. Every feature is free, forever.

Just want to use Cellarion? Go to cellarion.app and sign up. You do not need to clone this repository, run Docker, or host anything yourself. There's also a public demo account (Try the demo on the landing page) and an Android app on Google Play.

Cellarion is also open-source (AGPL-3.0), so if you'd prefer to run your own private instance, you can self-host it. The rest of this README covers self-hosting — see Quick Start. Most people should just use the hosted service at cellarion.app.

Hosted Service (recommended)

Cellarion is live and publicly available at:

👉 https://cellarion.app

This is the primary way to use Cellarion. Create an account and start using the full service today — every feature is free, forever. No credit card, no trial clock, no paywalled features, nothing to install or maintain. If you want to chip in, optional Supporter, Patron and Benefactor tiers (monthly or yearly) and GitHub Sponsors fund development — they unlock nothing extra, just our thanks.

Features

Your cellar

• Bottle tracking — Log every bottle with vintage, producer, region, price, rating, and tasting notes; add more of a bottle you already own in one click
• Cellar & rack management — Multiple cellars with customizable rack grids (up to 20×20) and a 3D cellar room view for physical placement
• Open-bottle tracking — Open a bottle, pour glasses over days, close or finish it — with preservation-aware drink-soon nudges
• Reserved bottles — Mark bottles as "spoken for" (a birthday, a dinner) so suggestions and consume flows respect them
• Drink-window alerts — Sommelier-curated maturity windows per wine and vintage; alerts when bottles approach peak, are in window, or slipping past it
• Rich statistics — Charts, world choropleth map, breakdowns by country, grape, value, and drink status
• Import & export — Bring collections from Vivino (incl. drinking history), CellarTracker, generic CSV, or Cellarion's own JSON; export everything as JSON or a ZIP with your images

The shared registry

• Smart search — Meilisearch-powered fuzzy search with aggressive deduplication and canonical-key matching
• Label scanning — Snap a photo of a wine label and let AI fill in the details
• Regional grape names — One canonical variety per grape, displayed the way the label writes it (a Douro Port shows Tinta Roriz, an Alentejo red Aragonez — both stored as Tempranillo)
• Registry quality tooling — Duplicate/fragmentation queues, cross-field domain checks, name checks, and a sommelier correction-proposal workflow keep the shared data clean

AI

• AI cellar chat — Ask questions about your collection — food pairings, occasion picks, cellar health (Claude + Voyage embeddings + Qdrant; only ever answers from wines you actually own)
• Connect your own AI — A built-in MCP server lets Claude, and any MCP-capable client, read and manage your cellar conversationally
• Bring your own models — Self-hosters can point every AI feature at any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio) instead of Anthropic/Voyage

Community & sharing

• Cellar sharing — Invite others to browse or co-manage a cellar with role-based access
• Wine lists, reviews & discussions — Build shareable lists, review wines, discuss them, follow other users, and get restock alerts
• Tasting journal & wishlist — Keep private notes and a want-to-try list

Platform

• Climate monitoring — Connect cellar temperature/humidity sensors (Home Assistant-friendly ingest API) with per-cellar dashboards
• Sign in with Google — Optional Google SSO alongside email/password
• Installable app — PWA with push notifications, plus an Android app on Google Play
• Internationalization — Community-translated via Weblate (help translate)
• Privacy & GDPR — Full data export, account deletion with cooling-off, one-click email opt-out, optional self-hosted cookie-free analytics (Umami)
• Everything free — Optional Supporter/Patron/Benefactor tiers (Stripe, monthly or yearly) and GitHub Sponsors fund development; they unlock nothing extra
• Sommelier & admin tools — Maturity/pricing curation surfaces, wine requests, quality reports, registry health watchdog, audit log, super-admin dashboard

Stack

• MongoDB 7 — Database (Mongoose 8)
• Express 4 — Backend API
• React 19 — Frontend (React Router 6, built with Vite 7)
• Node.js 24 — Runtime
• Meilisearch — Fuzzy search engine
• Qdrant — Vector database for AI cellar chat
• Voyage AI — Wine embedding generation (swappable for any OpenAI-compatible endpoint)
• Anthropic Claude — Label scanning + AI chat (swappable, same mechanism)
• MCP — Model Context Protocol server (/api/mcp) with OAuth, for AI assistants
• Stripe — Optional supporter payments (hosted Checkout + Portal)
• nginx — Serves the React SPA and proxies /api/ to the backend (internal)
• Traefik — External reverse proxy (bring your own; not included in this Compose file)
• Docker Compose — Containerization
• rembg — Python/Flask background removal microservice
• Umami — Optional self-hosted, cookie-free analytics (compose --profile analytics)

Self-Hosting (Quick Start)

This section is only for people who want to run their own private instance. If you just want to use Cellarion, head to cellarion.app instead — no setup required.

Prerequisites

• Docker + Docker Compose

Run the app

The app is routed through Traefik, so create the external web Docker network before the first up (compose declares it external — the first command fails otherwise):

git clone https://github.com/jagduvi1/Cellarion.git
cd Cellarion
cp .env.example .env
# Edit .env and set JWT_SECRET and MEILI_MASTER_KEY to strong random strings
docker network create web        # once; skip if it already exists
docker-compose up --build

Seed demo data

After the containers are running:

docker exec cellarion-backend node src/seed-demo.js

This creates demo accounts plus a starter taxonomy, wine registry entries, and a demo cellar with sample bottles:

These are local development credentials. Change them before deploying anywhere public.

Stop

docker-compose down          # keep data
docker-compose down -v       # also remove all volumes (wipes database)

Architecture

The tree below shows the shape of the codebase — the highlights, not every file. The backend has 57 Mongoose schemas and ~65 route modules (44 top-level + admin/ + somm/), plus the MCP server.

Cellarion/
├── backend/
│   ├── server.js                   # Entry point
│   └── src/
│       ├── app.js                  # Express app setup, mounting, rate limiters
│       ├── config/                 # db, plans, upload, aiConfig (models, prompts, limits)
│       ├── middleware/
│       │   ├── auth.js             # JWT + role middleware (requireAuth, requireAdmin, requireSomm)
│       │   └── bottleAccess.js     # requireBottleAccess(minRole) factory
│       ├── models/                 # 57 Mongoose schemas — core: User, WineDefinition,
│       │                           #   Bottle, Cellar, Rack, WineVintageProfile/Price,
│       │                           #   WineRequest, WineCorrectionProposal, BottleImage,
│       │                           #   AuditLog, Country/Region/Appellation/Grape;
│       │                           #   community: Discussion*, Review, JournalEntry,
│       │                           #   WishlistItem, WineList, Follow, RestockAlert;
│       │                           #   infra: Notification, PushSubscription, SupportTicket,
│       │                           #   ImportSession, StripeWebhookEvent, WineEmbedding,
│       │                           #   ClimateDevice/Reading, OAuth*, McpActionLog, …
│       ├── routes/                 # ~44 top-level route modules: auth (incl. Google SSO),
│       │                           #   cellars, bottles, wines (public read), racks, chat,
│       │                           #   stats, import, export, wineRequests, wineReports,
│       │                           #   discussions, reviews, journal, wishlist, wineLists,
│       │                           #   follows, recommendations, restockAlerts, climate,
│       │                           #   notifications, support, stripe, blog, og, sitemap,
│       │                           #   users, settings, images, health, superadmin, …
│       │   ├── admin/              # /api/admin/* — registry curation, taxonomy, users,
│       │   │                       #   tickets, proposals, fragmentation/cross-field queues
│       │   └── somm/               # /api/somm/* — maturity windows, prices, wine profiles
│       ├── mcp/                    # MCP server: registry, tools (read/write/somm/admin),
│       │                           #   OAuth, action ledger with undo
│       ├── services/               # search (Meili), embedding (Voyage/OpenAI-compatible),
│       │                           #   aiChat (RAG), labelScan, enrichmentJob, audit,
│       │                           #   findOrCreateWine, imageProcessor, taxonomyMerge,
│       │                           #   registryHealthJob, crossFieldScan, statsService, …
│       ├── utils/                  # normalize (dedup), cellarAccess, drinkWindow,
│       │                           #   grapeDisplay (regional names), nameChecks,
│       │                           #   crossFieldChecks, ratingUtils, maturityUtils, …
│       ├── data/                   # Taxonomy reference JSON
│       └── seed-demo.js
├── frontend/
│   ├── src/
│   │   ├── api/                    # Typed API client modules (one per resource)
│   │   ├── components/             # Reusable UI (Layout, Modal, BottleCard, rack grids, …)
│   │   ├── pages/                  # App screens (cellars, bottles, stats, chat, admin, …)
│   │   ├── contexts/               # Auth, Theme, Notifications
│   │   ├── locales/                # i18n (Weblate-managed except en)
│   │   └── utils/
│   ├── nginx.conf                  # nginx config (SPA + /api/ proxy)
│   └── Dockerfile                  # Multi-stage: Node build → nginx-unprivileged
├── rembg/                          # Python background-removal service
└── docker-compose.yml

Services

All external traffic enters through Traefik (runs on the shared web Docker network, external to this Compose file). All services inside this Compose file are internal only.

Running behind Traefik

Cellarion is designed to sit behind a Traefik reverse proxy on a shared Docker network called web. Traefik handles incoming HTTP on port 80 (SSL termination is handled upstream by Cloudflare or similar).

Requirements:

• A running Traefik instance connected to an external Docker network named web
• The web network must exist before starting Cellarion: docker network create web

The frontend service declares the following Traefik labels in docker-compose.yml:

traefik.enable: "true"
traefik.docker.network: "web"
traefik.http.routers.cellarion.rule: "Host(`cellarion.app`)"
traefik.http.routers.cellarion.entrypoints: "web"
traefik.http.services.cellarion.loadbalancer.server.port: "8080"

The upstream port is 8080 (not 80): the frontend image is built on nginxinc/nginx-unprivileged, whose non-root nginx cannot bind ports below 1024.

Update the Host(...) rule to match your own domain.

Connect your AI (MCP)

Cellarion ships a built-in Model Context Protocol server, so AI assistants can read and manage your cellar conversationally — "what should I open tonight?", "add these six bottles", "set the drink window for this vintage".

• Personal server — https://cellarion.app/api/mcp (OAuth; your own cellar, read/write/consume scopes, sommelier and admin tools for those roles, with an action ledger and undo_last)
• Public registry server — https://cellarion.app/api/mcp/public (no signup; read-only shared wine registry)
• Setup guide — cellarion.app/connect-ai has copy-paste config for Claude (web/Desktop/Code) and other MCP clients
• Also published as cellarion-mcp on npm and in the official MCP registry (app.cellarion/cellarion, app.cellarion/wine-registry)

Self-hosted instances serve the same endpoints from their own origin — the /connect-ai page renders instance-specific snippets automatically.

Core Concepts

User Roles

API Summary

The backend exposes ~65 route modules; this is the core surface, not an exhaustive reference. Wine registry reads (/api/wines, public wine pages, OG images, sitemap) are public; everything personal requires a JWT (Authorization: Bearer <token>).

Auth — /api/auth

Cellars — /api/cellars (auth required)

Bottles — /api/bottles (auth required)

Wine Registry — /api/wines

Public read. Regular-user searches are capped; admin/sommelier get full browse.

Chat — /api/chat (auth required)

MCP — /api/mcp and /api/mcp/public

See Connect your AI. OAuth 2.0 with dynamic client registration on the personal server; the public server needs no auth.

Community (auth required)

/api/discussions, /api/reviews, /api/journal, /api/wishlist, /api/wine-lists, /api/follows, /api/recommendations, /api/restock-alerts — lists, reviews, discussions, journal, wishlist, follows, and restock alerts.

Climate — /api/climate (auth required)

Register cellar sensors, ingest readings (Home Assistant-friendly token auth), per-cellar dashboards.

Notifications / Stats / Support / Wine Reports / Wine Requests (auth required)

As before: /api/notifications, /api/stats/overview, /api/support, /api/wine-reports, /api/wine-requests.

Sommelier — /api/somm/* (somm or admin role)

Admin — /api/admin/* (admin role required)

Wine definitions + merges, wine requests, correction proposals, taxonomy (incl. grape regional names), registry quality queues (dupl