Cellarion Wine Registry

Cellarion

Cellarion is a hosted wine cellar app — a ready-to-use online service at [cellarion.app](https://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](https://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](https://cellarion.app) (Try the demo on the landing page) and an Android app on [Google Play](https://play.google.com/store/apps/details?id=app.cellarion.twa).

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](https://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

Make yourself admin

A fresh install has no admin. Register your own account in the app, then run:

docker exec cellarion-backend node src/scripts/make-admin.js <your username or email>

Sign out and in again to see the admin pages. --remove takes the role away again.

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= 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, │ │