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
• 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)

# 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

# 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

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

Configuration pour Kirby :

<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

# 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)

# 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 :

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 :

# 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 :

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

Si absent, créez-le :

# 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

# 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 :

# 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 :

# 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 :

<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 :

# Activer mod_deflate
sudo a2enmod deflate

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

<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>

# Activer la configuration
sudo a2enconf compression
sudo systemctl reload apache2

Cache navigateur :

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

<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>

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

Sécuriser le Panel Kirby

Option 1 : Changer l'URL du panel

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

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

Option 2 : Restreindre par IP

# 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)

# 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 :

vim ~/backup-kirby.sh

#!/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 :

# Éditer la crontab
crontab -e

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

Mises à jour Kirby

Avec Composer :

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

Manuel (téléchargement) :

# 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 :

# 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

   # 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

   # Voir les logs
   sudo tail -50 /var/log/apache2/monsite.com_error.log
   

3. Permissions

   # 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 :

# 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 :

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 :

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

Vider le cache Apache (si mod_cache activé) :

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) :

<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) :

<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
• Configuration
• .htaccess

Outils :

• Kirby CLI - Commandes en ligne
• Kirby Plainkit - Template de départ

Communauté :

• Forum Kirby
• Discord Kirby

---

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 ! 🚀