Cette page s’adresse aux équipes qui exploitent leur propre instance de Jichio.
Si vous utilisez la version hébergée, vous n’avez rien à configurer ici.
Architecture
Navigateur (SDK) Votre serveur
│ POST /v1/events │ /v1/public/*
▼ ▼
┌───────────────────── API (FastAPI) ─────────────────────┐
│ ingestion · lecture dashboard · API publique · jobs │
└──────┬──────────┬───────────┬───────────┬───────────────┘
▼ ▼ ▼ ▼
ClickHouse Postgres Redis MinIO (S3)
événements comptes, limites avatars, captures
projets, de débit de heatmap
objectifs…
▲
│ lecture via l'API uniquement
Dashboard (Next.js)
| Service | Rôle |
|---|---|
| API (Python, FastAPI) | Seul composant exposé. Ingestion, lecture du dashboard, API publique, webhooks, tâches planifiées |
| ClickHouse | Événements bruts et agrégations. Table ReplacingMergeTree dédoublonnée par event_id |
| Postgres | Organisations, projets, environnements, clés, objectifs, tunnels, insights, notifications |
| Redis | Limites de débit (repli en mémoire si absent) |
| MinIO | Stockage S3 : avatars et captures de heatmap (préfixe privé heatmap-captures/) |
| Chromium (Playwright) | Captures d’écran des pages pour les heatmaps |
| Dashboard (Next.js) | Interface. Ne parle jamais directement aux bases : uniquement à l’API |
Variables d’environnement de l’API
Indispensables
| Variable | Rôle |
|---|---|
ENVIRONMENT | production désactive /docs et /openapi.json et impose des secrets forts |
POSTGRES_URL | Connexion Postgres (asyncpg) |
CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, CLICKHOUSE_DATABASE | Connexion ClickHouse |
REDIS_URL | Connexion Redis |
MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_BUCKET, MINIO_SECURE | Stockage objet |
JWT_SECRET | Signature des sessions du dashboard (32 caractères minimum hors local) |
CORS_ORIGINS | Origines autorisées pour le dashboard. * est interdit en production. L’ingestion accepte toujours toutes les origines |
INTERNAL_JOBS_SECRET | Secret des tâches planifiées. Vide : toutes les tâches répondent 401 |
TRUSTED_PROXY_HOPS | Nombre de proxys devant l’API, pour lire la bonne IP client (défaut 1) |
Fonctionnalités optionnelles
| Variable | Fonctionnalité |
|---|---|
ANTHROPIC_API_KEY, ANTHROPIC_MODEL, LLM_MONTHLY_BUDGET_USD | Rédaction des insights. Sans clé, la tâche recommendations répond 503 |
EMAIL_ENABLED, RESEND_API_KEY, EMAIL_FROM | E-mails (codes de connexion, alertes de quota) via Resend |
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_PRO_MONTHLY, STRIPE_PRICE_TEAM_MONTHLY | Facturation |
MAXMIND_DB_PATH, MAXMIND_LICENSE_KEY | Géolocalisation. Sans base, le pays vaut unknown |
PAGESPEED_API_KEY | Audits Lab — Performance |
HEATMAP_CAPTURE_ENABLED, HEATMAP_CAPTURE_TTL_DAYS, HEATMAP_CAPTURE_TOP_PATHS, HEATMAP_CHROMIUM_SANDBOX | Captures de heatmap (défauts : activé, 7 jours, 8 pages) |
Limites
| Variable | Défaut |
|---|---|
INGEST_RATE_LIMIT_PER_KEY_PER_MINUTE | 120 |
INGEST_RATE_LIMIT_PER_IP_PER_MINUTE | 180 |
AUTH_RATE_LIMIT_PER_IP_PER_MINUTE | 20 |
AUTH_RATE_LIMIT_PER_EMAIL_PER_MINUTE | 10 |
INGEST_QUOTA_CACHE_SECONDS | 30 |
RECOMMENDATIONS_GENERATE_PER_HOUR | 3 |
PERFORMANCE_SNAPSHOT_RETENTION_DAYS | 90 |
Tâches planifiées
Aucune tâche ne tourne seule : planifiez des appelsPOST avec l’en-tête
X-Internal-Secret: <INTERNAL_JOBS_SECRET> (par exemple avec des Cron Jobs Render).
| Endpoint | Fréquence conseillée | Rôle |
|---|---|---|
/v1/internal/jobs/site-health | Toutes les 30 min | Disponibilité des sites, webhooks health.* |
/v1/internal/jobs/webhook-retries | Toutes les 5 min | Nouvelles tentatives des webhooks |
/v1/internal/jobs/recommendations | Quotidienne | Détection des signaux et rédaction des insights |
/v1/internal/jobs/notifications | Quotidienne | Notifications, résumé hebdomadaire, mesure d’impact |
/v1/internal/jobs/operational-emails | Quotidienne | E-mails de suivi interrompu, quota, inactivité |
/v1/internal/jobs/performance-snapshots | Quotidienne | Audits PageSpeed |
/v1/internal/jobs/heatmap-captures | Quotidienne | Recapture des pages les plus cliquées |
curl -X POST https://api.example.com/v1/internal/jobs/site-health \
-H "X-Internal-Secret: $INTERNAL_JOBS_SECRET"
Captures de heatmap
L’image Docker de l’API inclut Chromium. Hors Docker, installez-le :cd apps/api
uv sync
uv run playwright install chromium
Pointer le SDK vers votre instance
<AnalyticsProvider apiKey="jch_pr_…" endpoint="https://api.example.com">