A wine cellar tracker for Home Assistant or Docker - manage your entire collection from label photo to tasting notes.

📖 Documentation & Demo →

• Wine cards with photo, vintage, type, region, grape variety, rating & notes
• Photo upload - snap a label photo from your phone
• Star rating (1-5 stars)
• Quick quantity buttons (+/-) directly on the card
• Duplicate wines - perfect when only the vintage changes
• Bottle format - track sizes from Piccolo (0.1875l) to Nebuchadnezzar (15l)
• Empty bottles stay visible as placeholders (toggle to hide)
• Drink window (from/until year)
• Purchase price with configurable currency
• Storage location with autocomplete from existing entries
• Region & purchase source autocomplete from existing entries
• Grape variety (e.g. Merlot, Pinot Noir, Chardonnay) with autocomplete

• AI label recognition - snap a label photo and let AI fill in all fields, including maturity phases, taste profile and food pairings (6 providers: Anthropic, OpenAI, OpenRouter, Ollama, MiniMax, Mistral)
• Vivino wine search - search by name, see ratings, region & price, and import directly - with a regional fallback chain so country-specific wines (e.g. Australian labels) actually show up
• Vivino ID management - view, edit & test Vivino wine links directly in the edit modal
• Reload missing data - re-analyze wines with incomplete fields via AI or Vivino
• AI sommelier chat with full CRUD - ask questions about your cellar, upload wine label photos, and add / edit / delete wines directly from the conversation - with persistent chat history
• Maturity graph - AI-generated bell curve showing drinking phases (Youth, Maturity, Peak, Decline)
• Taste profile & food pairings - AI-generated body/tannin/acidity/sweetness bars and matching dish suggestions

• Cellar view modes - switch between Cards, List, Grid, and Table view
• Sortable table view - sort by any column with persistent sort direction
• Search & filter by wine type, vintage & grape variety
• Activity timeline - chronological log of wines added, consumed, restocked, or removed
• Interactive globe - see your wine regions on a 3D globe (COBE)
• Stock history chart - area chart showing bottle count development over the last 6 months
• Statistics - donut charts, total bottles, total liters, value overview & average age

• 6 themes - each with dark & light mode, switchable in settings
• Hamburger menu - navigation collapses on narrow viewports
• Fully responsive - works great on desktop & mobile
• Multi-language - 7 languages (DE, EN, FR, IT, ES, PT, NL)
• HA Ingress - embedded directly in the Home Assistant sidebar
• REST API at /api/summary for HA sensors
• DEV_AUTH mode - DEV_AUTH env var for quick local development without Home Assistant
• Backup & restore - export the whole cellar as a ZIP (JSON + CSV + images) and import it back with duplicate preview

7 languages: German (de), English (en), French (fr), Italian (it), Spanish (es), Portuguese (pt), Dutch (nl). Set via the language option.

See CHANGELOG.md for the full version history and ROADMAP.md for planned features.

Or install manually:

1. Go to Settings → Add-ons → Add-on Store
2. Top right: ⋮ → Repositories
3. Add the repository URL: https://github.com/xenofex7/ha-wine-tracker
4. Wine Tracker will appear in the store
5. Click Install → Start

The add-on opens in the HA sidebar under Wine Tracker.

Run Wine Tracker without Home Assistant using Docker Compose.

1. Create a docker-compose.yml:

services:
  wine-tracker:
    image: ghcr.io/xenofex7/wine-tracker:latest
    ports:
      - "5050:5050"
    volumes:
      - wine-data:/data
    environment:
      - AUTH_ENABLED=true
      - USERS=admin:changeme
      - SECRET_KEY=change-this-to-a-random-string
      - CURRENCY=CHF
      - LANGUAGE=de
    restart: unless-stopped

volumes:
  wine-data:

Full example: See docker/docker-compose.yml for a complete configuration with all available options.

2. Start it:

docker-compose up -d

3. Open http://localhost:5050 and log in.

User format: user1:password1,user2:password2,guest:password3:readonly

• Users are comma-separated
• Each user is username:password (full access) or username:password:readonly (view only)
• Readonly users can browse and search wines but cannot add, edit, or delete

Anthropic (Claude):

OpenAI (GPT):

OpenRouter (multi-provider):

Ollama (local, no API key needed):

Tip: When running Ollama in a separate container, use http://host.docker.internal:11434 as the host.

MiniMax:

Note: MiniMax-Text-01 is MiniMax's current vision-capable model - despite the name it accepts image input. The older MiniMax-VL-01 name is no longer accepted by the API.

Mistral:

Note: For label recognition (vision) use a Pixtral model (pixtral-large-latest, pixtral-12b-latest). Other Mistral models like mistral-large-latest work for the sommelier chat but cannot read labels.

docker-compose pull
docker-compose up -d

All data (SQLite database + photos) is stored in the Docker volume mounted at /data. As long as you keep the volume, your data survives container updates.

All options are configured via the Home Assistant add-on configuration page.

The AI feature lets you snap a photo of a wine label and automatically fills in the wine details (name, vintage, type, region, grape, price, notes).

Provider notes:

• Anthropic - uses the Claude API directly. Requires an API key from console.anthropic.com
• OpenAI - uses the OpenAI API. Requires an API key from platform.openai.com
• OpenRouter - a unified API that routes to many models. Requires an API key from openrouter.ai. You can choose any vision-capable model.
• Ollama - runs fully local, no API key needed. Install Ollama and pull a vision model (e.g. llava). Set the host to your Ollama server address.
• MiniMax - OpenAI-compatible API from minimaxi.chat. The default model MiniMax-Text-01 supports vision input despite the name; the older MiniMax-VL-01 name is no longer accepted by the API.
• Mistral - OpenAI-compatible API from mistral.ai. For label recognition use a Pixtral model (e.g. pixtral-large-latest); regular Mistral text models work for the sommelier chat but cannot read labels. A free Experiment plan is available for some regions (details).

Token cost varies by provider and model - typical analysis is ~2,500 tokens. See the provider's pricing page for current rates. Ollama runs locally and is free.

All data (SQLite database + photos) is stored under /share/wine-tracker/ - preserved across add-on updates, restarts, and HA updates.

# configuration.yaml
sensor:
  - platform: rest
    name: "Wine Stock"
    resource: "http://localhost:5050/api/summary"
    value_template: "{{ value_json.total_bottles }}"
    unit_of_measurement: "bottles"
    json_attributes:
      - by_type
    scan_interval: 3600

This creates a sensor.wine_stock entity you can use on dashboards or in automations.

MIT