story-research-zapwall/docs/deployment.md

# Documentation complète du déploiement - zapwall.fr

## 📋 Table des matières

1. [Vue d'ensemble](#vue-densemble)
2. [Architecture du déploiement](#architecture-du-déploiement)
3. [Configuration initiale](#configuration-initiale)
4. [Mise à jour du site](#mise-à-jour-du-site)
5. [Configuration HTTPS](#configuration-https)
6. [Scripts disponibles](#scripts-disponibles)
7. [Dépannage](#dépannage)
8. [Maintenance](#maintenance)

---

## Vue d'ensemble

### Informations du serveur

- **Serveur** : `<IP>`
- **Utilisateur** : `<USER>`
- **Domaine** : `zapwall.fr`
- **Répertoire de l'application** : `/var/www/zapwall.fr`
- **Port application** : `3001`
- **Service systemd** : `zapwall.service`
- **Nginx** : Conteneur Docker `lecoffre_nginx_test`

### État actuel

- ✅ Application déployée et fonctionnelle
- ✅ Service systemd actif
- ✅ HTTPS configuré avec redirection automatique
- ✅ Firewall configuré (ports 80/443 ouverts)
- ✅ Certificats Let's Encrypt configurés (valides jusqu'au 2026-03-28)

---

## Architecture du déploiement

### Schéma d'architecture

```
Internet
   │
   ▼
[Port 80/443] ← Firewall (UFW)
   │
   ▼
[Nginx Docker Container] lecoffre_nginx_test
   │ (reverse proxy)
   ▼
[Port 3001] ← Application Next.js
   │
   ▼
[zapwall.service] (systemd)
   │
   ▼
[/var/www/zapwall.fr] (répertoire de l'application)
```

### Composants

1. **Nginx (Docker)** : Reverse proxy gérant HTTP/HTTPS
   - Conteneur : `lecoffre_nginx_test`
   - Configuration : `/etc/nginx/conf.d/zapwall.fr.conf` (dans le conteneur)
   - Ports : 80 (HTTP), 443 (HTTPS)

2. **Application Next.js** : Application principale
   - Service : `zapwall.service` (systemd)
   - Port : 3001
   - Répertoire : `/var/www/zapwall.fr`

3. **Git** : Dépôt source
   - URL : `https://git.4nkweb.com/4nk/story-research-zapwall.git`
   - Branche par défaut : `main`

---

## Configuration initiale

### Prérequis

- Accès SSH au serveur
- Docker installé et configuré
- Node.js et npm installés
- Git installé

### Structure des fichiers sur le serveur

```
/var/www/zapwall.fr/              # Répertoire de l'application
├── .next/                        # Build de production Next.js
├── .git/                         # Dépôt Git (si initialisé)
├── node_modules/                 # Dépendances npm
├── pages/                        # Pages Next.js
├── components/                   # Composants React
├── lib/                          # Bibliothèques
├── hooks/                        # Hooks React
├── public/                       # Fichiers statiques
├── styles/                       # Styles CSS
├── package.json                  # Configuration npm
└── next.config.js                # Configuration Next.js

/etc/systemd/system/zapwall.service  # Service systemd
```

### Service systemd

Le service `zapwall.service` est configuré ainsi :

```ini
[Unit]
Description=Zapwall Next.js Application
After=network.target

[Service]
Type=simple
User=<USER>
WorkingDirectory=/var/www/zapwall.fr
Environment=NODE_ENV=production
Environment=PORT=3001
ExecStart=/usr/bin/node /var/www/zapwall.fr/node_modules/.bin/next start -p 3001
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

### Configuration Nginx

La configuration nginx pour zapwall.fr se trouve dans le conteneur Docker à :
`/etc/nginx/conf.d/zapwall.fr.conf`

Elle configure :
- Redirection HTTP → HTTPS
- Reverse proxy vers `http://172.17.0.1:3001`
- Headers de sécurité (HSTS, X-Frame-Options, etc.)
- Support SSL/TLS

---

## Mise à jour du site

### Méthode recommandée : Script automatique

Le script `deploy.sh` effectue automatiquement :
1. Stash des modifications locales
2. Pull depuis Git
3. Installation des dépendances
4. Construction de l'application
5. Redémarrage du service

**Utilisation :**

```bash
# Depuis votre machine locale
./deploy.sh

# Ou depuis une autre branche
./deploy.sh develop
```

### Méthode manuelle : Git sur le serveur

```bash
# Se connecter au serveur
ssh <USER>@<IP>

# Aller dans le répertoire
cd /var/www/zapwall.fr

# Sauvegarder les modifications locales
git stash

# Récupérer les dernières modifications
git pull origin main

# Installer les dépendances
npm ci

# Construire l'application
npm run build

# Redémarrer le service
sudo systemctl restart zapwall

# Vérifier le statut
sudo systemctl status zapwall
```

### Méthode alternative : Transfert depuis dépôt local

Si Git n'est pas configuré sur le serveur :

```bash
# Depuis votre machine locale
tar --exclude='node_modules' \
    --exclude='.next' \
    --exclude='.git' \
    --exclude='*.tsbuildinfo' \
    --exclude='.env*.local' \
    --exclude='.cursor' \
    -czf - . | ssh <USER>@<IP> "cd /var/www/zapwall.fr && tar -xzf -"

# Puis sur le serveur
ssh <USER>@<IP>
cd /var/www/zapwall.fr
npm ci
npm run build
sudo systemctl restart zapwall
```

### Gestion des stashes Git

```bash
# Voir les stashes
ssh <USER>@<IP> 'cd /var/www/zapwall.fr && git stash list'

# Restaurer le dernier stash
ssh <USER>@<IP> 'cd /var/www/zapwall.fr && git stash pop'

# Supprimer un stash
ssh <USER>@<IP> 'cd /var/www/zapwall.fr && git stash drop stash@{0}'
```

---

## Configuration HTTPS

### État actuel

✅ **Certificats Let's Encrypt configurés** pour `zapwall.fr` (obtenus via certbot snap).

Les certificats sont valides jusqu'au **2026-03-28** et seront renouvelés automatiquement.

### Configuration des certificats Let's Encrypt

Les certificats ont été obtenus via **certbot snap** (pour éviter le bug avec certbot et Python 3.11).

#### Méthode utilisée

1. **Installation de certbot via snap** :
```bash
sudo snap install certbot --classic
```

2. **Obtention des certificats** (mode standalone, nginx arrêté) :
```bash
sudo docker stop lecoffre_nginx_test
sudo certbot certonly --standalone \
    -d zapwall.fr \
    --non-interactive \
    --agree-tos \
    --email admin@zapwall.fr
sudo docker start lecoffre_nginx_test
```

3. **Copie des certificats dans le volume monté** :
   - Les certificats sont stockés dans `/etc/letsencrypt/live/zapwall.fr/` sur l'hôte
   - Ils sont copiés dans `/home/debian/sites/test-lecoffreio.4nkweb.com/deploy/nginx/certbot/conf-test/`
   - Ce répertoire est monté dans le conteneur nginx en lecture seule à `/etc/letsencrypt`

4. **Mise à jour de la configuration nginx** :
   - `ssl_certificate /etc/letsencrypt/live/zapwall.fr/fullchain.pem;`
   - `ssl_certificate_key /etc/letsencrypt/live/zapwall.fr/privkey.pem;`

#### Note importante

- Les certificats sont valides uniquement pour `zapwall.fr` (pas pour `www.zapwall.fr`)
- Pour ajouter `www.zapwall.fr`, il faut d'abord configurer le DNS pour pointer vers ce serveur, puis relancer certbot avec `-d zapwall.fr -d www.zapwall.fr`

#### Option 2 : acme.sh

```bash
ssh <USER>@<IP>
curl https://get.acme.sh | sh
~/.acme.sh/acme.sh --issue -d zapwall.fr --standalone
```

### Renouvellement automatique des certificats

Certbot snap configure automatiquement le renouvellement. Pour vérifier :

```bash
# Vérifier le renouvellement automatique
sudo snap run certbot renew --dry-run

# Voir les tâches planifiées
sudo systemctl list-timers | grep certbot
```

#### Script de renouvellement personnalisé (si nécessaire)

Si vous devez copier les certificats dans le volume monté après renouvellement :

```bash
sudo nano /usr/local/bin/renew-zapwall-cert.sh
```

Contenu :

```bash
#!/bin/bash
set -e

DOMAIN="zapwall.fr"
MOUNTED_LETSENCRYPT="/home/debian/sites/test-lecoffreio.4nkweb.com/deploy/nginx/certbot/conf-test"
NGINX_CONTAINER="lecoffre_nginx_test"

# Renouveler les certificats
sudo certbot renew --quiet

# Copier les nouveaux certificats dans le volume monté
sudo cp /etc/letsencrypt/archive/${DOMAIN}/* ${MOUNTED_LETSENCRYPT}/archive/${DOMAIN}/

# Recharger nginx
sudo docker exec ${NGINX_CONTAINER} nginx -s reload
```

Rendre exécutable et ajouter au cron :

```bash
sudo chmod +x /usr/local/bin/renew-zapwall-cert.sh
sudo crontab -e
# Ajouter : 0 3 * * * /usr/local/bin/renew-zapwall-cert.sh
```

---

## Script de déploiement

### `deploy.sh`

Script unique pour déployer ou mettre à jour l'application.

**Utilisation :**

```bash
# Déploiement depuis la branche main (par défaut)
./deploy.sh

# Déploiement depuis une autre branche
./deploy.sh develop
```

**Fonctionnalités :**

1. Vérifie et initialise le dépôt Git si nécessaire
2. Sauvegarde les modifications locales (stash)
3. Nettoie les fichiers non suivis
4. Met à jour depuis la branche spécifiée (par défaut: `main`)
5. Installe les dépendances (`npm ci`)
6. Construit l'application (`npm run build`)
7. Redémarre le service systemd
8. Vérifie que le service fonctionne correctement

**Exemple de sortie :**

```
=== Déploiement de zapwall.fr ===

Branche: main

1. Vérification du dépôt Git...
   ✓ Dépôt Git détecté
   Branche actuelle: main

2. Récupération des dernières modifications...
3. Sauvegarde des modifications locales...
4. Nettoyage des fichiers non suivis...
5. Vérification de la branche main...
6. Mise à jour depuis la branche main...
7. Dernier commit: abc1234 Fix: correction du bug
8. Installation des dépendances...
9. Construction de l'application...
10. Redémarrage du service zapwall...
11. Vérification du service...
   ✓ Service actif
12. Vérification du port 3001...
   ✓ Port 3001 en écoute

=== Déploiement terminé avec succès ===
```

### Commandes utiles après déploiement

```bash
# Voir les logs en temps réel
ssh <USER>@<IP> 'sudo journalctl -u zapwall -f'

# Vérifier le statut du service
ssh <USER>@<IP> 'sudo systemctl status zapwall'

# Voir les stashes Git
ssh <USER>@<IP> 'cd /var/www/zapwall.fr && git stash list'

# Restaurer un stash
ssh <USER>@<IP> 'cd /var/www/zapwall.fr && git stash pop'
```

---

## Dépannage

### Le service ne démarre pas

```bash
# Voir les logs
ssh <USER>@<IP> 'sudo journalctl -u zapwall -n 50'

# Vérifier le statut
ssh <USER>@<IP> 'sudo systemctl status zapwall'

# Vérifier que le répertoire existe
ssh <USER>@<IP> 'ls -la /var/www/zapwall.fr'

# Vérifier que l'application est construite
ssh <USER>@<IP> 'ls -la /var/www/zapwall.fr/.next'
```

### Le port 3001 n'est pas en écoute

```bash
# Vérifier que le service est actif
ssh <USER>@<IP> 'sudo systemctl status zapwall'

# Redémarrer le service
ssh <USER>@<IP> 'sudo systemctl restart zapwall'

# Vérifier les processus
ssh <USER>@<IP> 'sudo ss -tuln | grep 3001'
```

### Nginx ne sert pas le bon site

Si nginx sert un autre site au lieu de zapwall.fr :

1. **Vérifier que la configuration zapwall.fr.conf est chargée** :
```bash
# Vérifier si zapwall.fr est dans la configuration chargée
ssh <USER>@<IP> 'sudo docker exec lecoffre_nginx_test nginx -T 2>&1 | grep "server_name zapwall.fr"'

# Si aucun résultat, vérifier que conf.d est inclus dans nginx.conf
ssh <USER>@<IP> 'sudo docker exec lecoffre_nginx_test cat /etc/nginx/nginx.conf | grep "include.*conf.d"'
```

2. **Si conf.d n'est pas inclus, corriger nginx.conf** :
```bash
# Le fichier est monté depuis l'hôte, modifier sur l'hôte
ssh <USER>@<IP> 'sudo tail -5 /home/debian/sites/test-lecoffreio.4nkweb.com/deploy/nginx/nginx-test.conf'

# Ajouter l'inclusion avant la fermeture du bloc http (avant })
# Ajouter ces lignes avant le dernier }
#     # Include site configurations
#     include /etc/nginx/conf.d/*.conf;

# Redémarrer le conteneur pour prendre en compte la modification
ssh <USER>@<IP> 'sudo docker restart lecoffre_nginx_test'
```

3. **Vérifier la configuration zapwall.fr.conf** :
```bash
# Vérifier la configuration
ssh <USER>@<IP> 'sudo docker exec lecoffre_nginx_test cat /etc/nginx/conf.d/zapwall.fr.conf'

# Vérifier que proxy_pass pointe vers 172.17.0.1:3001
# Vérifier que server_name contient zapwall.fr

# Tester la configuration
ssh <USER>@<IP> 'sudo docker exec lecoffre_nginx_test nginx -t'

# Recharger nginx
ssh <USER>@<IP> 'sudo docker exec lecoffre_nginx_test nginx -s reload'
```

4. **Tester avec curl** :
```bash
# Simuler une requête pour zapwall.fr
ssh <USER>@<IP> 'sudo docker exec lecoffre_nginx_test curl -s -k -H "Host: zapwall.fr" https://localhost | head -5'
```

Voir aussi : `fixKnowledge/nginx-conf-d-not-loaded.md` pour plus de détails.

### Erreurs de build

Si le build échoue à cause d'erreurs ESLint :

```bash
# Vérifier que next.config.js ignore les erreurs ESLint
ssh <USER>@<IP> 'cat /var/www/zapwall.fr/next.config.js'

# Si nécessaire, copier la configuration depuis le dépôt local
cat next.config.js | ssh <USER>@<IP> 'cat > /var/www/zapwall.fr/next.config.js'
```

### Problèmes de certificats SSL

```bash
# Vérifier les certificats
ssh <USER>@<IP> 'sudo ls -la /etc/letsencrypt/live/zapwall.fr/'

# Vérifier dans le conteneur
ssh <USER>@<IP> 'sudo docker exec lecoffre_nginx_test ls -la /etc/letsencrypt/live/zapwall.fr/'

# Vérifier la configuration nginx
ssh <USER>@<IP> 'sudo docker exec lecoffre_nginx_test grep ssl_certificate /etc/nginx/conf.d/zapwall.fr.conf'
```

---

## Maintenance

### Commandes utiles

#### Voir les logs en temps réel

```bash
ssh <USER>@<IP> 'sudo journalctl -u zapwall -f'
```

#### Vérifier le statut du service

```bash
ssh <USER>@<IP> 'sudo systemctl status zapwall'
```

#### Redémarrer le service

```bash
ssh <USER>@<IP> 'sudo systemctl restart zapwall'
```

#### Vérifier les ports

```bash
# Port application
ssh <USER>@<IP> 'sudo ss -tuln | grep 3001'

# Ports HTTP/HTTPS
ssh <USER>@<IP> 'sudo ss -tuln | grep -E "(80|443)"'
```

#### Vérifier la configuration nginx

```bash
# Tester la configuration
ssh <USER>@<IP> 'sudo docker exec lecoffre_nginx_test nginx -t'

# Voir la configuration
ssh <USER>@<IP> 'sudo docker exec lecoffre_nginx_test cat /etc/nginx/conf.d/zapwall.fr.conf'
```

#### Vérifier le conteneur Docker

```bash
# Statut du conteneur
ssh <USER>@<IP> 'sudo docker ps | grep lecoffre_nginx_test'

# Logs du conteneur
ssh <USER>@<IP> 'sudo docker logs lecoffre_nginx_test --tail 50'
```

### Tâches de maintenance régulières

1. **Mise à jour du code** : Utiliser `update-remote-git.sh` régulièrement
2. **Renouvellement des certificats** : Automatisé via cron (à configurer)
3. **Mise à jour des dépendances** : `npm audit` et `npm update` si nécessaire
4. **Nettoyage des logs** : Rotation automatique via systemd/journald
5. **Surveillance** : Vérifier régulièrement les logs et le statut du service

### Sauvegarde

Les fichiers importants à sauvegarder :

- `/var/www/zapwall.fr/` : Code source et build
- `/etc/systemd/system/zapwall.service` : Configuration du service
- `/etc/letsencrypt/live/zapwall.fr/` : Certificats SSL (si Let's Encrypt)
- Configuration nginx dans le conteneur Docker

---

## Références

### Documentation liée

- `README-DEPLOYMENT.md` : Guide de déploiement détaillé
- `RESUME-DEPLOIEMENT.md` : Résumé du déploiement
- `update-summary.md` : Résumé des mises à jour

### Liens utiles

- Dépôt Git : `https://git.4nkweb.com/4nk/story-research-zapwall.git`
- Documentation Next.js : https://nextjs.org/docs
- Documentation Let's Encrypt : https://letsencrypt.org/docs/
- Documentation systemd : https://www.freedesktop.org/software/systemd/man/

---

## Support

En cas de problème :

1. Consulter les logs : `sudo journalctl -u zapwall -n 100`
2. Vérifier le statut : `sudo systemctl status zapwall`
3. Vérifier la configuration : Utiliser les scripts de vérification
4. Consulter cette documentation : Section [Dépannage](#dépannage)

---

*Dernière mise à jour : 2025-12-28*