Skip to main content

Local Dev Setup

This guide takes you from a fresh clone to a fully running local environment. Pick Option A (DevContainer — recommended) or Option B (bare-metal).

The DevContainer has all tools pre-installed at the correct versions. No manual setup required.

  1. Install VS Code and the Dev Containers extension.

  2. Open VS Code, press Ctrl+Shift+P (or Cmd+Shift+P on macOS), and select:

    Dev Containers: Clone Repository in Container Volume...

  3. Paste the repository URL and wait for the container to build.

  4. Once inside the container, start everything:

    pnpm dev:stack

  5. Skip ahead to Verify It Works.

Option B: Bare-Metal Setup​

Make sure you've installed all Prerequisites first.

1. Clone the Repository​

git clone https://github.com/gospelib/main.git
cd main

2. Run the Setup Script​

The setup script installs all dependencies across all three ecosystems:

bash tools/scripts/setup.sh

This script:

  1. Verifies all prerequisites are installed and at the correct versions
  2. Copies .env.example → .env.local (if it doesn't exist)
  3. Runs pnpm install (Node.js/TypeScript dependencies)
  4. Runs uv sync in each Python service (services/content, services/ai, services/ingest)
  5. Runs go mod download in each Go service (services/gateway, services/auth, services/billing, services/notifications)
Manual alternative

If you prefer to run steps individually:

# Node.js / TypeScript
pnpm install

# Python services
cd services/content && uv sync && cd ../..
cd services/ai && uv sync && cd ../..
cd services/ingest && uv sync && cd ../..

# Go services
cd services/gateway && go mod download && cd ../..
cd services/auth && go mod download && cd ../..
cd services/billing && go mod download && cd ../..
cd services/notifications && go mod download && cd ../..

3. Start Infrastructure​

The data stores (FalkorDB, PostgreSQL, Redis, Typesense) run via Docker Compose:

pnpm infra:up

Wait until all four containers are healthy. You can check with:

pnpm infra:logs

4. Start All Services and Apps​

pnpm dev:stack

This starts infrastructure (if not already running) plus all backend services and frontend apps in parallel.

Start only what you need

If you're working on a specific area, you can start services individually:

pnpm dev:web            # Just the Next.js web app (port 3002)
pnpm dev:services       # Just backend services (no frontend)

See the Port Map for all services and their ports.

Verify It Works​

Run the Health Check Script​

bash tools/scripts/health-check.sh

All services should report healthy.

Check Manually​

  1. Web app: Open http://localhost:3002 — you should see the GospeLib landing page.

  2. Admin dashboard: Open http://localhost:3001 — you should see the admin UI.

  3. Gateway health:

    curl http://localhost:8080/health

    Expected response: a JSON health status.

  4. Content service health:

    curl http://localhost:8100/health

Common Issues​

ProblemSolution
Port already in useCheck for conflicting processes: lsof -i :<port>
Docker containers won't startEnsure Docker daemon is running: docker ps
pnpm install failsVerify pnpm version is exactly 9.15.0: pnpm --version
Python uv sync failsEnsure Python >= 3.12 and uv is on your PATH
Go module download failsEnsure Go 1.23 is installed: go version

Shutting Down​

pnpm dev:stack:stop     # Stop all services and apps
pnpm infra:down         # Stop data store containers

To destroy all data and start fresh:

pnpm infra:reset        # Destroys volumes and restarts containers

Next Step​

Now that your environment is running, take the Repository Tour to understand the codebase layout.