pantry/docs/development/local-setup.md

Pantry - Local Development Setup

Self-hosted household pantry management app with barcode scanning.

🚀 Quick Start

Prerequisites

• Docker & Docker Compose (for Supabase backend)
• Bun (for Nuxt frontend) - Install: curl -fsSL https://bun.sh/install | bash
• Git

1. Clone & Setup

git clone https://gitea.jeanlucmakiola.de/pantry-app/pantry.git
cd pantry

2. Start Supabase (Backend)

# Start all Supabase services
docker-compose up -d

# Wait ~10 seconds for services to initialize
# Check status
docker-compose ps

Services running:

• PostgreSQL: localhost:5432
• Supabase API: http://localhost:54321
• Supabase Studio: http://localhost:54323 (admin UI)

3. Apply Database Migrations

The migrations are automatically applied on first startup via /docker-entrypoint-initdb.d.

To verify:

docker-compose exec db psql -U postgres -d postgres -c "\dt"

You should see: inventory_items, products, tags, units, item_tags

4. Start Nuxt App (Frontend)

cd app
bun install
bun run dev

App running: http://localhost:3000

5. Open & Test

1. Visit http://localhost:3000
2. Click "Add Manually" to create your first inventory item
3. Access Supabase Studio at http://localhost:54323 to view database

---

📁 Project Structure

pantry/
├── app/                    # Nuxt 4 frontend
│   ├── components/         # Vue components
│   │   └── inventory/      # Inventory CRUD UI
│   ├── composables/        # Supabase client, data hooks
│   ├── pages/              # Routes (index, scan, settings)
│   └── types/              # TypeScript definitions
├── supabase/
│   └── migrations/         # SQL schema & seed data
├── docker/
│   └── kong.yml            # API gateway config
├── docker-compose.yml      # Supabase services
└── .env                    # Environment variables

---

🔧 Common Tasks

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f db
docker-compose logs -f auth

Reset Database

# Stop services
docker-compose down -v

# Restart (migrations auto-apply)
docker-compose up -d

Access Database

# psql
docker-compose exec db psql -U postgres -d postgres

# Supabase Studio (GUI)
# http://localhost:54323

Run Migrations Manually

# If you add new migrations after initial setup
docker-compose exec db psql -U postgres -d postgres -f /docker-entrypoint-initdb.d/003_helper_functions.sql

Create Test User

# Via Supabase Studio: http://localhost:54323
# → Authentication → Add User
# Email: test@example.com
# Password: password123

# Or via curl:
curl http://localhost:54321/auth/v1/signup \
  -H "apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

---

🧪 Testing Features

1. Inventory Management

• Add items manually via form
• Edit quantities with +/- buttons
• Delete items
• View expiry warnings

2. Tags & Organization

• Pre-seeded tags: Fridge, Freezer, Pantry, Dairy, Vegan, etc.
• Multi-select tags when adding items
• Color-coded badges

3. Units

• 30 pre-seeded units (g, kg, L, cups, pieces, etc.)
• Automatic conversion support

4. Barcode Scanning (Week 3 - In Progress)

• Camera access (requires HTTPS in production)
• Manual barcode entry fallback

---

🐛 Troubleshooting

Port Conflicts

If ports 5432, 54321, or 3000 are in use:

# Check what's using the port
sudo lsof -i :5432

# Option 1: Stop conflicting service
# Option 2: Change port in docker-compose.yml

Database Connection Refused

# Wait for PostgreSQL to fully start
docker-compose logs db | grep "ready to accept connections"

# If stuck, restart
docker-compose restart db

Migrations Not Applied

# Verify migrations directory is mounted
docker-compose exec db ls -la /docker-entrypoint-initdb.d

# Manually apply
docker-compose exec db bash
cd /docker-entrypoint-initdb.d
for f in *.sql; do psql -U postgres -d postgres -f "$f"; done

Frontend: Module Not Found

cd app
rm -rf node_modules bun.lock .nuxt
bun install
bun run dev

---

📊 Database Schema

Tables

Table	Purpose	Rows (Est.)
inventory_items	Current inventory	100-500
products	Barcode cache (Open Food Facts)	500-2000
tags	Organization labels	50 (33 pre-seeded)
units	Measurement units	50 (30 pre-seeded)
item_tags	Many-to-many item ↔ tag	200-1000

Pre-Seeded Data

Units (30):

• Weight: g, kg, mg, lb, oz
• Volume: mL, L, cup, tbsp, tsp, gal, qt, pt
• Count: piece, dozen, package, bottle, can, jar, box, bag

Tags (33):

• Position: Fridge, Freezer, Pantry, Cabinet
• Type: Dairy, Meat, Vegetables, Fruits, Snacks
• Dietary: Vegan, Gluten-Free, Organic, Kosher, Halal
• Custom: Low Stock, To Buy, Meal Prep, Leftovers

---

🔐 Authentication

Default Setup (Development):

• Auto-confirm emails (no SMTP needed)
• Anyone can sign up
• JWT tokens valid for 1 hour

Create Admin User:

-- Via psql
docker-compose exec db psql -U postgres -d postgres

INSERT INTO auth.users (id, email, encrypted_password, email_confirmed_at)
VALUES (
  gen_random_uuid(),
  'admin@pantry.local',
  crypt('admin123', gen_salt('bf')),
  NOW()
);

---

🌐 Environment Variables

.env (root)

POSTGRES_PASSWORD=postgres
JWT_SECRET=your-secret-here
ANON_KEY=<supabase-anon-key>
SERVICE_ROLE_KEY=<supabase-service-role-key>

app/.env (Nuxt)

NUXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NUXT_PUBLIC_SUPABASE_ANON_KEY=<same-as-above>

---

📈 Development Workflow

1. Make changes to Nuxt app → Hot reload at localhost:3000
2. Database changes → Create new migration in supabase/migrations/
3. Test → Add items, scan barcodes, check database
4. Commit → Feature branch → PR to develop

---

🚢 Production Deployment (Coming Soon)

See docs/DEPLOYMENT.md for:

• Coolify setup
• Environment configuration
• SSL/HTTPS setup
• Backups

---

📚 Documentation

• Architecture
• Database Schema
• API Reference
• Development Guide

---

🤝 Contributing

This is a personal project, but issues and PRs welcome!

1. Fork the repo
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

---

📝 License

MIT License - See LICENSE file

---

🙋 Support

• Issues: https://gitea.jeanlucmakiola.de/pantry-app/pantry/issues
• Docs: https://gitea.jeanlucmakiola.de/pantry-app/pantry/wiki

---

Version: 0.1.0-alpha (MVP in progress)
Status: Week 2 complete, Week 3 in progress (14/34 issues done)