Open BPMN - Guide Complet Docker ou Kubernetes

Déploiement local de Open BPMN avec 2 alternatives: Docker Compose ou Kubernetes.

Objectif

Ce dépôt permet de lancer l'application Open BPMN en local avec:

• Docker Compose (le plus simple pour démarrer vite)
• Kubernetes (environnement plus proche de la prod)

Choisir Ton Mode

• Utilise Docker Compose si tu veux démarrer en 1 commande.
• Utilise Kubernetes si tu veux déployer via manifests (k8s/).

Kubernetes A-T-Il Besoin De Docker ?

• Non, Kubernetes n'a pas besoin de Docker pour fonctionner.
• Kubernetes a besoin d'un runtime de conteneurs compatible CRI (souvent containerd ou CRI-O).
• Oui dans certains setups locaux:
  • Docker Desktop + Kubernetes: Docker Desktop est nécessaire.
  • Minikube/k3d avec driver Docker: Docker est nécessaire comme moteur local.
• Non dans d'autres setups:
  • Cluster managé (EKS/GKE/AKS) ou cluster bare-metal avec containerd.

Dépendances Et Prérequis

Prérequis Communs

• Git
• accès terminal
• port local 3000 disponible

Option Docker Compose

• Docker Desktop (macOS/Windows) ou Docker Engine (Linux)
• Docker Compose v2 (docker compose)

Vérification:

docker --version
docker compose version

Option Kubernetes

• kubectl
• cluster Kubernetes actif
• runtime de conteneurs déjà fourni par le cluster (généralement containerd)

Vérification:

kubectl version --client
kubectl config get-contexts
kubectl config current-context
kubectl cluster-info

Option Python (si tu utilises aussi le code Python du repo)

• Python >= 3.13
• uv

Installer les dépendances Python du projet:

uv sync

Notions Essentielles

Docker - Bases À Connaître

• Image: modèle immuable utilisé pour créer des conteneurs.
• Conteneur: instance en exécution d'une image.
• Registry: dépôt d'images (ex: Docker Hub).
• Port mapping: exposition d'un port conteneur vers l'hôte (ex: 3000:3000).
• Volume: persistance des données hors cycle de vie du conteneur.
• Docker Compose: orchestration locale multi-services via YAML.

Kubernetes - Bases À Connaître

• Cluster: ensemble de nœuds pilotés par un plan de contrôle.
• Namespace: isolation logique des ressources (open-bpmn).
• Pod: plus petite unité déployable (1+ conteneurs).
• Deployment: gestion déclarative des pods (réplicas, rollout, restart).
• Service: point d'accès réseau stable vers les pods.
• Port-forward: tunnel local vers un Service/Pod sans exposition externe.
• Manifests YAML: définition déclarative de l'état désiré (k8s/*.yaml).

Avant De Lancer Les Commandes

1. Ouvre un terminal dans le projet.

cd /Users/rgctechfi/Projects/bpmn

2. Vérifie que le port 3000 n'est pas déjà pris.

lsof -i :3000

3. Choisis une seule méthode d'exécution à la fois:

• Docker Compose
• Kubernetes

4. Si Kubernetes est choisi, confirme que le contexte est configuré (sinon erreur localhost:8080 refused).

Installation Rapide Des Outils (macOS)

Docker

brew install --cask docker
open -a Docker

Attends que Docker Desktop soit "running", puis:

docker --version
docker compose version

kubectl

brew install kubectl
kubectl version --client

Pour Docker Desktop Kubernetes:

• Ouvre Docker Desktop
• Settings > Kubernetes > Enable Kubernetes > Apply & Restart
• Puis vérifie:

kubectl config get-contexts
kubectl config use-context docker-desktop
kubectl cluster-info

Lancer L'application - Docker Compose

Démarrage

docker compose up -d

Vérification

docker compose ps
docker compose logs --tail=100

Logs en continu

docker compose logs -f

Redémarrage

docker compose restart

Arrêt propre

docker compose down

Mise à jour de l'image

docker compose pull
docker compose up -d

Accès application:

• http://localhost:3000

Lancer L'application - Kubernetes

Déploiement

kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

Vérification du rollout

kubectl -n open-bpmn rollout status deployment/modeler-app
kubectl -n open-bpmn get pods
kubectl -n open-bpmn get svc

Accès local (port-forward)

kubectl -n open-bpmn port-forward svc/modeler-app 3000:3000

Accès application:

• http://localhost:3000

Logs

kubectl -n open-bpmn logs deployment/modeler-app --tail=100
kubectl -n open-bpmn logs deployment/modeler-app -f

Redémarrage du déploiement

kubectl -n open-bpmn rollout restart deployment/modeler-app
kubectl -n open-bpmn rollout status deployment/modeler-app

Suppression du déploiement

kubectl delete -f k8s/service.yaml
kubectl delete -f k8s/deployment.yaml
kubectl delete -f k8s/namespace.yaml

Dépannage (Erreurs Fréquentes)

Erreur Docker: command not found: docker

Docker n'est pas installé ou n'est pas démarré.

brew install --cask docker
open -a Docker

Erreur Kubernetes: The connection to the server localhost:8080 was refused

Aucun contexte Kubernetes actif.

kubectl config get-contexts
kubectl config current-context
kubectl config use-context docker-desktop
kubectl cluster-info

Erreur port occupé

Le port 3000 est déjà utilisé.

lsof -i :3000

Puis change le port exposé:

• Docker Compose: modifier docker-compose.yml (ex: 3001:3000)
• Kubernetes: utiliser un autre port local dans le port-forward (ex: 3001:3000)

Structure Du Repo

.
├── README.md
├── docker-compose.yml
├── k8s/
│   ├── namespace.yaml
│   ├── deployment.yaml
│   └── service.yaml
├── ressources/
│   └── pictures/
│       └── ui.png
├── main.py
├── pyproject.toml
└── uv.lock

Fichiers Clés

• Docker Compose: docker-compose.yml
• Kubernetes: k8s/namespace.yaml, k8s/deployment.yaml, k8s/service.yaml
• Dépendances Python: pyproject.toml