An open-source wine cellar inventory manager. Track your collection by country, region, grape variety, winemaker, and vintage. Manage physical storage locations and monitor bottle inventory.
- Wine database with detailed attributes (country, region, grape, winemaker, vintage)
- Bottle inventory with per-bottle storage location tracking
- Drinking window tracking per vintage
- User accounts with admin and standard roles
- Multi-database support. Currently limited to Sqlite, with MySQL and Postgres in the works
- Tasting notes / ratings
- Upload images of your collection
- Import wine details from 3rd party websites (Vivino, Wine Society, Naked Wines etc)
- User & technical documentation
Frontend — Next.js 16, React 19, Tailwind CSS 4, TanStack Query v5, TanStack Form, Radix UI, Better Auth
Backend — Node.js 20, Hono, Kysely, Better Auth, Zod, Vitest
cellarboss/
├── apps/
│ ├── backend/ # Hono API server
│ └── web/ # Next.js frontend
├── assets/ # Coming soon...
├── docs/ # Coming soon...
└── packages/
├── types/ # Shared type definitions
└── validators/ # Shared Zod validators
- Node.js 20
- pnpm 9
pnpm installBackend (apps/backend/.env):
BETTER_AUTH_SECRET=<random-secret>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_TYPE=sqlite
DATABASE_URL=database.sqlite
NODE_ENV=development
Frontend (apps/web/.env):
CELLARBOSS_SERVER=http://localhost:5000
BETTER_AUTH_SECRET=<same-secret-as-backend>
NODE_ENV=development
cd apps/backend
pnpm auth:migrate
pnpm migrateOptionally seed some initial data:
pnpm seed# Backend (port 5000)
pnpm --filter backend dev
# Frontend (port 3000)
pnpm --filter web devA docker-compose.dev.yml is provided for running the full stack locally with PostgreSQL:
docker-compose -f docker-compose.dev.yml upThis starts PostgreSQL on port 5432, the backend on port 5000, and the frontend on port 3000.
There are separate test suites for individual parts of the project. Currently, all of these are automatically run whenever a PR is raised for a merge into the main branch.
vitest for all API routes
cd apps/backend
pnpm testvitest for all validation rules
cd packages/validators
pnpm testvitest for helper functions
cd apps/web
pnpm testplaywright end-to-end tests for user activities, with a mock backend API
cd apps/web
pnpm test:e2e# Build everything
pnpm build
# Or individually
pnpm --filter backend build
pnpm --filter web buildThe backend uses Kysely with dialect switching based on the DATABASE_TYPE environment variable:
| Value | Driver |
|---|---|
sqlite |
better-sqlite3 |
postgres |
pg |
mysql |
mysql2 |
Set DATABASE_URL to the appropriate connection string (or file path for SQLite).
I (mattdy) created this project to fufil a need in my own life, and decided to release it publically in case others find it useful. While I do have a background in software development, I am by no means an expert in React development. As such, I have made use of LLMs such as ChatGPT, Claude and Copilot to aid development.
I wouldn't go as far as calling this project 'vibe-coded', but certain elements have been written by AI models, and I will likely continue to utilise these within the project. This will possibly involve future features also being written by AI, but I am also considering automatic PR reviews and the like.
I am very happy to enter into a discussion on the merits of these, respecting my position the current sole developer on the project.
It is my intention to make this software free and available for community non-profit usage, without restriction. That said, I may choose to investigate commercial licencing arrangements in the future, should there be any demand for such support. In the meantime, if you wish to use this software in a commercial setting, then please consider giving back to the project.
Good observation! I'm terrible at graphic design, please get in touch if you can help with the styling!
Any feedback or suggestions are gratefully received via Issues
Great! As above, please raise an Issue