Kit de Démarrage Développeur¶

Ce guide aide les développeurs à configurer un environnement AKKO local, construire des images personnalisées, ajouter des services et exécuter la suite de tests.

Configuration Locale (k3d + Helm)¶

Prérequis¶

Docker Desktop avec au moins 16 Go de RAM alloués
k3d (Kubernetes léger dans Docker)
Helm 3.x
kubectl
macOS ARM ou Linux x86_64

Démarrage Rapide¶

# 1. Créer le cluster k3d
bash helm/scripts/k3d-create.sh

# 2. Construire toutes les images personnalisées
bash helm/scripts/build-images.sh

# 3. Déployer AKKO
bash helm/scripts/deploy.sh

Le script deploy.sh gère tout : création du cluster, construction des images, installation Helm avec les valeurs de dev et import du realm Keycloak.

Déploiement Manuel¶

Si vous préférez un contrôle étape par étape :

# Créer le cluster k3d
k3d cluster create akko --servers 1 --agents 2 \
  --port "443:443@loadbalancer" --port "80:80@loadbalancer"

# Construire et importer les images personnalisées
bash helm/scripts/build-images.sh

# Installation Helm
helm install akko helm/akko/ \
  -f helm/examples/values-dev.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-akko-k3d.json

Valeurs de Dev¶

Le fichier helm/examples/values-dev.yaml contient les surcharges spécifiques au développement : limites de ressources réduites, journalisation de debug et classes de stockage locales.

Construction des Images Personnalisées¶

AKKO utilise 5 images Docker personnalisées, toutes taguées 2026.03 :

Image	Dockerfile	Description
`akko-jupyterhub`	`docker/jupyterhub/Dockerfile`	Image du hub
`akko-notebook`	`docker/jupyterhub/Dockerfile.notebook`	Notebook utilisateur (Python, R, Julia, Quarto, code-server)
`akko-spark`	`docker/spark/Dockerfile`	Spark avec JARs Iceberg + AWS
`akko-postgres`	`docker/postgres/Dockerfile`	PostgreSQL avec PostGIS + pgvector
`akko-cockpit`	`branding/cockpit/Dockerfile`	Portail avec proxys de santé

Construire toutes les images d'un coup :

bash helm/scripts/build-images.sh

Construire une seule image :

docker build -t akko-notebook:2026.03 -f docker/jupyterhub/Dockerfile.notebook .
k3d image import akko-notebook:2026.03 -c akko

Pas de tags :latest

Toutes les images doivent utiliser des tags de version épinglés (ex: 2026.03). Le tag :latest est mutable et casse la reproductibilité.

Ajouter un Nouveau Service¶

AKKO dispose d'une checklist stricte en 15 étapes pour ajouter un service. Cela garantit l'intégration complète avec l'authentification, le monitoring, le catalogue et la documentation.

Consultez la checklist complète dans Ajouter un service. Étapes clés :

Créer un sous-chart Helm dans helm/akko/charts/
Ajouter la dépendance dans helm/akko/Chart.yaml
Ajouter les valeurs dans helm/akko/values.yaml et helm/examples/values-dev.yaml
Enregistrer le client OAuth dans keycloak/realm-akko.json
Ajouter la carte Cockpit (HTML + health check + proxy nginx)
Créer les pages de documentation EN + FR
Mettre à jour la navigation de docs/mkdocs.yml
Mettre à jour le nombre de services dans le README

Toutes les étapes dans le même commit

La CI vérifie que les changements de service incluent les mises à jour de documentation. Un PR sans pages de doc échouera.

Exécution des Tests¶

AKKO dispose de 184 tests répartis en 12 catégories.

Suite de Tests Complète¶

bash tests/run-all.sh

Durée estimée : environ 45 minutes pour la suite complète.

Validation Rapide¶

bash tests/run-all.sh --fast

Durée estimée : environ 10 minutes. Couvre les health checks, l'authentification et les tests de données de base.

Catégories de Tests¶

Catégorie	Outil	Ce qui est testé
Health	Shell	Tous les 33+ endpoints de services répondent
Auth	pytest	Flux SSO Keycloak, échange de tokens
RBAC	pytest	Accès basé sur les rôles à travers les services
Theme	Playwright	Branding Keycloak + JupyterHub
Data	pytest	Opérations Spark, Trino, tables Iceberg
Notebooks	Shell	Tous les notebooks de démo s'exécutent sans erreur
Dashboards	Playwright	Rendu des dashboards Superset
DAGs	pytest	Parsing et exécution des DAGs Airflow
MLflow	pytest	Suivi d'expériences, registre de modèles
OPA	pytest	Application des politiques de requêtes Trino
OpenMetadata	pytest	Ingestion du catalogue, lignage
Monitoring	Shell	Cibles Prometheus, dashboards Grafana

Tests Helm¶

helm test akko

Exécute les tests in-cluster définis dans helm/akko/charts/*/templates/tests/.

Règles de Contribution¶

Stratégie de Branches¶

main -- prêt pour la production, protégé
feature/<nom> -- branches de fonctionnalités
fix/<nom> -- branches de correctifs

Conventions de Commit¶

Utiliser des messages de commit descriptifs
Inclure les mises à jour de documentation dans le même commit que le code
Référencer les numéros d'issues quand applicable

Style de Code¶

YAML : indentation 2 espaces
Python : suivre PEP 8, utiliser les f-strings
Shell : scripts compatibles shellcheck
Tout le code et les configs en anglais -- commentaires, noms de variables, noms de tables

Checklist de Pull Request¶

[ ] Tous les tests passent (bash tests/run-all.sh --fast)
[ ] Le lint Helm passe (helm lint helm/akko/)
[ ] Documentation EN + FR mise à jour
[ ] Aucun tag :latest introduit
[ ] Aucun secret ou fichier .env committé
[ ] Nombre de services exact dans le README

Principes d'Architecture¶

Souveraineté d'abord -- tout fonctionne hors ligne, on-prem, air-gapped
Kubernetes-natif -- portable sur k3d, k3s, EKS, GKE, AKS, OpenShift
Init idempotent -- tous les jobs d'initialisation sont sûrs à ré-exécuter
Deux instances PostgreSQL -- ne jamais mélanger données infra et données métier