Quick Start

Prerequisites

Before you begin, ensure the following tools are installed on your machine:

You will also need API keys for:

• OpenAI — GPT-4 for AI agents and embeddings
• Clerk — Authentication (create a free dev instance at clerk.com)
• Serper.dev — Primary web/news search provider (SERPER_API_KEY)
• Brave Search (optional) — Fallback search provider, used only when Serper errors (BRAVE_API_KEY)

Clone and Setup

Clone the monorepo and run the automated setup:

git clone https://github.com/TerraGuard/terraguard.git
cd terraguard
make setup

The make setup command will:

1. Copy .env.example to .env for each service (if .env does not already exist)
2. Install Python dependencies via Poetry for the backend API
3. Install Node.js dependencies for the frontend
4. Download Go module dependencies for the Go services
5. Pull required Docker images

After setup completes, edit the .env files in each service directory to add your API keys and configure database connection strings.

Configure the Database

TerraGuard requires PostgreSQL with the PostGIS and pgVector extensions. If you are running PostgreSQL locally:

# Create the database
createdb terraguard

# Enable required extensions (connect to the database first)
psql -d terraguard -c "CREATE EXTENSION IF NOT EXISTS postgis;"
psql -d terraguard -c "CREATE EXTENSION IF NOT EXISTS vector;"

Then update the DATABASE_URL in tg-backend-api/.env:

DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/terraguard

Run the database migrations:

cd tg-backend-api
poetry run alembic upgrade head

Start All Services

From the repository root:

make dev

This starts all services plus infrastructure dependencies. Alternatively, you can start services individually:

# Infrastructure (Redis, Inngest)
cd tg-backend-api/local-services && make up

# Backend API (includes the search layer — Serper + Brave)
cd tg-backend-api && make server

# Event Processor
cd tg-event-processor && make run

# Web Crawler
cd tg-web-crawler-api && make docker-up

# Frontend
cd tg-frontend && npm run dev

# GeoPop API
cd geopop-api && cargo run --release

Port Reference

Once everything is running, the services are available at:

The search layer is part of the Backend API and has no dedicated port.

Verify Services

Check that all services are healthy:

# Backend API
curl http://localhost:4000/api/v1/health

# Event Processor
curl http://localhost:4010/health

# Web Crawler API
curl http://localhost:4020/v1/health

# GeoPop API
curl http://localhost:5605/health

# Frontend (should return HTML)
curl -s http://localhost:4025 | head -5

All health endpoints should return a 200 status with a JSON response.

Trigger a Test Ingestion

To verify the full pipeline, trigger the event processor to fetch recent events:

# Trigger GDACS ingestion
curl -X POST http://localhost:4010/v1/ingest/gdacs

# Trigger USGS ingestion
curl -X POST http://localhost:4010/v1/ingest/usgs

After a few seconds, events should appear in the database and be visible on the frontend at http://localhost:4025.

Inngest Dashboard

The Inngest dev server provides a dashboard for monitoring background jobs:

# Usually available at
open http://localhost:8288

Use this to monitor the enrichment pipeline — you should see functions triggered for web search, content crawling, and vector indexing as new events are processed.

Common Issues

PostgreSQL extensions not found

If you see errors about missing postgis or vector extensions, install them:

# macOS with Homebrew
brew install postgis
brew install pgvector

# Ubuntu/Debian
sudo apt install postgresql-15-postgis-3
sudo apt install postgresql-15-pgvector

Search returns no results

Web and news search run inside the Backend API and call Serper.dev (primary) with Brave Search as an error fallback — there is no local search container to start. If searches return nothing, confirm the API keys are set in tg-backend-api/.env:

SERPER_API_KEY=...   # primary provider
BRAVE_API_KEY=...    # fallback, used only when Serper errors

If SERPER_API_KEY is unset, every search falls straight through to Brave; if both are unset, search returns an empty result set with a logged error.

Clerk authentication errors

For local development, create a Clerk development instance and add the keys to tg-backend-api/.env and tg-frontend/.env:

# Backend
CLERK_SECRET_KEY=sk_test_...

# Frontend
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

Next Steps

• Architecture Overview — Understand the system design
• Dashboard Guide — Learn the main interface
• Local Development (Detailed) — Advanced local setup options