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
• Offline mode — Keeps a copy of your cellars, racks and bottles on the device, so the app works in the cellar with no signal: browse, find a bottle in its rack, consume/open/pour, place and move bottles, edit notes and ratings. Changes sync when you're back online — applied once (idempotency keys), and never silently over someone else's change (conflicts land in Needs attention). Off until the user chooses it: the installed app asks once, and Settings switches it anywhere
• 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, Ploc, 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, searched in MongoDB; 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
• Single sign-on — Optional Google SSO, or your own OIDC provider (Pocket ID, Authentik, Keycloak, Zitadel, Authelia), alongside email/password
• Installable app — PWA with push notifications and offline support (the service worker keeps each build for offline use), 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
• Voyage AI — Wine embedding generation (swappable for any OpenAI-compatible endpoint); the vectors are stored in MongoDB and compared by the backend — no vector database
• 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)

Upgrade

git pull
docker-compose up -d --build

Upgrading from v1.241.0 or earlier: Qdrant is retired. The wine vectors behind the AI cellar chat, restock suggestions and the MCP similarity tools now live in MongoDB, and the backend compares them itself — there is no vector database to run any more. After the upgrade the old qdrant container keeps running as an orphan, so its vectors can be copied over once, with no re-embedding and no embedding cost:

# dry run (counts only), then the real copy
docker-compose exec -e QDRANT_URL=http://qdrant:6333 backend node src/scripts/migrate-vectors-from-qdrant.js
docker-compose exec -e QDRANT_URL=http://qdrant:6333 backend node src/scripts/migrate-vectors-from-qdrant.js --apply
# then remove the old container, and later its volume
docker-compose up -d --remove-orphans
docker volume ls | grep qdrant      # e.g. cellarion_qdrant-data → docker volume rm cellarion_qdrant-data

• If you had set QDRANT_API_KEY, add -e QDRANT_API_KEY=<your key> to both commands (the new compose no longer passes it).
• Instead of copying, you can run a full embedding job in SuperAdmin → AI, which re-embeds every wine through your embedding provider.
• If embeddings were never configured (no VOYAGE_API_KEY / EMBEDDING_PROVIDER), there is nothing to copy — just remove the old container.
• Going back to v1.241.0 afterwards works, but run a full embedding job after that downgrade, and again after upgrading once more.

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),
│       │                           #   vectorStore (wine vectors in MongoDB, compared in memory),
│       │                           #   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.

Shared wine registry for self-hosters (Registry Bridge)

A self-hosted Cellarion starts with an empty wine registry. The Registry Bridge connects it to the shared registry on cellarion.app, one wine at a time: registry matches appear in your add-bottle search, the wine you pick is copied into your own database with its tasting profile and drink windows, copies are refreshed weekly (your own edits to a copy are kept, and REGISTRY_BRIDGE_REFRESH=off stops the refresh), and the corrections and values your users file flow back to the shared queues, credited to your install. The registry itself never leaves cellarion.app — no bulk download, no snapshot.

1. Sign in on cellarion.app, open Settings → Connect a self-hosted Cellarion, accept the Registry Data Terms and create a key (two per account, shown once).
2. Add the two lines to your .env and restart the backend:

REGISTRY_BRIDGE_URL=https://cellarion.app
REGISTRY_BRIDGE_KEY=cbr_…

Quotas, the monthly import window and the protocol are described in docs/registry-bridge.md; the terms are at cellarion.app/terms.

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