Local Development

Set up the TerraGuard platform for local development, including prerequisites, environment configuration, port assignments, and testing workflows.

Prerequisites

Before running TerraGuard locally, ensure you have the following installed:

Dependency	Version	Purpose
PostgreSQL	15+ with PostGIS & pgVector	Primary data store with geospatial and vector extensions
Docker & Docker Compose	Latest	Container orchestration for support services
Node.js	20+	Frontend build toolchain
Go	1.22+	Event processor, crawler API
Python	3.11+	Backend API, crawler worker
Poetry	Latest	Python dependency management
Make	Any	Task runner for all services

Setup

1. Clone the Monorepo

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

2. Install Dependencies

Run the unified setup command to install dependencies for all services:

make setup

This runs npm install for the frontend, poetry install for the backend, and go mod download for the Go services.

3. Configure Environment Variables

Each service has a .env.example file. Copy and fill in the required values:

cp tg-backend-api/.env.example tg-backend-api/.env
cp tg-frontend/.env.example tg-frontend/.env
cp tg-event-processor/.env.example tg-event-processor/.env
cp tg-web-crawler-api/.env.example tg-web-crawler-api/.env

At minimum, configure your PostgreSQL connection string and Clerk API keys. For web/news search, set SERPER_API_KEY (primary provider) and BRAVE_API_KEY (fallback) in tg-backend-api/.env — search runs inside the Backend API, so there are no SearXNG or Tor containers to configure. See each .env.example for the full list of required variables.

4. Start All Services

make dev

This starts all services, infrastructure containers, and MCP servers. The first run may take a few minutes while Docker images are pulled and Go binaries are compiled.

Port Assignments

All local services are mapped to the 4000+ port range to avoid conflicts:

Port	Service	Description
4000	Frontend	Next.js web interface
5601	Backend API	Python/FastAPI REST API (includes the search layer)
5603	Crawler API	Go crawler job manager
4004	Crawler Worker	Python crawl4ai browser worker
5605	GeoPop API	Rust reverse geocoding service
5606	Event Processor	Go event ingestion service
4007	Inngest UI	Inngest dashboard for job monitoring
4008	Inngest API	Inngest event/function API
4011	Mailpit SMTP	Local email capture (SMTP)
4012	Mailpit Web	Local email viewer (web UI)
4013	Redis	In-memory store for Inngest
4021-4025	MCP Servers	Model Context Protocol servers

Web and news search run inside the Backend API (Serper.dev primary, Brave Search fallback) and have no dedicated port or local container.

Makefile Commands

Command	Description
`make dev`	Start all services and infrastructure
`make down`	Stop all services and infrastructure
`make status`	Show running status of all containers and processes
`make logs`	Tail logs from all services
`make restart-backend`	Restart only the backend API
`make restart-frontend`	Restart only the frontend
`make restart-crawler`	Restart only the crawler API
`make restart-processor`	Restart only the event processor
`make dev-backend`	Start only the backend API and its dependencies (search runs in-process)
`make dev-frontend`	Start only the frontend
`make dev-crawler`	Start only the crawler API and worker
`make dev-event-processor`	Start only the event processor

Testing Event Processing

The event processor includes built-in test endpoints for replaying sample disaster events without connecting to live data sources.

List Available Test Files

curl http://localhost:5606/test/files

["myanmar-earthquake.json", "turkey-flood.json", "japan-tsunami.json"]

Preview Events in a Test File

curl http://localhost:5606/test/files/myanmar-earthquake.json/events

This returns the parsed events from the file without ingesting them, allowing you to inspect the data before processing.

Ingest a Single Test Event

curl -X POST http://localhost:5606/test/files/myanmar-earthquake.json/events/0

This sends event at index 0 from the test file through the full ingestion pipeline, including deduplication, normalization, and database upsert.

Enable Live Polling

By default, live polling from GDACS and USGS is disabled in development. To enable it:

GDACS_ENABLED=true USGS_ENABLED=true make dev-event-processor

This starts the event processor with active polling schedules. Events will be fetched from live feeds and processed through the full pipeline.

Database Migrations

The backend API uses Alembic for database migrations:

cd tg-backend-api

# Apply all pending migrations
poetry run alembic upgrade head

# Roll back the last migration
poetry run alembic downgrade -1

# Generate a new migration from model changes
poetry run alembic revision --autogenerate -m "description"

Verifying the Setup

After make dev, verify that all services are healthy:

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

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

# Crawler API
curl http://localhost:5603/v1/health

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

# Frontend
curl http://localhost:4000

All health endpoints should return a 200 status. If any service fails to start, check the logs with make logs or inspect individual service logs in the terminal output.

On this page