WineBox
Documentation
User Guide
Dashboard Overview
Checking In Wine
Step-by-Step
What Gets Detected
Using Wine Autocomplete
Viewing Your Cellar
Filters
Quick Search
Wine Cards
Wine Details
Checking Out Wine
Searching Your Cellar
Available Filters
Search Tips
Transaction History
What’s Recorded
Filtering History
Importing from Spreadsheets
Import Workflow
Custom Fields
Exporting Your Collection
Supported Formats
Custom Fields in Exports
Export via API
Tips for Best Results
Taking Great Label Photos
AI Scanning Options
Keeping Your Cellar Organized
Data Backup
For Developers
Project Structure
Development Setup
Installing the X-Wines Database
Test Dataset (Development)
Full Dataset (100K+ Wines)
Verify Import
Running Tests
Invoke Tasks Reference
Server Management
Database Management
Database Migrations
User Management (Development)
Documentation
API Reference
Authentication
Wine Management
Cellar & History
Search
X-Wines Dataset
Example: Check In via API
Example: Search via API
Building Documentation
Configuration
Configuration Files
File Locations
Development
User Configuration
System Configuration (Production)
Quick Setup
Development
Production
Configuration Reference
config.toml
secrets.env
Environment Variable Overrides
Examples
Boolean Values
All Environment Variables
Runtime — required
Runtime — optional
Backups (S3)
Deployment (DigitalOcean)
Testing
Legacy / migration-only
Configuration Sections
Server
Database
Storage
OCR
Auth
Email
Common Configurations
Development
Production
Security Best Practices
Troubleshooting
Configuration Not Loading
Environment Variables Not Working
MongoDB Connection Issues
Secret Key Warnings
Deployment
Architecture
Prerequisites
One-Command Deployment
Required Environment Variables
Step-by-Step Deployment
1. Initial Server Setup
2. Configure DNS
3. Deploy Application
4. Setup SSL
5. Create Admin User
6. Deploy X-Wines Dataset (Optional)
Deploy Module
deploy.initialise
deploy.setup
deploy.app
deploy.xwines
OAT Admin Panel
Architecture
Allowlist
One-time bring-up
Routine deploys
Smoke test (post-deploy)
Service status / logs
Production Admin Panel
Allowlist
One-time bring-up
Routine deploys
Smoke test (post-deploy)
Database Migrations
Text Index Migration (v0.5.12)
Database
MongoDB Atlas
Configuration
Environment Variables
Production Configuration
Server Management
systemd Commands
nginx Commands
File Locations
Synced Secrets
Updating WineBox
Standard Update
Specific Version
Manual Update
Monitoring
Health Check
Service Status
Recent Logs
Backup and Recovery
Backup
Restore
Troubleshooting
Service Won’t Start
502 Bad Gateway
SSL Certificate Issues
Database Connection Issues
Security
Firewall
Secrets
Updates
API Reference
Base URL
Authentication
Getting a Token
Using the Token
Token Expiration
Endpoints
Health Check
GET /health
Wine Endpoints
POST /api/wines/record
POST /api/wines/{wine_id}/checkout
GET /api/wines
GET /api/wines/{wine_id}
PUT /api/wines/{wine_id}
DELETE /api/wines/{wine_id}
Cellar Endpoints
GET /api/cellar
GET /api/cellar/summary
Transaction Endpoints
GET /api/transactions
GET /api/transactions/{transaction_id}
Search Endpoint
GET /api/search
Images
GET /api/images/{filename}
Export Endpoints
GET /api/export/wines
GET /api/export/transactions
Import Endpoints
POST /api/import/upload
POST /api/import/{batch_id}/mapping
POST /api/import/{batch_id}/process
X-Wines Dataset Endpoints
GET /api/xwines/search
GET /api/xwines/wines/{wine_id}
GET /api/xwines/stats
GET /api/xwines/types
GET /api/xwines/countries
Error Responses
400 Bad Request
404 Not Found
422 Unprocessable Entity
500 Internal Server Error
Wine Pricing Data Architecture
Data Sources
1. X-Wines Dataset (Reference Wine Catalogue)
2. Kaggle/Vivino Wine Prices (Real Market Data)
3. Claude Haiku API (AI Price Estimation)
4. Brave Search API (Price Validation)
MongoDB Collections
xwines_wines
– Reference Wine Catalogue
xwines_prices
– Estimated Retail Prices
kaggle_wine_prices
– Vivino Market Reference
xwines_price_validations
– Validation Results
xwines_metadata
– Dataset Version Tracking
Data Flow
Price Tiers
Scripts Reference
Annotation Script Options
Accuracy
WineBox
Index
Index