601 lines
14 KiB
Markdown
601 lines
14 KiB
Markdown
# 🚀 Guide de Déploiement AfterWork Server
|
||
|
||
## 📋 Vue d'Ensemble
|
||
|
||
Ce guide décrit le processus de déploiement de l'API AfterWork sur le VPS via `lionsctl pipeline`.
|
||
|
||
**URL de l'API** : `https://api.lions.dev/afterwork`
|
||
|
||
---
|
||
|
||
## 🔧 Prérequis
|
||
|
||
### Environnement Local
|
||
- Java 17 (JDK)
|
||
- Maven 3.9+
|
||
- Docker 20.10+
|
||
- `lionsctl` CLI installé et configuré
|
||
|
||
### Environnement Serveur
|
||
- PostgreSQL 15+
|
||
- Kubernetes cluster configuré
|
||
- Ingress Controller (nginx)
|
||
- Cert-Manager pour les certificats SSL (Let's Encrypt)
|
||
|
||
---
|
||
|
||
## 📁 Fichiers de Configuration
|
||
|
||
### 1. Variables d'Environnement Requises
|
||
|
||
Les variables suivantes doivent être définies dans Kubernetes Secrets :
|
||
|
||
```yaml
|
||
DB_HOST: postgres # Hostname du serveur PostgreSQL
|
||
DB_PORT: 5432 # Port PostgreSQL
|
||
DB_NAME: afterwork_db # Nom de la base de données
|
||
DB_USERNAME: afterwork # Utilisateur de la base de données
|
||
DB_PASSWORD: <secret> # Mot de passe (à définir dans le secret)
|
||
```
|
||
|
||
### 2. docker/Dockerfile.prod
|
||
|
||
Le fichier `docker/Dockerfile.prod` utilise une approche multi-stage :
|
||
- **Stage 1** : Build avec Maven dans une image UBI8 OpenJDK 17
|
||
- **Stage 2** : Runtime optimisé avec l'uber-jar compilé
|
||
|
||
### 3. application-prod.properties
|
||
|
||
Configuration production avec :
|
||
- Context path : `/afterwork`
|
||
- CORS : `https://afterwork.lions.dev`
|
||
- Health checks : `/q/health/ready` et `/q/health/live`
|
||
- Métriques : `/q/metrics`
|
||
|
||
---
|
||
|
||
## 🏗️ Build de l'Image Docker
|
||
|
||
### Build Local (Test)
|
||
|
||
```bash
|
||
# Build de l'image (Dockerfiles dans docker/)
|
||
docker build -f docker/Dockerfile.prod -t afterwork-api:latest .
|
||
|
||
# Test local
|
||
docker run -p 8080:8080 \
|
||
-e DB_HOST=localhost \
|
||
-e DB_PORT=5432 \
|
||
-e DB_NAME=afterwork_db \
|
||
-e DB_USERNAME=afterwork \
|
||
-e DB_PASSWORD=changeme \
|
||
afterwork-api:latest
|
||
```
|
||
|
||
### Build pour Registry
|
||
|
||
```bash
|
||
# Tag pour le registry
|
||
docker tag afterwork-api:latest registry.lions.dev/afterwork-api:1.0.0
|
||
docker tag afterwork-api:latest registry.lions.dev/afterwork-api:latest
|
||
|
||
# Push vers le registry
|
||
docker push registry.lions.dev/afterwork-api:1.0.0
|
||
docker push registry.lions.dev/afterwork-api:latest
|
||
```
|
||
|
||
---
|
||
|
||
## 🚢 Déploiement avec lionsctl pipeline
|
||
|
||
La commande **`lionsctl pipeline`** clone le repo Git, compile (Maven), construit l'image Docker, déploie sur Kubernetes et envoie une notification email. Il n'y a pas de sous-commande `deploy` : tout est inclus dans `lionsctl pipeline`.
|
||
|
||
### Commande de déploiement
|
||
|
||
Remplacez `<org>` par votre organisation Git (ex. `lionsdev`, `developer`) et `<email>` par l'adresse de notification.
|
||
|
||
```bash
|
||
# Déploiement en dev (clone + build + image + déploiement K8s)
|
||
lionsctl pipeline \
|
||
-u https://git.lions.dev/<org>/mic-after-work-server-impl-quarkus-main \
|
||
-b develop \
|
||
-j 17 \
|
||
-e dev \
|
||
-c k1 \
|
||
-m <email>
|
||
|
||
# Déploiement en production sur le cluster k2
|
||
lionsctl pipeline \
|
||
-u https://git.lions.dev/<org>/mic-after-work-server-impl-quarkus-main \
|
||
-b main \
|
||
-j 17 \
|
||
-e production \
|
||
-c k2 \
|
||
-m <email> \
|
||
-p prod
|
||
|
||
# Avec déploiement Helm (charts générés automatiquement)
|
||
lionsctl pipeline \
|
||
-u https://git.lions.dev/<org>/mic-after-work-server-impl-quarkus-main \
|
||
-b develop \
|
||
-j 17 \
|
||
-e dev \
|
||
-c k1 \
|
||
-m <email> \
|
||
--use-helm
|
||
```
|
||
|
||
**Options principales :**
|
||
|
||
| Option | Description | Exemple |
|
||
|--------|-------------|---------|
|
||
| `-u`, `--url` | URL du repo Git (obligatoire) | `https://git.lions.dev/.../mic-after-work-server-impl-quarkus-main` |
|
||
| `-b`, `--branch` | Branche à déployer | `develop`, `main` |
|
||
| `-j`, `--java-version` | Version Java (8–21) | `17` |
|
||
| `-e`, `--environment` | Environnement (dev / staging / production) | `dev`, `production` |
|
||
| `-c`, `--cluster` | Cluster Kubernetes (k1 ou k2) (obligatoire) | `k1`, `k2` |
|
||
| `-m`, `--mail` | Email(s) pour les notifications | `admin@lions.dev` |
|
||
| `-p`, `--profile` | Profil Maven | `prod` pour production |
|
||
| `--use-helm` | Déployer via Helm | — |
|
||
|
||
### Vérification du déploiement
|
||
|
||
```bash
|
||
# Pods et statut (nom d'app dérivé du repo, ex. mic-after-work-server-impl-quarkus-main)
|
||
kubectl get pods -n applications -l app=mic-after-work-server-impl-quarkus-main
|
||
|
||
# Logs en temps réel
|
||
kubectl logs -n applications -l app=mic-after-work-server-impl-quarkus-main -f
|
||
|
||
# Health check
|
||
curl https://api.lions.dev/afterwork/q/health/ready
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 Structure Kubernetes
|
||
|
||
### 1. Secret (kubernetes/afterwork-secrets.yaml)
|
||
|
||
```yaml
|
||
apiVersion: v1
|
||
kind: Secret
|
||
metadata:
|
||
name: afterwork-secrets
|
||
namespace: applications
|
||
type: Opaque
|
||
stringData:
|
||
DB_PASSWORD: "CHANGE_ME_IN_PRODUCTION"
|
||
```
|
||
|
||
### 2. ConfigMap (kubernetes/afterwork-configmap.yaml)
|
||
|
||
```yaml
|
||
apiVersion: v1
|
||
kind: ConfigMap
|
||
metadata:
|
||
name: afterwork-config
|
||
namespace: applications
|
||
data:
|
||
DB_HOST: "postgres"
|
||
DB_PORT: "5432"
|
||
DB_NAME: "afterwork_db"
|
||
DB_USERNAME: "afterwork"
|
||
QUARKUS_PROFILE: "prod"
|
||
TZ: "Africa/Douala"
|
||
```
|
||
|
||
### 3. Deployment (kubernetes/afterwork-deployment.yaml)
|
||
|
||
```yaml
|
||
apiVersion: apps/v1
|
||
kind: Deployment
|
||
metadata:
|
||
name: afterwork-api
|
||
namespace: applications
|
||
labels:
|
||
app: afterwork-api
|
||
version: 1.0.0
|
||
spec:
|
||
replicas: 2
|
||
selector:
|
||
matchLabels:
|
||
app: afterwork-api
|
||
template:
|
||
metadata:
|
||
labels:
|
||
app: afterwork-api
|
||
spec:
|
||
containers:
|
||
- name: afterwork-api
|
||
image: registry.lions.dev/afterwork-api:1.0.0
|
||
imagePullPolicy: Always
|
||
ports:
|
||
- containerPort: 8080
|
||
name: http
|
||
protocol: TCP
|
||
envFrom:
|
||
- configMapRef:
|
||
name: afterwork-config
|
||
- secretRef:
|
||
name: afterwork-secrets
|
||
resources:
|
||
requests:
|
||
memory: "512Mi"
|
||
cpu: "250m"
|
||
limits:
|
||
memory: "1Gi"
|
||
cpu: "1000m"
|
||
livenessProbe:
|
||
httpGet:
|
||
path: /afterwork/q/health/live
|
||
port: 8080
|
||
initialDelaySeconds: 60
|
||
periodSeconds: 30
|
||
timeoutSeconds: 10
|
||
failureThreshold: 3
|
||
readinessProbe:
|
||
httpGet:
|
||
path: /afterwork/q/health/ready
|
||
port: 8080
|
||
initialDelaySeconds: 30
|
||
periodSeconds: 10
|
||
timeoutSeconds: 5
|
||
failureThreshold: 3
|
||
imagePullSecrets:
|
||
- name: registry-credentials
|
||
```
|
||
|
||
### 4. Service (kubernetes/afterwork-service.yaml)
|
||
|
||
```yaml
|
||
apiVersion: v1
|
||
kind: Service
|
||
metadata:
|
||
name: afterwork-api
|
||
namespace: applications
|
||
labels:
|
||
app: afterwork-api
|
||
spec:
|
||
type: ClusterIP
|
||
ports:
|
||
- port: 8080
|
||
targetPort: 8080
|
||
protocol: TCP
|
||
name: http
|
||
selector:
|
||
app: afterwork-api
|
||
```
|
||
|
||
### 5. Ingress (kubernetes/afterwork-ingress.yaml)
|
||
|
||
```yaml
|
||
apiVersion: networking.k8s.io/v1
|
||
kind: Ingress
|
||
metadata:
|
||
name: afterwork-api
|
||
namespace: applications
|
||
annotations:
|
||
cert-manager.io/cluster-issuer: "letsencrypt-prod"
|
||
nginx.ingress.kubernetes.io/ssl-redirect: "true"
|
||
nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
|
||
nginx.ingress.kubernetes.io/proxy-body-size: "10m"
|
||
nginx.ingress.kubernetes.io/rewrite-target: /$2
|
||
spec:
|
||
ingressClassName: nginx
|
||
tls:
|
||
- hosts:
|
||
- api.lions.dev
|
||
secretName: afterwork-api-tls
|
||
rules:
|
||
- host: api.lions.dev
|
||
http:
|
||
paths:
|
||
- path: /afterwork(/|$)(.*)
|
||
pathType: Prefix
|
||
backend:
|
||
service:
|
||
name: afterwork-api
|
||
port:
|
||
number: 8080
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 Processus de Déploiement Complet
|
||
|
||
### Étape 1 : Préparation
|
||
|
||
```bash
|
||
cd C:\Users\dadyo\PersonalProjects\mic-after-work-server-impl-quarkus-main
|
||
|
||
# Build Maven
|
||
mvn clean package -DskipTests
|
||
|
||
# Vérifier que le JAR est créé
|
||
ls target/*-runner.jar
|
||
```
|
||
|
||
### Étape 2 : Build Docker
|
||
|
||
```bash
|
||
# Build l'image de production (Dockerfiles dans docker/)
|
||
docker build -f docker/Dockerfile.prod -t registry.lions.dev/afterwork-api:1.0.0 .
|
||
|
||
# Test local (optionnel)
|
||
docker run --rm -p 8080:8080 \
|
||
-e DB_HOST=postgres \
|
||
-e DB_NAME=afterwork_db \
|
||
-e DB_USERNAME=afterwork \
|
||
-e DB_PASSWORD=test123 \
|
||
registry.lions.dev/afterwork-api:1.0.0
|
||
```
|
||
|
||
### Étape 3 : Push vers Registry
|
||
|
||
```bash
|
||
# Login au registry
|
||
docker login registry.lions.dev
|
||
|
||
# Push
|
||
docker push registry.lions.dev/afterwork-api:1.0.0
|
||
docker tag registry.lions.dev/afterwork-api:1.0.0 registry.lions.dev/afterwork-api:latest
|
||
docker push registry.lions.dev/afterwork-api:latest
|
||
```
|
||
|
||
### Étape 4 : Déploiement Kubernetes
|
||
|
||
```bash
|
||
# Créer le namespace si nécessaire
|
||
kubectl create namespace applications --dry-run=client -o yaml | kubectl apply -f -
|
||
|
||
# Créer les secrets (MODIFIER LES VALEURS!)
|
||
kubectl apply -f kubernetes/afterwork-secrets.yaml
|
||
|
||
# Créer la ConfigMap
|
||
kubectl apply -f kubernetes/afterwork-configmap.yaml
|
||
|
||
# Déployer l'application
|
||
kubectl apply -f kubernetes/afterwork-deployment.yaml
|
||
kubectl apply -f kubernetes/afterwork-service.yaml
|
||
kubectl apply -f kubernetes/afterwork-ingress.yaml
|
||
|
||
# Ou via lionsctl pipeline (clone + build + déploiement)
|
||
lionsctl pipeline -u https://git.lions.dev/<org>/mic-after-work-server-impl-quarkus-main -b develop -j 17 -e dev -c k1 -m <email>
|
||
```
|
||
|
||
### Étape 5 : Vérification
|
||
|
||
```bash
|
||
# Pods
|
||
kubectl get pods -n applications -l app=afterwork-api
|
||
|
||
# Logs
|
||
kubectl logs -n applications -l app=afterwork-api --tail=100 -f
|
||
|
||
# Service
|
||
kubectl get svc -n applications afterwork-api
|
||
|
||
# Ingress
|
||
kubectl get ingress -n applications afterwork-api
|
||
|
||
# Test health
|
||
curl https://api.lions.dev/afterwork/q/health/ready
|
||
curl https://api.lions.dev/afterwork/q/health/live
|
||
|
||
# Test API
|
||
curl https://api.lions.dev/afterwork/api/users/test
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Maintenance
|
||
|
||
### Mise à Jour de l'Application
|
||
|
||
```bash
|
||
# 1. Build nouvelle version
|
||
mvn clean package -DskipTests
|
||
docker build -f docker/Dockerfile.prod -t registry.lions.dev/afterwork-api:1.0.1 .
|
||
docker push registry.lions.dev/afterwork-api:1.0.1
|
||
|
||
# 2. Mise à jour du déploiement
|
||
kubectl set image deployment/afterwork-api \
|
||
afterwork-api=registry.lions.dev/afterwork-api:1.0.1 \
|
||
-n applications
|
||
|
||
# 3. Rollout status
|
||
kubectl rollout status deployment/afterwork-api -n applications
|
||
```
|
||
|
||
### Rollback
|
||
|
||
```bash
|
||
# Voir l'historique
|
||
kubectl rollout history deployment/afterwork-api -n applications
|
||
|
||
# Rollback à la version précédente
|
||
kubectl rollout undo deployment/afterwork-api -n applications
|
||
|
||
# Rollback à une révision spécifique
|
||
kubectl rollout undo deployment/afterwork-api --to-revision=2 -n applications
|
||
```
|
||
|
||
### Scaling
|
||
|
||
```bash
|
||
# Scale up
|
||
kubectl scale deployment afterwork-api --replicas=3 -n applications
|
||
|
||
# Scale down
|
||
kubectl scale deployment afterwork-api --replicas=1 -n applications
|
||
|
||
# Autoscaling (HPA)
|
||
kubectl autoscale deployment afterwork-api \
|
||
--min=2 --max=10 \
|
||
--cpu-percent=80 \
|
||
-n applications
|
||
```
|
||
|
||
---
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
### Problème : Pods ne démarrent pas
|
||
|
||
```bash
|
||
# Vérifier les événements
|
||
kubectl describe pod <pod-name> -n applications
|
||
|
||
# Vérifier les logs
|
||
kubectl logs <pod-name> -n applications
|
||
|
||
# Vérifier les secrets
|
||
kubectl get secret afterwork-secrets -n applications -o yaml
|
||
```
|
||
|
||
### Problème : Base de données inaccessible
|
||
|
||
```bash
|
||
# Tester la connexion depuis un pod
|
||
kubectl run -it --rm debug --image=postgres:15 --restart=Never -- \
|
||
psql -h postgres -U afterwork -d afterwork_db
|
||
|
||
# Vérifier le service PostgreSQL
|
||
kubectl get svc -n postgresql
|
||
```
|
||
|
||
### Problème : Ingress ne fonctionne pas
|
||
|
||
```bash
|
||
# Vérifier l'Ingress
|
||
kubectl describe ingress afterwork-api -n applications
|
||
|
||
# Vérifier les certificats TLS
|
||
kubectl get certificate -n applications
|
||
|
||
# Logs du contrôleur Ingress
|
||
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Monitoring
|
||
|
||
### Métriques Prometheus
|
||
|
||
```bash
|
||
# Accéder aux métriques
|
||
curl https://api.lions.dev/afterwork/q/metrics
|
||
|
||
# Ou via port-forward
|
||
kubectl port-forward -n applications svc/afterwork-api 8080:8080
|
||
curl http://localhost:8080/q/metrics
|
||
```
|
||
|
||
### Logs Centralisés
|
||
|
||
```bash
|
||
# Tous les logs de l'application
|
||
kubectl logs -n applications -l app=afterwork-api --tail=1000
|
||
|
||
# Logs en temps réel
|
||
kubectl logs -n applications -l app=afterwork-api -f
|
||
|
||
# Logs d'un pod spécifique
|
||
kubectl logs -n applications <pod-name> --previous
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 Sécurité
|
||
|
||
### Secrets
|
||
|
||
- ⚠️ **NE JAMAIS** commiter les secrets dans Git
|
||
- Utiliser Sealed Secrets ou Vault pour la gestion des secrets
|
||
- Rotation régulière des mots de passe de base de données
|
||
|
||
### Network Policies
|
||
|
||
```yaml
|
||
apiVersion: networking.k8s.io/v1
|
||
kind: NetworkPolicy
|
||
metadata:
|
||
name: afterwork-api-netpol
|
||
namespace: applications
|
||
spec:
|
||
podSelector:
|
||
matchLabels:
|
||
app: afterwork-api
|
||
policyTypes:
|
||
- Ingress
|
||
- Egress
|
||
ingress:
|
||
- from:
|
||
- namespaceSelector:
|
||
matchLabels:
|
||
name: ingress-nginx
|
||
ports:
|
||
- protocol: TCP
|
||
port: 8080
|
||
egress:
|
||
- to:
|
||
- namespaceSelector:
|
||
matchLabels:
|
||
name: postgresql
|
||
ports:
|
||
- protocol: TCP
|
||
port: 5432
|
||
- to:
|
||
- namespaceSelector: {}
|
||
ports:
|
||
- protocol: TCP
|
||
port: 443 # Pour les APIs externes
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 Checklist de Déploiement
|
||
|
||
### Avant le Déploiement
|
||
|
||
- [ ] Tests unitaires passent
|
||
- [ ] Build Maven réussit
|
||
- [ ] Image Docker créée
|
||
- [ ] Variables d'environnement configurées
|
||
- [ ] Secrets créés dans Kubernetes
|
||
- [ ] Base de données PostgreSQL prête
|
||
|
||
### Pendant le Déploiement
|
||
|
||
- [ ] Image pushée vers le registry
|
||
- [ ] Manifests Kubernetes appliqués
|
||
- [ ] Pods démarrent correctement
|
||
- [ ] Health checks réussissent
|
||
- [ ] Ingress configuré avec TLS
|
||
|
||
### Après le Déploiement
|
||
|
||
- [ ] API accessible via HTTPS
|
||
- [ ] WebSocket fonctionne
|
||
- [ ] Tests d'intégration passent
|
||
- [ ] Métriques remontées dans Prometheus
|
||
- [ ] Logs centralisés fonctionnent
|
||
- [ ] Documentation mise à jour
|
||
|
||
---
|
||
|
||
## 📞 Support
|
||
|
||
En cas de problème :
|
||
1. Consulter les logs : `kubectl logs -n applications -l app=afterwork-api`
|
||
2. Vérifier les events : `kubectl get events -n applications`
|
||
3. Tester les health checks : `curl https://api.lions.dev/afterwork/q/health`
|
||
4. Contacter l'équipe DevOps
|
||
|
||
---
|
||
|
||
**Dernière mise à jour** : 2026-01-09
|
||
**Version** : 1.0.0
|