Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicolas344/Sentinel-SoftServe/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through standing up a fully functional Sentinel instance on your local machine. By the end you will have the entire observability stack, the FastAPI backend, and the React dashboard running together — and you will trigger your first AI-driven incident triage with a single Docker command.
Make sure you have Docker Desktop running, Node.js 20+, Python 3.9+, a Supabase project, and an OpenAI API key before you start. See the Introduction for the full prerequisites list.
1

Clone the repository

Pull the source code and enter the project directory.
git clone https://github.com/nicolas344/Sentinel-SoftServe.git
cd Sentinel-SoftServe
2

Configure environment variables

Sentinel needs two .env files — one for the backend and one for the frontend. Create both before starting any services.Backend — create Backend/.env:
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key
SUPABASE_JWT_SECRET=your-jwt-secret

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=http://localhost:3001

LOKI_URL=http://localhost:3100
CHROMA_HOST=http://localhost:8001
PROMETHEUS_URL=http://localhost:9090

# Shared secret for the /api/alerts webhook.
# Must match http_config.authorization.credentials in alertmanager/alertmanager.yml.
# Omit only in development — leaves the webhook open.
ALERT_WEBHOOK_SECRET=sentinel-webhook-secret-change-me

# Optional: comma-separated allowed CORS origins.
# Production example: CORS_ORIGINS=https://sentinel-softserve-1.onrender.com
# CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
Frontend — create Frontend/.env.local:
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
VITE_API_URL=http://localhost:8000
3

Apply the database schema

The Supabase schema lives in supabase/migrations/. For a brand-new Supabase project, open the SQL Editor in the Supabase dashboard and run each migration file in order:
supabase/migrations/0001_initial_schema.sql
supabase/migrations/0002_production_hardening.sql
If you are joining an existing team project that already has the baseline schema, only apply 0002_production_hardening.sql. Alternatively, use supabase db push from the Supabase CLI if your environment is configured.
4

Start the infrastructure stack

Docker Compose starts Prometheus, Alertmanager, Loki, Promtail, Grafana, LangFuse, and ChromaDB in the background with a single command.
docker compose up -d
Wait about 30 seconds for all containers to become healthy before proceeding.
5

Install backend dependencies

Create a Python virtual environment and install the FastAPI application’s requirements.
cd Backend
python3 -m venv env
source env/bin/activate      # Windows: env\Scripts\activate
pip install -r requirements.txt
6

Seed ChromaDB with runbooks (one-time only)

Sentinel’s RAG pipeline needs runbook documents loaded into ChromaDB before the agent can retrieve relevant remediation context. Run each seed script once with your virtual environment active.
cd Backend
source env/bin/activate

python scripts/seed_chromadb.py            # Docker runbooks
python scripts/seed_postgres_runbooks.py   # PostgreSQL runbooks
python scripts/seed_podman_runbooks.py     # Podman runbooks
python scripts/seed_kubernetes_runbooks.py # Kubernetes runbooks
Each script populates a dedicated runbooks-{domain} collection in ChromaDB. You only need to run these once; re-running them on an existing instance will upsert without duplication.
7

Start the backend

Launch the FastAPI application with hot-reload enabled. Keep this terminal open.
cd Backend
source env/bin/activate
uvicorn main:app --reload --host 0.0.0.0
The backend is ready at http://localhost:8000. Interactive Swagger docs are at http://localhost:8000/docs.
8

Start the frontend

In a new terminal, install Node dependencies and start the Vite dev server.
cd Frontend
npm install   # first time only
npm run dev
The React dashboard opens at http://localhost:5173. Sign in with the Supabase email and password you configured for your project.
9

Simulate your first incident

With everything running, trigger a realistic container crash to watch Sentinel’s full triage pipeline in action.
docker run -d --name demo-crash alpine sh -c "
  echo '[INFO] Starting service on port 8080'
  echo '[INFO] Connecting to postgres://db:5432...'
  sleep 5
  echo '[ERROR] Connection pool exhausted after 3 retries'
  sleep 5
  echo '[FATAL] Could not recover connection. Shutting down.'
  exit 1
"
Sentinel will automatically detect the crash within 20–30 seconds. It will fetch the container logs from Loki, classify the incident type with GPT-4o-mini, route to the DockerAgent for investigation, and surface a proposed corrective action in the dashboard for your approval.
Once the incident appears in the dashboard you can:
  • Read the agent’s full reasoning and tool call history in the Agent Reasoning panel.
  • Approve the proposed action (e.g. docker restart demo-crash) to trigger Lab 4 — Action & Verification.
  • Reject or Postpone if you want to handle remediation manually.
  • After resolution, generate a Post-Mortem report directly from the incident detail view.

​
Service URLs

Once the full stack is running, all services are accessible at the following local addresses.
ServiceURLCredentials
Sentinel Dashboardhttp://localhost:5173Supabase email/password
Backend APIhttp://localhost:8000—
API Docs (Swagger)http://localhost:8000/docs—
Grafanahttp://localhost:3000admin / sentinel123
Prometheushttp://localhost:9090—
Alertmanagerhttp://localhost:9093—
LangFusehttp://localhost:3001local account
ChromaDBhttp://localhost:8001—

Build docs developers (and LLMs) love

Get started for freeTalk to us