Skip to content

DEVELOPER_SETUP.md

Latest commit

 

History

History
144 lines (107 loc) · 3.46 KB

DEVELOPER_SETUP.md

File metadata and controls

144 lines (107 loc) · 3.46 KB

Developer Setup Guide

Get Protocol Guide running locally with one command using Docker.

Prerequisites

  1. Docker Desktop — download here
    • Mac: Intel or Apple Silicon both work
    • Windows: Requires WSL 2 backend (Docker Desktop installer handles this)
    • Linux: Docker Engine + Docker Compose plugin
  2. Git — to clone the repo

That's it. No Node.js, no pnpm, no database setup needed.

Setup (5 minutes)

1. Clone the repo

git clone https://github.com/your-org/Protocol-Guide.git
cd Protocol-Guide

2. Create your .env file

cp .env.example .env

Open .env and fill in the required values. Ask Tanner for shared dev credentials.

Required variables:

  • SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY — Supabase project
  • DATABASE_URL — Supabase PostgreSQL connection string
  • ANTHROPIC_API_KEY — Claude API key
  • GOOGLE_API_KEY — Gemini Embedding 2 Preview key (Voyage removed 2026-03-24)
  • JWT_SECRET, NEXT_AUTH_SECRET — generate with openssl rand -base64 32

3. Start the app

docker compose up

First run takes 2-3 minutes to build the image and install dependencies. Subsequent runs start in seconds.

4. Open in browser

Service URL
Web app http://localhost:8081
API http://localhost:3001
API health check http://localhost:3001/api/live

Daily Workflow

# Start
docker compose up

# Start in background
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down

# Rebuild after package.json changes
docker compose up --build

Hot Reload

Source code is volume-mounted. Edit files on your machine and changes reflect immediately:

  • Server (server/): tsx watch auto-restarts
  • Frontend (app/, components/, hooks/, lib/): Metro hot reload

No need to restart Docker after code changes.

Troubleshooting

"Cannot connect to the Docker daemon"

Start Docker Desktop. Wait for it to finish loading.

Build fails on first run

docker compose down
docker compose up --build

Port 3001 or 8081 already in use

Something else is using those ports. Stop it, or change ports in docker-compose.yml:

ports:
  - "3002:3001"   # Change 3002 to whatever you want
  - "8082:8081"

Stale dependencies after pulling new code

docker compose down
docker compose build --no-cache
docker compose up

Container crashes with "Module not found"

Dependencies need reinstalling:

docker compose down -v    # Removes anonymous volumes including node_modules
docker compose up --build

Slow file watching on Windows/WSL

Add this to docker-compose.yml under the app service:

environment:
  - CHOKIDAR_USEPOLLING=true

Need Redis for rate limiting

docker compose --profile with-redis up

Then set REDIS_URL=redis://redis:6379 in your .env.

Architecture

docker compose up
  └── app (Dockerfile.dev)
       ├── Express API server  → localhost:3001
       └── Expo Metro bundler  → localhost:8081
           │
           ├── Supabase (remote) ← DATABASE_URL in .env
           ├── Claude API (remote) ← ANTHROPIC_API_KEY
           └── Google Gemini (remote) ← GOOGLE_API_KEY (Voyage removed 2026-03-24)

All external services (database, AI, payments) are remote. Docker only containerizes the Node.js runtime and dependencies.