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

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

### 2. Start Supabase (Backend)

```bash
# 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:
```bash
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)

```bash
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

```bash
# All services
docker-compose logs -f

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

### Reset Database

```bash
# Stop services
docker-compose down -v

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

### Access Database

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

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

### Run Migrations Manually

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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:**

```sql
-- 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)
```bash
POSTGRES_PASSWORD=postgres
JWT_SECRET=your-secret-here
ANON_KEY=<supabase-anon-key>
SERVICE_ROLE_KEY=<supabase-service-role-key>
```

**app/.env** (Nuxt)
```bash
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](docs/ARCHITECTURE.md)
- [Database Schema](docs/DATABASE.md)
- [API Reference](docs/API.md)
- [Development Guide](docs/DEVELOPMENT.md)

---

## 🤝 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)