Skip to main content

Getting Started with TVL Platform

Complete developer setup guide - 15 minutes total

Overview​

This guide walks you through setting up your local development environment for The Villa Life Platform.

What you'll set up:

  • ✅ Dev container with PostgreSQL, Node.js, pnpm
  • ✅ Secrets management with Doppler (or manual)
  • ✅ Database migrations and seed data
  • ✅ Verify tests pass

Time: 15 minutes

Prerequisites​

Before starting, ensure you have:

  • Docker Desktop - Download
  • VS Code - Download
  • Dev Containers Extension - Install
  • Git - Configure with your identity

Optional (Recommended for Teams):

Setup Steps​

Step 1: Clone Repository (1 minute)​

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

# Verify you're in the right directory
ls -la
# Should see: .devcontainer/, docs/, packages/, README.md, etc.

Step 2: Configure Secrets (5 minutes)​

Choose one option:

# 1. Install Doppler CLI
brew install dopplerhq/cli/doppler  # macOS
# curl -Ls https://cli.doppler.com/install.sh | sh  # Linux

# 2. Authenticate
doppler login

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

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

# ✅ Secrets configured!

See: Detailed Doppler Setup Guide

Option B: Manual Setup​

# 1. Copy template
cp .env.example .env.local

# 2. Defaults are already configured for local dev
# No need to edit unless you have specific requirements

# ✅ Secrets configured!

Step 3: Open in Dev Container (5 minutes)​

# 1. Open in VS Code
code .

# 2. Reopen in container
# Press F1 (or Cmd+Shift+P on Mac)
# Type: "Dev Containers: Reopen in Container"
# Press Enter

# 3. Wait for container to build (3-5 minutes first time)
# You'll see:
# - Building devcontainer...
# - Installing Node.js 20 + pnpm 8.x
# - Starting PostgreSQL 15
# - Running postCreateCommand...

What happens automatically:

  • ✅ PostgreSQL starts (accessible at localhost:5432)
  • ✅ Dependencies installed (pnpm install)
  • ✅ Database migrations applied (pnpm db:migrate)
  • ✅ Seed data loaded (pnpm db:seed)

Step 4: Verify Setup (2 minutes)​

# Open terminal in VS Code (inside container)

# 1. Check Node.js version
node --version
# Should show: v20.x.x

# 2. Check pnpm version
pnpm --version
# Should show: 10.19.x

# 3. Check database connection
pnpm db:console
# Should open psql console
# Type: \dt
# Should show: bookings, properties, organizations, etc.
# Type: \q to exit

# 4. Run tests
pnpm test:rls
# Should show: ✓ All RLS tests pass

# ✅ Setup complete!

What's Running?​

After setup, your environment includes:

Services​

  • PostgreSQL 15 - localhost:5432

    • Database: tvl_dev
    • User: tvl_user
    • Password: tvl_password

  • pgAdmin 4 - http://localhost:5050

    • Email: admin@thevillalife.com
    • Password: admin

Available 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: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

# Development
pnpm dev                  # Start dev server
pnpm build                # Build for production
pnpm clean                # Clean build artifacts

Next Steps​

Now that your environment is set up:

  1. Read the architecture - Architecture Overview
  2. Learn development workflow - CONTRIBUTING.md
  3. Understand database patterns - Database Setup Guide
  4. Review RLS policies - RLS Policy Patterns
  5. Start coding! - Pick an issue from Linear

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

Making Changes​

# 1. Create feature branch
git checkout -b feat/your-feature-name

# 2. Make changes
# - Write code
# - Write tests
# - Test locally

# 3. Run quality checks
pnpm lint
pnpm type-check
pnpm test

# 4. Commit changes
git add .
git commit -m "feat(scope): description"

# 5. Push and create PR
git push -u origin feat/your-feature-name

See CONTRIBUTING.md for full workflow details.

Troubleshooting​

DevContainer Won't Start​

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

# Still failing? Check:
# 1. Docker Desktop is running
# 2. .env.local exists
# 3. No port conflicts (5432, 5050)

Can't Connect to PostgreSQL​

# Check if postgres is running
docker ps | grep postgres

# 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

For more issues, see DevContainer Troubleshooting.

Environment Strategy​

99% of your development uses local Docker PostgreSQL:

EnvironmentDatabaseWhen to Use
Local (default)Docker PostgreSQLEveryday coding, testing migrations, RLS policies
Integration (optional)Supabase devTesting Auth, Storage, Realtime features
Staging (CI/CD)Supabase stagingTeam testing, QA before production
Production (CI/CD)Supabase productionLive environment

Keep it simple: Start local, only use remote when testing integrations.

See QUICKSTART.md for switching environments.

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      # 5-minute quick start
    └── guides/
        └── quickstart/
            ├── getting-started.md   # You are here!
            ├── doppler-setup.md     # Secrets management
            └── database-setup.md    # Database deep-dive

Getting Help​

Documentation​

Common Questions​

QuestionAnswer
Which database should I use?Local Docker PostgreSQL (99% of the time)
How do I rotate secrets?Run doppler secrets download > .env.local
Where are migrations?packages/database/migrations/
How do I test RLS policies?pnpm test:rls

Support​

If you're stuck:

  1. Search documentation - Most answers are documented
  2. Check Linear - Issue might already exist
  3. Ask in Slack - #tvl-dev channel
  4. Create Linear issue - Tag with question label

Summary​

You just completed:

  • ✅ Cloned repository
  • ✅ Configured secrets (Doppler or manual)
  • ✅ Started dev container
  • ✅ Verified database and tests

You're ready to:

  • ✅ Read architecture docs
  • ✅ Learn development workflow
  • ✅ Start coding!

Welcome to the team! 🚀

Last Updated: 2025-01-26 Maintained By: Tech Lead Status: Active