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). On by default in the installed app, a switch in Settings otherwise
• 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 + 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
• 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
• 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.