Getting Started

This guide walks you through running Ephor for the first time and setting up a local development environment.

Prerequisites

• Docker 24 or later
• Docker Compose v2 or later

For local development you will also need:

• JDK 21 (for the API)
• Node.js 22 or later (for the dashboard)

Quick Start

git clone https://github.com/holbein-io/ephor.git
cd ephor
docker compose up --build

This starts:

• Dashboard at http://localhost:3000
• API at http://localhost:8080/api/v1
• PostgreSQL on port 5432

Authentication is disabled by default in the Docker Compose configuration. A development user with Admin privileges is injected automatically so you can explore the full dashboard immediately.

Local Development

API (Spring Boot)

Start only the database, then run the API with hot-reload:

# Start PostgreSQL
docker compose up postgres -d

# Run the API
SPRING_PROFILES_ACTIVE=local ./gradlew :api:bootRun

The API starts on port 8080. The local profile enables Swagger UI at http://localhost:8080/api/v1/swagger-ui/index.html.

Dashboard (React / Vite)

cd dashboard/app
npm install
npm run dev

The dashboard starts on port 3000 and proxies /api requests to http://localhost:8080.

Running Tests

# API tests
./gradlew :api:test

# Dashboard tests
cd dashboard/app && npm test

Next Steps

• Authentication -- configure OAuth2 with Keycloak, GitHub, or another provider
• Kubernetes Deployment -- deploy Ephor to a cluster with Helm
• Vulnerability Scanning -- deploy the scanner agent to discover and scan workloads