02 — Installer sur votre laptop (k3d local)¶

Durée : 15 min walltime (5 min hands-on + 10 min d'attente) · Persona : engineer / admin · Voie : B

Ce chapitre fait tourner une plateforme AKKO complète sur votre laptop. Vous possédez chaque couche, aucun domaine public n'est impliqué.

Pré-requis

Docker Desktop ≥ 4.20 ou Colima ≥ 0.6 (Apple Silicon supporté).
16 Go de RAM disponibles (12 Go au minimum, mais l'ordonnancement sera tendu).
k3d ≥ 5.6 — installation : brew install k3d (macOS) ou wget -q -O - https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash.
helm ≥ 3.13 — installation : brew install helm ou votre package manager.
kubectl ≥ 1.28 — installation : brew install kubectl.
git n'importe quelle version moderne.

Vérifiez tout avec k3d version && helm version && kubectl version --client && docker version.

Étape 1 — Cloner le dépôt¶

git clone https://github.com/AKKO-p/AKKO
cd AKKO

Résultat attendu : un listing qui contient helm/, docker/, docs/, branding/.

Étape 2 — Générer la config par domaine et les secrets de dev¶

AKKO est zéro-hardcoded : chaque URL, rôle et credential est généré pour votre domaine. Choisissez un nom (nous prenons akko.local).

bash helm/scripts/generate-domain-values.sh akko.local
bash helm/scripts/generate-dev-secrets.sh

Résultat attendu : le script imprime generated helm/examples/values-domain.yaml et generated helm/examples/values-dev-secrets.yaml. Les deux fichiers sont gitignorés.

Que s'est-il passé ? Le premier script a matérialisé chaque URL de service (https://demo.akko.local, https://identity.akko.local, etc.) et un nouvel export realm. Le second a généré des mots de passe aléatoires pour chaque compte de service interne.

Étape 3 — Déployer¶

bash helm/scripts/deploy.sh

Cette commande unique :

Crée un cluster k3d nommé akko (ou réutilise un existant).
Construit localement les 16 images de conteneurs custom.
Installe le chart Helm umbrella (44 sous-charts).
Injecte le realm d'identité avec 5 comptes persona.
Injecte le catalogue de démo banking.

Résultat attendu : le script se termine par Deploy complete. Open https://demo.akko.local après environ 5 minutes (le build d'images est la partie longue au premier run).

Si deploy.sh sort avec image build failed, lancez docker system df — vous êtes peut-être à court de cache de build. Libérez avec docker system prune -f (sûr : ne supprime que les couches orphelines).

Étape 4 — Attendre que ce soit vert¶

Regardez la plateforme converger vers Ready :

kubectl get pods -n akko -w

Attendez que chaque pod soit Running ou Completed. Démarrage à froid : 3 à 5 minutes après la fin de la commande deploy.

Résultat attendu : kubectl get pods -n akko affiche 30+ pods, tous Running ou Completed. Pressez Ctrl-C pour arrêter le watch.

Quelques pods (jobs d'init, rotation de secrets) finissent en Completed — c'est un succès, pas un échec.

Étape 5 — Ajouter les entrées `/etc/hosts`¶

Les domaines locaux ont besoin d'une résolution DNS. Ajoutez ce bloc à /etc/hosts (nécessite sudo) :

127.0.0.1 demo.akko.local identity.akko.local catalog.akko.local
127.0.0.1 federation.akko.local compute.akko.local orchestrator.akko.local
127.0.0.1 lab.akko.local bi.akko.local experiments.akko.local
127.0.0.1 llm.akko.local metrics.akko.local logs.akko.local
127.0.0.1 alerts.akko.local docs.akko.local mcp.akko.local

Résultat attendu : ping demo.akko.local répond 127.0.0.1 immédiatement.

Pourquoi pas un script automatique ? Éditer /etc/hosts nécessite root, et nous ne livrons jamais un script qui demande sudo en silence. Le copier-coller est le choix par défaut de confiance.

Étape 6 — Ouvrir le cockpit¶

Ouvrez https://demo.akko.local dans votre navigateur.

La première visite déclenche un avertissement TLS car le certificat de dev est auto-signé. Acceptez-le (Chrome : « Advanced » → « Proceed »).

Résultat attendu : la page de connexion du fournisseur d'identité charge. Connectez-vous avec alice / alice123. Vous arrivez sur la Home du cockpit avec un badge violet akko-admin.

Cockpit local

Étape 7 — Vérifier que les 10 couches sont vivantes¶

Dans la Home du cockpit, scrollez jusqu'à la grille Layer health. Chaque tuile doit être verte.

# Alternative CLI — chaque endpoint santé de couche :
curl -sk https://demo.akko.local/api/health/all | jq

Résultat attendu : chaque couche retourne { "status": "ok" }. Si une couche est degraded, attendez 30 secondes et réessayez — quelques sous-charts ont besoin d'un cycle supplémentaire pour se marquer prêts.

Dépannage¶

Symptôme	Cause probable	Fix
`deploy.sh` : `Cannot connect to Docker daemon`	Docker Desktop / Colima pas démarré	Démarrer Docker Desktop, réessayer.
`deploy.sh` : `image build failed: insufficient space`	Cache de build saturé	`docker system prune -f` puis réessayer.
Navigateur : `ERR_NAME_NOT_RESOLVED`	Fichier hosts pas édité (étape 5)	Ajouter le bloc, sauvegarder, réessayer.
`kubectl get pods -n akko` montre `ImagePullBackOff`	Miroir registry k3d non configuré	`bash helm/scripts/deploy.sh` ré-exécute le setup du mirror.
`helm install` : `release already exists`	Installation précédente non terminée	`helm uninstall akko -n akko` puis relancer `deploy.sh`.
Fournisseur d'identité 504 à la première connexion	Démarrage à froid, JVM qui chauffe	Attendre 30 sec puis rafraîchir la page de login.

Référence complète : Dépannage et le runbook d'installation.

Ce que vous venez d'apprendre¶

AKKO se déploie en trois commandes sur n'importe quel laptop équipé de Docker.
Chaque URL et credential est généré depuis le domaine que vous choisissez.
Les 10 couches arrivent en ligne ensemble, observables depuis un seul dashboard.

Suivant : 03 — Première connexion et les 5 personas.