Skip to main content

Quick Start Guide

Get up and running with TVL Platform in 5 minutes.

What Database Should I Use?​

┌────────────────────────────────────────────────────────────┐
│  Scenario              │  Database                         │
├────────────────────────────────────────────────────────────┤
│  Everyday coding       │  ✅ Docker PostgreSQL (local)    │
│  Testing migrations    │  ✅ Docker PostgreSQL (local)    │
│  Testing RLS policies  │  ✅ Docker PostgreSQL (local)    │
│  Testing Supabase Auth │  🔌 Remote Supabase (dev)        │
│  Team staging          │  🎯 Remote Supabase (staging)    │
│  Production            │  🚀 Remote Supabase (production) │
└────────────────────────────────────────────────────────────┘

99% of your development will use local Docker PostgreSQL.

5-Minute Setup​

Prerequisites​

What is Doppler?​

Doppler is our cloud-based secrets management platform. Think of it as a secure vault for environment variables that automatically syncs across your team.

Benefits:

  • ✅ 5-minute onboarding (vs 30 minutes manually copying secrets)
  • ✅ Automatic sync - Secrets update when rotated (no manual coordination)
  • ✅ Team collaboration - Shared secrets for database, APIs, etc.
  • ✅ Audit logs - Track who accessed which secrets
  • ✅ SOC 2 certified - Helps achieve compliance
  • ✅ Free for teams <5 - Unlimited secrets

Learn more: Doppler Quickstart Guide | Operations Guide

Setup Steps​

# 1. Clone repository
git clone https://github.com/your-org/the-villa-life.git
cd the-villa-life

# 2. Install Doppler CLI (one-time)
brew install dopplerhq/cli/doppler  # macOS
# curl -Ls https://cli.doppler.com/install.sh | sh  # Linux/Windows WSL

# 3. Authenticate with Doppler
doppler login

# 4. Link to project
doppler setup  # Choose: tvl-platform → development

# 5. Download secrets
doppler secrets download --no-file --format env > .env.local

# 6. Open in VS Code
code .

# 7. Reopen in container
# Command Palette (F1): "Dev Containers: Reopen in Container"

# 8. Wait for setup (3-5 min first time)
# ✅ PostgreSQL running
# ✅ Dependencies installed
# ✅ Migrations applied
# ✅ Test data seeded

# 6. Verify setup
pnpm db:console  # Should open psql

Option 2: Manual Setup (Solo Developers)​

# 1. Clone repository
git clone https://github.com/your-org/the-villa-life.git
cd the-villa-life

# 2. Copy environment template
cp .env.example .env.local

# 3. Open in VS Code
code .

# 4. Reopen in container
# F1 → Dev Containers: Reopen in Container

# 5. Verify setup
pnpm db:console

Daily Workflow​

Starting Your Day​

# Open VS Code (automatically opens in container)
code .

# Pull latest changes
git pull origin main

# Check database status
pnpm db:migrate:status

# Run tests to verify everything works
pnpm test:rls

Common Commands​

Database​

pnpm db:migrate           # Run pending migrations
pnpm db:migrate:create    # Create new migration
pnpm db:rollback          # Rollback last migration
pnpm db:seed              # Load test data
pnpm db:reset             # Destroy + rebuild (local only!)
pnpm db:console           # Open psql console

Testing​

pnpm test                 # All tests
pnpm test:watch           # Watch mode
pnpm test:rls             # RLS policy tests
pnpm test:db              # Database tests
pnpm test:coverage        # Coverage report

Code Quality​

pnpm lint                 # Check code style
pnpm lint:fix             # Auto-fix issues
pnpm format               # Format with Prettier
pnpm type-check           # TypeScript validation

Environment Strategy​

Your typical week looks like this:

Monday - Friday (Everyday Development)​

Use: Local Docker PostgreSQL in dev container

Why?

  • ⚡ Fast: <1ms query latency
  • 🔒 Isolated: Your own database, can't break anyone else
  • 💰 Free: No API limits
  • 📡 Offline: Work without internet
  • 🧪 Safe: Reset database 100x a day if needed

Commands:

pnpm db:reset             # Safe to destroy and rebuild
pnpm test:rls             # Test RLS policies locally

Occasionally (Integration Testing)​

Use: Remote Supabase dev project (optional)

When?

  • Testing Supabase Auth (Google OIDC, magic links)
  • Testing Supabase Storage (file uploads)
  • Testing Supabase Realtime (websockets)
  • Testing external APIs (Hostaway, Stripe webhooks)

Setup:

# Create separate Supabase project: "tvl-dev-integration"
# Get connection string from Supabase dashboard

# Temporarily update .env.local
DATABASE_ENVIRONMENT=supabase-dev
DATABASE_URL=postgresql://postgres.[PROJECT_REF]:[PASSWORD]@...

# Rebuild container
# F1 → Dev Containers: Rebuild Container

# Run integration tests
pnpm test:integration

# Switch back to local when done
DATABASE_ENVIRONMENT=local

Feature Complete (Staging)​

Use: Remote Supabase staging project (via CI/CD)

You don't deploy manually - CI/CD handles this:

  1. Push code to feature branch
  2. Create PR
  3. CI runs tests with local PostgreSQL
  4. Merge to main
  5. CI deploys to staging automatically

Going Live (Production)​

Use: Remote Supabase production (via CI/CD only)

Manual approval required for production deployments.

Switching Environments​

Local → Remote Supabase​

Only when you need Supabase-specific features:

# 1. Get Supabase credentials
# Visit: https://app.supabase.com/project/_/settings/database

# 2. Update .env.local
DATABASE_ENVIRONMENT=supabase-dev
DATABASE_URL=postgresql://postgres.[PROJECT_REF]:[PASSWORD]@...
SUPABASE_URL=https://[PROJECT_REF].supabase.co
SUPABASE_ANON_KEY=your-anon-key

# 3. Rebuild container
# F1 → Dev Containers: Rebuild Container

Remote → Local​

# 1. Update .env.local
DATABASE_ENVIRONMENT=local

# 2. Rebuild container
# F1 → Dev Containers: Rebuild Container

Troubleshooting​

DevContainer Won't Start​

# Rebuild from scratch
# F1 → Dev Containers: Rebuild Container

# Still failing? Check Docker Desktop is running

Can't Connect to PostgreSQL​

# Check if postgres is running
docker ps

# Test connection manually
psql postgresql://tvl_user:tvl_password@localhost:5432/tvl_dev

# Check logs
docker logs tvl-postgres

Migrations Failing​

# Check status
pnpm db:migrate:status

# Reset and try again (local only!)
pnpm db:reset

Tests Failing​

# Ensure database is seeded
pnpm db:seed

# Check you're on local database
echo $DATABASE_URL
# Should be: postgresql://tvl_user:tvl_password@localhost:5432/tvl_dev

# Run specific test
pnpm test booking-service.test.ts

Access URLs​

When container is running:

Key Files​

the-villa-life/
├── .env.example           # Template (committed)
├── .env.local             # Your config (NOT committed)
├── .devcontainer/         # Dev container setup
│   ├── devcontainer.json
│   ├── docker-compose.yml
│   └── Dockerfile
├── packages/
│   └── database/          # Database package
│       ├── migrations/    # SQL migrations
│       └── seeds/         # Test data
└── docs/
    ├── QUICKSTART.md      # You are here!
    ├── guides/            # Implementation guides
    └── reference/         # Technical reference

Next Steps​

  1. ✅ Complete setup - You're here!
  2. 📖 Read CONTRIBUTING.md - Development workflow
  3. 🏗️ Review architecture - Architecture Docs
  4. 🔒 Learn RLS patterns - RLS Policy Patterns
  5. 🚀 Start coding!

Remember​

  • 🏠 Local dev = Docker PostgreSQL (99% of your time)
  • 🔌 Remote dev = Supabase (when testing integrations)
  • 🎯 Staging = Supabase (team testing via CI/CD)
  • 🚀 Production = Supabase (live via CI/CD)

Keep it simple. Start local. Scale when needed. 🎯

Detailed Documentation​

For more comprehensive guides, see:

Last Updated: 2025-10-25