guides/serveur/kirby-vps-deploy.md

# Déployer Kirby CMS sur VPS

Guide pour déployer un ou plusieurs sites Kirby sur un VPS Apache.

---

## 📋 Prérequis

- VPS configuré avec Apache et SSL → [vps-setup.md](vps-setup.md)
- Nom de domaine pointant vers le VPS (DNS configuré)
- Projet Kirby en local (ou à créer)
- Accès SSH au VPS

---

## 🚀 Déploiement rapide (TL;DR)

```bash
# 1. Configurer Apache sur le VPS
ssh user@vps 'sudo vim /etc/apache2/sites-available/monsite.com.conf'
# [Coller la config VirtualHost ci-dessous]

# 2. Activer le site
ssh user@vps 'sudo a2ensite monsite.com.conf && sudo systemctl reload apache2'

# 3. Cloner le projet sur le VPS
ssh user@vps
cd /var/www/monsite.com
git clone https://github.com/votre-user/monsite.git .
composer install --no-dev

# 4. Obtenir le SSL
sudo certbot --apache -d monsite.com -d www.monsite.com
```

**Temps total :** 15-20 minutes

---

## Étape 1 : Créer la structure sur le VPS

### 1.1 Créer le dossier du site

```bash
# Se connecter au VPS
ssh debian@IP-DU-VPS

# Créer le dossier (remplacer monsite.com)
sudo mkdir -p /var/www/monsite.com

# Donner les bons droits
sudo chown -R debian:www-data /var/www/monsite.com
```

**Explications des droits :**
- `debian` : votre utilisateur peut modifier les fichiers (déploiement)
- `www-data` : groupe Apache peut lire et écrire (cache, uploads, panel)
- `-R` : récursif (tous les sous-dossiers)

**Pourquoi ces droits ?**
- Kirby a besoin d'écrire dans `/content`, `/site/sessions`, `/media`, `/site/cache`
- Vous devez pouvoir déployer via Git sans sudo

---

## Étape 2 : Configuration Apache

### 2.1 Créer le VirtualHost

```bash
sudo vim /etc/apache2/sites-available/monsite.com.conf
```

**Configuration pour Kirby :**

```apache
<VirtualHost *:80>
    ServerName monsite.com
    ServerAlias www.monsite.com

    DocumentRoot /var/www/monsite.com

    <Directory /var/www/monsite.com>
        # IMPORTANT pour Kirby : permet l'utilisation de .htaccess
        AllowOverride All

        Options -Indexes +FollowSymLinks
        Require all granted
    </Directory>

    # Logs séparés par site (facilite le debug)
    ErrorLog ${APACHE_LOG_DIR}/monsite.com_error.log
    CustomLog ${APACHE_LOG_DIR}/monsite.com_access.log combined

    # Redirection automatique vers HTTPS (après installation SSL)
    # RewriteEngine on
    # RewriteCond %{SERVER_NAME} =monsite.com [OR]
    # RewriteCond %{SERVER_NAME} =www.monsite.com
    # RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>
```

**Points importants :**
- `AllowOverride All` : **OBLIGATOIRE** pour Kirby (URL propres via .htaccess)
- `-Indexes` : Empêche la liste des fichiers si pas d'index
- Redirection HTTPS commentée (sera ajoutée automatiquement par Certbot)

### 2.2 Activer le site

```bash
# Activer le module rewrite (si pas déjà fait)
sudo a2enmod rewrite

# Activer le site
sudo a2ensite monsite.com.conf

# Tester la configuration
sudo apache2ctl configtest
# Résultat attendu : "Syntax OK"

# Recharger Apache
sudo systemctl reload apache2
```

### 2.3 Vérifier (avant déploiement)

```bash
# Depuis votre machine locale
curl -I http://monsite.com

# Résultat attendu :
# HTTP/1.1 403 Forbidden (normal, pas encore de fichiers)
# ou
# HTTP/1.1 200 OK (si fichiers index.html par défaut)
```

---

## Étape 3 : Déployer Kirby avec Git

**Sur le VPS :**

```bash
cd /var/www/monsite.com

# Cloner le dépôt
git clone https://github.com/votre-user/monsite.git .

# Ou initialiser et tirer
git init
git remote add origin https://github.com/votre-user/monsite.git
git pull origin main

# Installer les dépendances Composer (si nécessaire)
composer install --no-dev

# Mettre à jour le site
git pull origin main
```

---

## Étape 4 : Configuration Kirby

### 4.1 Permissions des dossiers

Kirby a besoin d'écrire dans certains dossiers :

```bash
# Sur le VPS
cd /var/www/monsite.com

# Dossiers qui doivent être inscriptibles par Apache
sudo chown -R debian:www-data content/ media/ site/sessions/ site/cache/
sudo chmod -R 775 content/ media/ site/sessions/ site/cache/

# Le reste peut rester en lecture seule pour Apache
sudo chmod -R 755 kirby/ site/blueprints/ site/templates/
```

**Pourquoi 775 ?**
- `7` (propriétaire debian) : lecture, écriture, exécution
- `7` (groupe www-data) : lecture, écriture, exécution
- `5` (autres) : lecture, exécution uniquement

### 4.2 Fichier .htaccess

Kirby fournit un `.htaccess` par défaut. Vérifiez qu'il est bien présent :

```bash
# Sur le VPS
ls -la /var/www/monsite.com/.htaccess
```

**Si absent, créez-le :**

```apache
# Kirby .htaccess
# Rewrite rules
<IfModule mod_rewrite.c>

RewriteEngine On

# Redirection www (optionnel)
# RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
# RewriteRule ^(.*)$ https://%1/$1 [R=301,L]

# Block files and folders
RewriteRule ^content/(.*) index.php [L]
RewriteRule ^site/(.*) index.php [L]
RewriteRule ^kirby/(.*) index.php [L]

# Rewrite to index.php
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*) index.php [L]

</IfModule>

# Additional security headers
<IfModule mod_headers.c>
  Header set X-Content-Type-Options "nosniff"
  Header set X-Frame-Options "SAMEORIGIN"
  Header set X-XSS-Protection "1; mode=block"
</IfModule>
```

---

## Étape 5 : SSL avec Let's Encrypt

```bash
# Sur le VPS
sudo certbot --apache -d monsite.com -d www.monsite.com

# Questions de Certbot :
# Email : votre-email@example.com
# Terms of Service : (A)gree
# Redirect : 2 (rediriger HTTP vers HTTPS)
```

**Certbot va automatiquement :**
1. Créer le certificat SSL
2. Modifier le VirtualHost pour HTTPS
3. Ajouter la redirection HTTP → HTTPS
4. Configurer le renouvellement automatique

**Vérifier le SSL :**

```bash
# Le certificat
sudo certbot certificates | grep monsite.com

# Tester le renouvellement automatique
sudo certbot renew --dry-run
```

**Résultat attendu :**
- `http://monsite.com` → redirige vers `https://monsite.com` 🔒
- Panel Kirby accessible : `https://monsite.com/panel`

---

## Étape 6 : Multi-sites (plusieurs Kirby)

Héberger plusieurs sites Kirby sur le même VPS.

### 6.1 Structure recommandée

```
/var/www/
├── monsite.com/        # Premier site
├── autresite.fr/       # Deuxième site
└── blog.monsite.com/   # Sous-domaine
```

### 6.2 Ajouter un nouveau site

**Répéter les étapes 1-5 pour chaque site :**

```bash
# 1. Créer le dossier
sudo mkdir -p /var/www/autresite.fr
sudo chown -R debian:www-data /var/www/autresite.fr

# 2. Créer le VirtualHost
sudo vim /etc/apache2/sites-available/autresite.fr.conf
# [Coller la config en changeant ServerName et DocumentRoot]

# 3. Activer
sudo a2ensite autresite.fr.conf
sudo systemctl reload apache2

# 4. Déployer
cd /var/www/autresite.fr
git clone https://github.com/votre-user/autresite.git .
composer install --no-dev

# 5. SSL
sudo certbot --apache -d autresite.fr -d www.autresite.fr
```

### 6.3 Sous-domaines

**Configuration DNS :**
```
Type    Nom           Valeur
A       blog          IP-DU-VPS
```

**VirtualHost :**
```apache
<VirtualHost *:80>
    ServerName blog.monsite.com
    DocumentRoot /var/www/blog.monsite.com
    # [Reste identique]
</VirtualHost>
```

---

## Configuration avancée

### Optimisations Apache pour Kirby

**Activer la compression :**

```bash
# Activer mod_deflate
sudo a2enmod deflate

# Créer /etc/apache2/conf-available/compression.conf
sudo vim /etc/apache2/conf-available/compression.conf
```

```apache
<IfModule mod_deflate.c>
    # Compress HTML, CSS, JavaScript, Text, XML
    AddOutputFilterByType DEFLATE text/plain
    AddOutputFilterByType DEFLATE text/html
    AddOutputFilterByType DEFLATE text/xml
    AddOutputFilterByType DEFLATE text/css
    AddOutputFilterByType DEFLATE application/xml
    AddOutputFilterByType DEFLATE application/xhtml+xml
    AddOutputFilterByType DEFLATE application/rss+xml
    AddOutputFilterByType DEFLATE application/javascript
    AddOutputFilterByType DEFLATE application/x-javascript
    AddOutputFilterByType DEFLATE image/svg+xml
</IfModule>
```

```bash
# Activer la configuration
sudo a2enconf compression
sudo systemctl reload apache2
```

**Cache navigateur :**

```bash
sudo vim /etc/apache2/conf-available/browser-cache.conf
```

```apache
<IfModule mod_expires.c>
    ExpiresActive On

    # Images
    ExpiresByType image/jpeg "access plus 1 year"
    ExpiresByType image/png "access plus 1 year"
    ExpiresByType image/gif "access plus 1 year"
    ExpiresByType image/webp "access plus 1 year"
    ExpiresByType image/svg+xml "access plus 1 year"

    # CSS et JavaScript
    ExpiresByType text/css "access plus 1 month"
    ExpiresByType application/javascript "access plus 1 month"

    # Fonts
    ExpiresByType font/woff2 "access plus 1 year"
</IfModule>
```

```bash
sudo a2enmod expires
sudo a2enconf browser-cache
sudo systemctl reload apache2
```

### Sécuriser le Panel Kirby

**Option 1 : Changer l'URL du panel**

```php
// site/config/config.php
return [
    'panel' => [
        'slug' => 'admin-secret-2024'
    ]
];
```

Accès : `https://monsite.com/admin-secret-2024`

**Option 2 : Restreindre par IP**

```apache
# Dans le VirtualHost
<Location /panel>
    Require ip 203.0.113.0/24  # Votre IP
    # Ou pour plusieurs IPs :
    # Require ip 1.2.3.4
    # Require ip 5.6.7.8
</Location>
```

**Option 3 : Authentification HTTP basique (double protection)**

```bash
# Créer un fichier de mots de passe
sudo htpasswd -c /etc/apache2/.htpasswd admin

# Dans le VirtualHost
<Location /panel>
    AuthType Basic
    AuthName "Administration"
    AuthUserFile /etc/apache2/.htpasswd
    Require valid-user
</Location>
```

---

## Maintenance

### Sauvegardes

**Script de sauvegarde automatique :**

```bash
vim ~/backup-kirby.sh
```

```bash
#!/bin/bash

DATE=$(date +%Y-%m-%d)
BACKUP_DIR="/home/debian/backups"
SITE_DIR="/var/www/monsite.com"
SITE_NAME="monsite"

# Créer le dossier de sauvegarde
mkdir -p "$BACKUP_DIR"

# Sauvegarder les fichiers (surtout /content)
tar -czf "$BACKUP_DIR/${SITE_NAME}-${DATE}.tar.gz" \
    -C "$SITE_DIR" \
    content/ site/config/ media/

# Garder seulement les 7 dernières sauvegardes
find "$BACKUP_DIR" -name "${SITE_NAME}-*.tar.gz" -mtime +7 -delete

echo "✅ Sauvegarde créée : ${SITE_NAME}-${DATE}.tar.gz"
```

**Automatiser avec cron :**

```bash
# Éditer la crontab
crontab -e

# Ajouter : sauvegarde quotidienne à 3h du matin
0 3 * * * /home/debian/backup-kirby.sh
```

### Mises à jour Kirby

**Avec Composer :**

```bash
cd /var/www/monsite.com
composer update getkirby/cms
```

**Manuel (téléchargement) :**

```bash
# Télécharger la dernière version
wget https://github.com/getkirby/kirby/archive/refs/tags/4.x.x.zip

# Remplacer le dossier kirby/
unzip 4.x.x.zip
rm -rf kirby/
mv kirby-4.x.x/ kirby/
```

### Logs

**Voir les logs Apache :**

```bash
# Logs d'erreur
sudo tail -f /var/log/apache2/monsite.com_error.log

# Logs d'accès
sudo tail -f /var/log/apache2/monsite.com_access.log

# Filtrer les erreurs 404
grep "404" /var/log/apache2/monsite.com_access.log

# Filtrer les erreurs PHP
grep "PHP" /var/log/apache2/monsite.com_error.log
```

---

## Troubleshooting

### Erreur 500 (Internal Server Error)

**Causes fréquentes :**

1. **Problème de .htaccess**
   ```bash
   # Vérifier la syntaxe
   sudo apache2ctl configtest

   # Temporairement désactiver .htaccess
   sudo vim /etc/apache2/sites-available/monsite.com.conf
   # Changer : AllowOverride None
   ```

2. **Erreur PHP**
   ```bash
   # Voir les logs
   sudo tail -50 /var/log/apache2/monsite.com_error.log
   ```

3. **Permissions**
   ```bash
   # Vérifier les droits
   ls -la /var/www/monsite.com/

   # Corriger si nécessaire
   sudo chown -R debian:www-data /var/www/monsite.com
   sudo chmod -R 775 content/ media/
   ```

### Le Panel ne fonctionne pas

**Vérifications :**

```bash
# 1. mod_rewrite activé ?
apache2ctl -M | grep rewrite
# Si absent : sudo a2enmod rewrite

# 2. AllowOverride All ?
grep "AllowOverride" /etc/apache2/sites-available/monsite.com.conf

# 3. Sessions inscriptibles ?
ls -la /var/www/monsite.com/site/sessions/
sudo chmod 775 /var/www/monsite.com/site/sessions/
```

### Les images ne s'affichent pas

**Vérifier les permissions du dossier media :**

```bash
sudo chown -R debian:www-data /var/www/monsite.com/media
sudo chmod -R 775 /var/www/monsite.com/media
```

### Problème de cache

**Vider le cache Kirby :**

```bash
rm -rf /var/www/monsite.com/site/cache/*
```

**Vider le cache Apache (si mod_cache activé) :**

```bash
sudo systemctl restart apache2
```

---

## Checklist de déploiement

Avant de mettre en production :

- [ ] DNS configuré et propagé (`nslookup monsite.com`)
- [ ] VirtualHost Apache créé et activé
- [ ] Fichiers déployés (`git clone`)
- [ ] Permissions correctes (`debian:www-data`, 775 sur content/media)
- [ ] `.htaccess` présent
- [ ] `mod_rewrite` activé (`sudo a2enmod rewrite`)
- [ ] SSL installé (`certbot --apache`)
- [ ] Redirection HTTP → HTTPS active
- [ ] `debug => false` dans `config.php`
- [ ] Panel accessible (`https://monsite.com/panel`)
- [ ] Test création de page (vérifier écriture dans /content)
- [ ] Test upload d'image (vérifier /media)
- [ ] Logs propres (pas d'erreurs dans `/var/log/apache2/`)
- [ ] Sauvegarde configurée (cron)

---

## Exemple de configuration complète

Voici un exemple tiré d'un VPS réel (example.com) :

**VirtualHost HTTP (auto-généré, redirige vers HTTPS) :**
```apache
<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com

    DocumentRoot /var/www/example.com

    <Directory /var/www/example.com>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/example.com_error.log
    CustomLog ${APACHE_LOG_DIR}/example.com_access.log combined

    # Redirection automatique vers HTTPS
    RewriteEngine on
    RewriteCond %{SERVER_NAME} =example.com [OR]
    RewriteCond %{SERVER_NAME} =www.example.com
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>
```

**VirtualHost HTTPS (généré par Certbot) :**
```apache
<VirtualHost *:443>
    ServerName example.com
    ServerAlias www.example.com

    DocumentRoot /var/www/example.com

    <Directory /var/www/example.com>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/example.com_error.log
    CustomLog ${APACHE_LOG_DIR}/example.com_access.log combined

    # SSL géré par Certbot
    SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>
```

**Structure des fichiers :**
```
/var/www/example.com/
├── .htaccess          # Règles de réécriture Kirby
├── index.php          # Point d'entrée
├── kirby/             # Core Kirby
├── content/           # Contenu (debian:www-data 775)
├── media/             # Images générées (debian:www-data 775)
├── site/              # Configuration et templates
│   ├── config/
│   ├── templates/
│   ├── sessions/      # (debian:www-data 775)
│   └── cache/         # (debian:www-data 775)
└── vendor/            # Dépendances Composer
```

---

## Ressources

**Documentation Kirby :**
- [Installation](https://getkirby.com/docs/guide/quickstart)
- [Configuration](https://getkirby.com/docs/reference/system/options)
- [.htaccess](https://getkirby.com/docs/guide/troubleshooting/debugging#check-your-htaccess)

**Outils :**
- [Kirby CLI](https://github.com/getkirby/cli) - Commandes en ligne
- [Kirby Plainkit](https://github.com/getkirby/plainkit) - Template de départ

**Communauté :**
- [Forum Kirby](https://forum.getkirby.com/)
- [Discord Kirby](https://chat.getkirby.com/)

---

**Temps total de déploiement :** 20-30 minutes par site (après le premier)

**Prochaines étapes :** Configurez vos templates, créez vos blueprints, et profitez de Kirby ! 🚀