Quick Start¶

Get LogSys running in 5 minutes.

1. Clone Repository¶

git clone https://github.com/elhamrit-stack/AlertOps
cd LogSys

2. Configure Environment¶

cp .env.example .env
# Edit .env if needed (defaults work for local dev)

3. Start Platform¶

docker compose up -d

This starts 8 services (the simulator is opt-in, see below): - kafka-broker (KRaft, no Zookeeper) - kafka-init (creates topics) - postgres (16-alpine) - redis (7-alpine) - vector (HTTP→Kafka router) - api (FastAPI + Alembic migrations) - collectors (Jira, Prometheus, Azure DevOps, Webhooks) - consumer-pipeline (Parse → Normalize → Dedup → ML → Storage) - ml-service (RoBERTa inference on :8001)

Optional simulator (synthetic data for demos):

docker compose --profile demo up -d

4. Verify Startup¶

# Watch pipeline logs (should show batches processed)
docker compose logs -f consumer-pipeline

# Check API health
curl http://localhost:8000/health
# {"status":"ok"}

# Check all containers healthy
docker compose ps

5. Access Dashboard¶

Open http://localhost:5173 and login with: - Email: admin@alertops.com - Password: Admin123!

6. Send Test Data¶

# Option A: Send a real webhook via the API (needs a login token first)
curl -X POST http://localhost:8000/api/webhooks/<your_secret> \
  -H "Content-Type: application/json" \
  -d '{"message": "ERROR: Database connection failed", "severity": "error", "source": "demo"}'

# Option B: POST directly to Vector
curl -X POST http://localhost:8686 \
  -H "Content-Type: text/plain" \
  -d "ERROR: Database connection failed at 2026-01-15 10:30:00"

# Option C: Generate a platform webhook from the dashboard (Sources → Générer un webhook)
# then send events to the returned URL.

7. Explore¶

Page	What to See
Monitoring	Real-time log table with filters, severity/priority badges
AI Insights	RCA, anomalies, recommended actions, MTTD/MTTR
Analytics	Templates, time-series charts, severity breakdown
Dashboard	KPIs, sparklines, health score, top errors

Development Workflow (no hot-reload)¶

docker-compose.override.yml is intentionally not used (a uvicorn --reload override skips Alembic migrations, which caused missing-schema errors). The api container starts via start.sh: it runs alembic upgrade head then launches uvicorn without reload.

After editing backend code:

# Restart the API to pick up code changes
docker compose restart api

# After pulling new migrations, apply them explicitly (if api didn't restart)
docker compose exec api alembic upgrade head

# After changing requirements.txt / Dockerfile, rebuild the image
docker compose build api

Optional hot-reload in dev (not required): run the API outside Docker:
cd backend && pip install -r requirements.txt && uvicorn app.main:app --reload
Migrations are still run manually: docker compose exec api alembic upgrade head.

Common Issues¶

Problem	Solution
`alembic upgrade head` fails	Check `docker compose logs postgres` — wait for healthcheck
Port 8000/5432/6379 in use	Change ports in `.env` (`API_PORT`, `POSTGRES_PORT`, `REDIS_PORT`)
Permission denied on docker.sock	Add user to `docker` group or use `sudo`
No data in dashboard	Check `docker compose logs consumer-pipeline` for errors; verify Kafka topics exist
Column missing / "does not exist" in API logs	Migrations not applied → `docker compose exec api alembic upgrade head`
Backend edits not visible after change	The API has no hot-reload → `docker compose restart api`

Stop & Cleanup¶

# Stop services (keep data)
docker compose down

# Stop and remove ALL data (volumes)
docker compose down -v