Quickstart

Run Filomena locally with durable PostgreSQL state and send one Grafana alert through the complete ingestion path.

Requirements

• Docker with Compose
• Git
• An OpenAI-compatible chat-completions endpoint

Start the stack

Clone the repository and create the local environment file:

git clone https://github.com/bfxavier/filomena.git
cd filomena
cp .env.example .env

Set at least these values in .env:

FILOMENA_WEBHOOK_TOKEN=replace-me
FILOMENA_ANALYSIS_API_KEY=replace-me
FILOMENA_MODEL=gpt-4.1-mini

Start Filomena, PostgreSQL and VictoriaMetrics:

set -a
. ./.env
set +a
docker compose up --build -d

The default stack stores state in PostgreSQL. SQLite and ClickHouse remain available adapters.

For a lightweight SQLite stack, set:

FILOMENA_STATE_PROVIDER=sqlite
FILOMENA_STATE_CONNECTION_STRING=Data Source=/var/lib/filomena/filomena.db

Send the first alert

Use the included Grafana payload:

curl -fsS \
  -H "Authorization: Bearer $FILOMENA_WEBHOOK_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @examples/grafana-alert.json \
  http://localhost:8080/v1/webhooks/grafana

The endpoint returns 202 Accepted with accepted, duplicate and deferred counts. Follow processing in the application logs:

docker compose logs -f filomena

Check readiness and Prometheus metrics:

curl -fsS http://localhost:8080/readyz
curl -fsS http://localhost:8080/metrics

Read the investigation

Local development falls back to the webhook token when a dedicated read token is not set:

curl -fsS \
  -H "Authorization: Bearer $FILOMENA_WEBHOOK_TOKEN" \
  'http://localhost:8080/v1/runs?limit=10'

Use the returned run ID to retrieve its alert, evidence, diagnosis and feedback:

curl -fsS \
  -H "Authorization: Bearer $FILOMENA_WEBHOOK_TOKEN" \
  http://localhost:8080/v1/runs/RUN_ID

Add ClickHouse

Set the ClickHouse provider variables in .env, then start the optional profile:

docker compose --profile clickhouse up --build -d

ClickHouse can provide Filomena state, log evidence, or both. They are separate configuration choices.

Move to Kubernetes

The installer creates separate scoped tokens, installs the Helm chart and waits for readiness:

FILOMENA_ANALYSIS_API_KEY=... \
FILOMENA_STATE_CONNECTION_STRING='Host=postgres.example;Port=5432;Database=filomena;Username=filomena;Password=...' \
FILOMENA_METRICS_BASE_URL=http://prometheus-operated.monitoring.svc:9090 \
./deploy/install.sh

Read the configuration before enabling evidence providers and the production operations guide before using the release with real alerts.