Project Hephaestus: Quickstart

Getting Started with Docker Compose (Still working on this)

Follow these steps to spin up the entire Hephaestus stack locally using Docker Compose.

Prerequisites

• Docker Desktop installed and running.
• Docker Compose installed (included with Docker Desktop).
• NVIDIA drivers and the NVIDIA Container Toolkit (if you plan to use GPU acceleration).

1. Setup Environment Variables

First, create a .env file from the example template:

cp .env.example .env        # macOS / Linux
copy .env.example .env       # Windows (cmd / PowerShell)

Open the .env file and set the required variables (like SEARXNG_SECRET).

2. Build and Start the Containers

Run the following command from the root of the project to build the images and start the services in detached mode:

docker compose up --build -d

This will spin up:

• Next.js Frontend (Port: 3000)
• Python/LangGraph Backend (Port: 8000)
• Redis
• MongoDB
• SearXNG (Port: 8080)

3. Access the Application

Once the containers are running, you can access the frontend UI at:

http://localhost:3000

Stopping the Services

To stop the containers and remove the networks, run:

docker compose down

Note: Data for MongoDB and Redis is stored in persistent volumes. To completely wipe the database data, you can run docker compose down -v.

Local Native Development (Without Docker) (Recommended)

To save disk space and enable native hot-reloading during development, you can run the frontend and backend natively on your local machine, while only running the supporting services in Docker.

Prerequisites

• Docker Desktop — required for Redis, MongoDB, and SearXNG.
• Python 3.11+
• uv — Python package manager (pip install uv)
• Node.js 18+
• pnpm (npm install -g pnpm) — or use npm as a fallback

1. Run Supporting Services

Spin up only the databases and SearXNG via Docker:

docker compose up -d redis mongodb searxng

⚠️ Docker is required for this step. Redis, MongoDB, and SearXNG are real infrastructure services — there is no standalone alternative. If Docker Desktop is not installed, install it first before proceeding.

2. Setup Environment Variables

cp .env.example .env        # macOS / Linux
copy .env.example .env       # Windows (cmd / PowerShell)

3. Backend (Python/FastAPI)

The backend dependencies are declared in backend/pyproject.toml, so you only need to install from that file:

cd backend
uv sync
uv run python main.py

Windows note: If you prefer activating the virtual environment manually, run .venv\Scripts\activate after uv sync. On macOS/Linux, use source .venv/bin/activate.

The backend API and Swagger docs will be available at:

• API: http://localhost:8000
• Docs: http://localhost:8000/docs

4. Frontend (Next.js)

Using pnpm for efficient package management (or npm as a fallback):

cd frontend
pnpm install        # or: npm install
pnpm dev            # or: npm run dev

5. Open the App

Once both apps are running, open the frontend at:

http://localhost:3000