Installation Guide

Installation Guide

Get EdgeQuake running on your machine in 5 minutes

---

Prerequisites Checklist

Before installing, ensure you have:

Requirement	Version	Check Command	Purpose
Rust	1.95.x	rustc --version	Build backend with the pinned toolchain
Cargo	via rustup	cargo --version	Package manager and workspace tooling
Docker	24+	docker --version	Recommended path for required PostgreSQL
Node.js	20+	node --version	WebUI and Playwright
pnpm	10+	pnpm --version	Frontend package manager

---

Quick Install Decision Tree

                     ┌─────────────────────┐
                     │ What's your goal?   │
                     └──────────┬──────────┘
                                │
              ┌─────────────────┼─────────────────┐
              │                 │                 │
              ▼                 ▼                 ▼
       ┌──────────┐      ┌──────────┐      ┌──────────┐
       │ Try it   │      │ Develop  │      │ Deploy   │
       │ quickly  │      │ locally  │      │ to prod  │
       └────┬─────┘      └────┬─────┘      └────┬─────┘
            │                 │                 │
            ▼                 ▼                 ▼
       make dev         make dev-bg       Docker Compose
       (interactive)    (background)      (see Deployment)

---

Installation Options

Option 1: Full Stack with Make (Recommended)

# Clone the repository
git clone https://github.com/raphaelmansuy/edgequake.git
cd edgequake

# Start everything (PostgreSQL + Backend + Frontend)
make dev

What happens:

1. Ensures PostgreSQL is reachable on port 5432
2. Runs database migrations
3. Builds and starts the Rust backend on port 8080
4. Starts the Next.js frontend, preferring port 3001 and automatically shifting if that port is already in use

Verify:

# In a new terminal
curl http://localhost:8080/health
# Expected: JSON containing "status":"healthy"

# Open WebUI (default local Make-based port)
open <http://localhost:3001>

If another stack is already using 3001, run make status to see the exact frontend URL that was selected.

---

Option 2: Backend Only (For API Development)

# Clone and enter
git clone https://github.com/raphaelmansuy/edgequake.git
cd edgequake

# Start backend with PostgreSQL (required since v0.4.0)
make backend-bg

Note: Starting with v0.4.0, DATABASE_URL is required for all server modes. In-memory storage was removed to ensure reliable, production-grade behavior. Use the Docker-based PostgreSQL setup above (make dev) for the fastest path.

Verify:

curl http://localhost:8080/health

---

Option 3: Build from Source

# Clone
git clone https://github.com/raphaelmansuy/edgequake.git
cd edgequake

# Build release binary
cd edgequake
cargo build --release

# Binary location
ls target/release/edgequake

# Run directly (PostgreSQL is required)
export DATABASE_URL="postgresql://postgres:edgequake@localhost:5432/edgequake"
./target/release/edgequake

---

Option 4: Development Mode (Watch + Hot Reload)

Principle: prefer explicit health checks and the repository-pinned toolchain over ad-hoc local variations. That keeps local behavior consistent with CI.

# Terminal 1: Start PostgreSQL
make db-start

# Terminal 2: Run backend with cargo-watch
cd edgequake
cargo watch -x run

# Terminal 3: Run frontend with hot reload
cd edgequake_webui
pnpm dev

---

LLM Provider Configuration

EdgeQuake supports multiple LLM providers:

Ollama (Free, Local) — Default

# Install Ollama
brew install ollama  # macOS
# or: curl -fsSL https://ollama.com/install.sh | sh

# Pull models
ollama pull llama3.2
ollama pull nomic-embed-text

# Start Ollama (if not running)
ollama serve

# Start EdgeQuake (auto-detects Ollama)
make dev

OpenAI (Paid, Cloud)

# Set API key
export OPENAI_API_KEY="sk-your-key"

# Start EdgeQuake (auto-selects OpenAI when key is present)
make dev

Provider Switching at Runtime

Once running, you can switch providers via API:

# Check current provider
curl http://localhost:8080/api/v1/config | jq .llm_provider

# Provider is auto-selected based on OPENAI_API_KEY

---

Storage Configuration

EdgeQuake uses PostgreSQL as its storage backend for all modes (since v0.4.0):

┌─────────────────────────────────────────────────────────────┐
│                     Storage (PostgreSQL)                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│         ┌─────────────────────────────────────┐            │
│         │          PostgreSQL 15+              │            │
│         │                                     │            │
│         │  ┌──────────┐  ┌──────────────────┐ │            │
│         │  │ pgvector  │  │   Apache AGE     │ │            │
│         │  │ (vectors) │  │   (graph DB)     │ │            │
│         │  └──────────┘  └──────────────────┘ │            │
│         │                                     │            │
│         └─────────────────────────────────────┘            │
│                                                             │
│  DATABASE_URL required for all server modes.               │
│  Use Docker for the easiest PostgreSQL setup.              │
└─────────────────────────────────────────────────────────────┘

PostgreSQL Setup

# Using Docker (recommended)
docker run -d \
  --name edgequake-postgres \
  -e POSTGRES_PASSWORD=edgequake \
  -e POSTGRES_DB=edgequake \
  -p 5432:5432 \
  ghcr.io/raphaelmansuy/edgequake-postgres:latest

# Set connection string
export DATABASE_URL="postgresql://postgres:edgequake@localhost:5432/edgequake"

# Run migrations
cd edgequake && sqlx database setup

---

Verification Checklist

Run these commands to verify your installation:

# 1. Confirm the pinned compiler is active
cd edgequake
cargo --version
rustc --version

# 2. Check backend health
curl -s http://localhost:8080/health | jq
# ✅ Expected: JSON containing "status":"healthy" and "storage_mode":"postgresql"

# 3. Check API docs
curl -s http://localhost:8080/api-docs/openapi.json | jq .info.title
# ✅ Expected: "EdgeQuake API"

# 4. Check Ollama if using the local provider
curl -s http://localhost:11434/api/tags | jq

# 5. Let the repo verify itself
cargo fmt --all --check
cargo clippy --workspace --lib -- -D warnings
cargo test --workspace --lib --no-fail-fast

No-flake local workflow

For the most reproducible local setup:

cd edgequake
rustup show active-toolchain
make status

If PostgreSQL is unavailable, EdgeQuake now exits with a clear startup error instead of crashing later in a harder-to-debug state.

---

Troubleshooting

Docker Issues

# Problem: Docker not running
docker info
# Solution: Start Docker Desktop or systemctl start docker

# Problem: Port 5432 in use
lsof -i :5432
# Solution: Stop conflicting service or use different port

Rust Build Issues

# Problem: Rust version too old
rustup update stable

# Problem: Missing dependencies on Linux
sudo apt-get install pkg-config libssl-dev libpq-dev

# Problem: Slow compilation
# Solution: Use faster linker
# In .cargo/config.toml:
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]

LLM Issues

# Problem: Ollama not responding
ollama serve  # Start if not running
ollama list   # Check available models

# Problem: OpenAI rate limit
# Solution: Check your API usage at platform.openai.com

---

Next Steps

Now that EdgeQuake is running:

1. Quick Start — Ingest your first document
2. Architecture Overview — Understand the system
3. API Reference — Explore endpoints

---

System Requirements

Component	Minimum	Recommended
RAM	4 GB	16 GB
CPU	2 cores	8 cores
Disk	10 GB	50 GB
OS	Linux, macOS, Windows (WSL2)	Linux, macOS