Doppler Quickstart Guide - TVL Platform

Date: 2025-10-25 Status: Active Setup Guide Target Audience: All developers joining the TVL Platform team Time Required: 10-15 minutes

What is Doppler?

Doppler is a cloud-based secrets management platform that:

✅ Stores environment variables securely (encrypted at rest with AES-256)
✅ Syncs secrets across your team automatically
✅ Provides audit logs (who accessed what secret when)
✅ Enables fast secret rotation (update once, syncs everywhere)
✅ Is SOC 2 Type II certified (helps achieve SOC 2 compliance)

Why we use it:

Team Collaboration: Onboard new developers in 5 minutes (vs 30 minutes manually)
Secret Rotation: Rotate secrets in 10 minutes (vs 2 hours manually)
Zero Maintenance: No infrastructure to manage (vs self-hosted Infisical)
Free Tier: 5 users, unlimited secrets (sufficient for MVP.0-MVP.2)

Step 1: Install Doppler CLI (5 minutes)

macOS

# Install via Homebrew
brew install dopplerhq/cli/doppler

# Verify installation
doppler --version
# Should show: doppler version 3.x.x

Linux

# Install via script
curl -Ls https://cli.doppler.com/install.sh | sh

# Verify installation
doppler --version

Windows (WSL)

# Use Linux installation method in WSL
curl -Ls https://cli.doppler.com/install.sh | sh

# Verify installation
doppler --version

Step 2: Authenticate (1 minute)

# Login (opens browser for authentication)
doppler login

# ✅ You'll see: "Authenticated successfully!"

What happens:

Browser opens to https://dashboard.doppler.com
Sign in with Google (use your company email)
CLI receives authentication token
Token stored securely in ~/.doppler/.doppler.yaml

Step 3: Select Project & Environment (1 minute)

# Navigate to project directory
cd /path/to/the-villa-life

# Setup Doppler (non-interactive - recommended)
doppler setup --project tvl-mvp-v0 --config dev

# ✅ Doppler is now configured for this directory

# Verify configuration
doppler configure get project config --plain
# Should show:
# tvl-mvp-v0
# dev

Alternative: Interactive Setup

# Setup Doppler (interactive)
doppler setup

# You'll be prompted:
# ? Select a project: tvl-mvp-v0
# ? Select a config: dev

What this does:

Stores project configuration in Doppler config directory (~/.doppler/)
Links your workspace directory to tvl-mvp-v0/dev in Doppler
No .doppler.yaml file needed (uses directory scope)

Step 4: Add Local Development Secrets (2 minutes)

If setting up for the first time, add your local development secrets:

# Add all local development secrets at once
doppler secrets set \
  DATABASE_ENVIRONMENT="local" \
  DATABASE_URL="postgresql://tvl_user:tvl_password@postgres:5432/tvl_dev" \
  DATABASE_TEST_URL="postgresql://tvl_user:tvl_password@postgres:5432/tvl_test" \
  POSTGRES_USER="postgres" \
  POSTGRES_PASSWORD="postgres" \
  TVL_USER="tvl_user" \
  TVL_PASSWORD="tvl_password" \
  NODE_ENV="development" \
  PGADMIN_DEFAULT_EMAIL="admin@thevillalife.com" \
  PGADMIN_DEFAULT_PASSWORD="admin"

# ✅ Secrets added to Doppler

Skip this step if secrets already exist in Doppler.

Step 5: Sync Secrets to `.env.local` (1 minute)

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

# Verify secrets were downloaded
cat .env.local
# Should show:
# DATABASE_ENVIRONMENT=local
# DATABASE_URL=postgresql://...
# NODE_ENV=development
# ... etc.

Important:

✅ .env.local is gitignored (never committed)
✅ .env.local is generated from Doppler (always up-to-date)
❌ Never edit .env.local manually (changes will be overwritten)

Step 6: Rebuild Dev Container (2 minutes)

# Open in VS Code
code .

# Rebuild container (F1 or Cmd+Shift+P)
# Type: "Dev Containers: Rebuild Container"
# Press Enter

# Wait 2-3 minutes for container to rebuild
# ✅ Container starts with secrets from .env.local

Alternative (if not using devcontainer):

# Just start your development server
pnpm dev

# Secrets from .env.local are automatically loaded

Step 7: Verify Setup (1 minute)

# Inside devcontainer (or terminal), check environment variables
echo $DATABASE_URL
# Should show: postgresql://tvl_user:tvl_password@localhost:5432/tvl_dev

echo $DATABASE_ENVIRONMENT
# Should show: local

# Test database connection
pnpm db:console
# Should connect to PostgreSQL successfully

✅ Success! You're now using Doppler for secrets management.

Daily Workflow

Starting Work (No Changes Needed)

# 1. Open VS Code
code .

# 2. Reopen in Container (if using devcontainer)
# F1 → Dev Containers: Reopen in Container

# 3. Start coding
# ✅ Secrets automatically loaded from .env.local

No manual steps needed - Doppler secrets are already in .env.local

When Secrets Change (Rare)

Scenario: Team lead rotates database password in Doppler

Your workflow:

# 1. Pull latest secrets
doppler secrets download --no-file --format env > .env.local

# 2. Rebuild container (if using devcontainer)
# F1 → Dev Containers: Rebuild Container

# ✅ You now have the updated password

Frequency: Once per quarter (or when team member leaves)

Switching Environments

Use Local PostgreSQL (Default - `dev`)

# Switch to dev environment
doppler setup --project tvl-mvp-v0 --config dev

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

# Rebuild container
# F1 → Dev Containers: Rebuild Container

# ✅ Using local Docker PostgreSQL

Config: dev Database: Local PostgreSQL (Docker) Purpose: Day-to-day development

Use Personal Development (`dev_personal`)

# Switch to personal dev environment
doppler setup --project tvl-mvp-v0 --config dev_personal

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

# Rebuild container
# F1 → Dev Containers: Rebuild Container

# ✅ Using personal dev configuration

Config: dev_personal Purpose: Personal development settings (custom database, API keys for testing)

Use Staging (`stg`)

# Switch to staging environment
doppler setup --project tvl-mvp-v0 --config stg

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

# Rebuild container
# F1 → Dev Containers: Rebuild Container

# ✅ Using staging environment

Config: stg Database: Supabase staging When to use:

QA testing before production deploy
Reproducing customer-reported bugs
Integration testing with external services

Use Production (`prd`)

# ⚠️ WARNING: Only for emergency production debugging
doppler setup --project tvl-mvp-v0 --config prd

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

# ✅ Using production environment (READ-ONLY recommended)

Config: prd Database: Supabase production When to use:

Emergency production debugging (READ-ONLY)
Production data migrations (with approval)
Never for regular development

Common Tasks

View All Secrets

# List all secrets in current environment
doppler secrets

# Output:
# NAME                          VALUE
# DATABASE_URL                  postgresql://...
# DATABASE_ENVIRONMENT          local
# NODE_ENV                      development
# ...

Get Single Secret

# Get specific secret value
doppler secrets get DATABASE_URL

# Output:
# postgresql://tvl_user:tvl_password@localhost:5432/tvl_dev

Set Secret (Team Leads Only)

# Update a secret in Doppler
doppler secrets set DATABASE_URL="postgresql://new_connection_string"

# ⚠️ This updates Doppler (affects all team members)
# Notify team: "Secrets updated, run: doppler secrets download > .env.local"

Compare Environments

# See differences between dev and production
doppler secrets diff dev prd

# Output:
# DATABASE_URL: different
# STRIPE_SECRET_KEY: different (test vs live)
# NODE_ENV: different (development vs production)

Troubleshooting

Error: "Could not find project"

Cause: Not authenticated or project doesn't exist

Fix:

# Re-authenticate
doppler login

# Setup project again
doppler setup
# Choose: tvl-platform → development

Error: ".env.local is empty"

Cause: Doppler config not set or no secrets in environment

Fix:

# Check current setup
doppler configure get

# Re-setup if needed
doppler setup

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

Error: "Permission denied"

Cause: You don't have access to the Doppler project

Fix:

# Contact team lead to invite you to Doppler workspace
# Email: tech-lead@example.com
# Message: "Please invite me to Doppler workspace (email: your@email.com)"

Secret Value Looks Wrong

Cause: Wrong environment selected

Fix:

# Check current config
doppler configure get
# Shows: project=tvl-platform, config=production (WRONG!)

# Switch to development
doppler setup
# Choose: tvl-platform → development

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

Want to Use Manual .env.local (Not Recommended)

If you must:

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

# 2. Fill in values manually
# Edit .env.local

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

# ⚠️ Downsides:
# - No auto-sync (you miss secret rotations)
# - No audit trail (can't see who accessed secrets)
# - Manual updates (when secrets change)

Security Best Practices

✅ DO:

Use Doppler for all secrets (database passwords, API keys, etc.)
Keep .env.local gitignored (never commit secrets)
Rotate secrets quarterly (or when team member leaves)
Use environment-specific configs (development, integration, staging, production)
Review audit logs (check who accessed production secrets)

❌ DON'T:

Never commit .env.local to Git (use .gitignore)
Never share secrets via Slack/email (invite to Doppler instead)
Never use production secrets in development (use development config)
Never edit .env.local manually (always sync from Doppler)
Never hardcode secrets in code (use environment variables)

Advanced: CI/CD Integration

GitHub Actions (Service Token)

# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Install Doppler CLI
      - uses: dopplerhq/cli-action@v3

      # Run tests with Doppler secrets
      - name: Run tests
        run: doppler run -- pnpm test
        env:
          DOPPLER_TOKEN: ${{ secrets.DOPPLER_TOKEN_STAGING }}

Setup:

Generate service token in Doppler (for staging environment)
Add DOPPLER_TOKEN_STAGING to GitHub repository secrets
✅ GitHub Actions automatically gets all staging secrets!

No need to add 30+ individual secrets to GitHub!

Cost & Limits

Free Tier (Current)

Users: 5 (current team size: 3)
Secrets: Unlimited
Environments: Unlimited (we use 4: dev, integration, staging, production)
Audit Logs: 30 days retention
Support: Community (Slack, email)

Cost: $0/month

Team Tier (When > 5 Users)

Users: Unlimited
Price: $12/user/month
Audit Logs: 1 year retention
Support: Email support (24-hour response)

Example (10 users):

Cost: $120/month = $1,440/year
Still cheaper than self-hosted Infisical ($1,600/year DevOps overhead)

Resources

Doppler Dashboard: https://dashboard.doppler.com
Doppler Docs: https://docs.doppler.com
CLI Reference: https://docs.doppler.com/docs/cli
VS Code Extension: https://marketplace.visualstudio.com/items?itemName=Doppler.doppler-vscode

Summary

Setup (One-Time):

Install Doppler CLI (5 min)
Authenticate (1 min)
Select project/environment (1 min)
Download secrets to .env.local (1 min)
Rebuild container (2 min)

Total: 10 minutes

Daily Workflow:

✅ No manual steps (secrets automatically loaded)
✅ Update secrets when rotated (once per quarter)

Benefits:

✅ Fast onboarding (5 min vs 30 min)
✅ Fast rotation (10 min vs 2 hours)
✅ Auto-sync (no manual updates)
✅ Audit trail (who accessed what)
✅ SOC 2 compliant (helps achieve certification)

Next Steps:

✅ Complete this setup (10 min)
✅ Verify database connection (1 min)
✅ Start coding (you're ready!)

Questions? Ask in #dev-setup Slack channel or contact tech lead.

Last Updated: 2025-10-27 Maintained By: Tech Lead Status: Active

Recent Updates:

2025-10-27: Updated to reflect actual project configuration (tvl-mvp-v0 with configs: dev, dev_personal, stg, prd)
2025-10-27: Added Step 4 for adding local development secrets via CLI
2025-10-27: Updated all environment switching examples to use correct config names

What is Doppler?​

Step 1: Install Doppler CLI (5 minutes)​

macOS​

Linux​

Windows (WSL)​

Step 2: Authenticate (1 minute)​

Step 3: Select Project & Environment (1 minute)​

Step 4: Add Local Development Secrets (2 minutes)​

Step 5: Sync Secrets to .env.local (1 minute)​

Step 6: Rebuild Dev Container (2 minutes)​

Step 7: Verify Setup (1 minute)​

Daily Workflow​

Starting Work (No Changes Needed)​

When Secrets Change (Rare)​

Switching Environments​

Use Local PostgreSQL (Default - dev)​

Use Personal Development (dev_personal)​

Use Staging (stg)​

Use Production (prd)​

Common Tasks​

View All Secrets​

Get Single Secret​

Set Secret (Team Leads Only)​

Compare Environments​

Troubleshooting​

Error: "Could not find project"​

Error: ".env.local is empty"​

Error: "Permission denied"​

Secret Value Looks Wrong​

Want to Use Manual .env.local (Not Recommended)​

Security Best Practices​

✅ DO:​

❌ DON'T:​

Advanced: CI/CD Integration​

GitHub Actions (Service Token)​

Cost & Limits​

Free Tier (Current)​

Team Tier (When > 5 Users)​

Resources​

Summary​

What is Doppler?

Step 1: Install Doppler CLI (5 minutes)

macOS

Linux

Windows (WSL)

Step 2: Authenticate (1 minute)

Step 3: Select Project & Environment (1 minute)

Step 4: Add Local Development Secrets (2 minutes)

Step 5: Sync Secrets to `.env.local` (1 minute)

Step 6: Rebuild Dev Container (2 minutes)

Step 7: Verify Setup (1 minute)

Daily Workflow

Starting Work (No Changes Needed)

When Secrets Change (Rare)

Switching Environments

Use Local PostgreSQL (Default - `dev`)

Use Personal Development (`dev_personal`)

Use Staging (`stg`)

Use Production (`prd`)

Common Tasks

View All Secrets

Get Single Secret

Set Secret (Team Leads Only)

Compare Environments

Troubleshooting

Error: "Could not find project"

Error: ".env.local is empty"

Error: "Permission denied"

Secret Value Looks Wrong

Want to Use Manual .env.local (Not Recommended)

Security Best Practices

✅ DO:

❌ DON'T:

Advanced: CI/CD Integration

GitHub Actions (Service Token)

Cost & Limits

Free Tier (Current)

Team Tier (When > 5 Users)

Resources

Summary