Procédure de sauvegarde et de mise à jour de BookStack
1. Préparation
Utilisez un compte avec sudo. Conservez toujours une copie des sauvegardes hors de la VM. La procédure officielle couvre la base de données et les fichiers propres à l'instance.
cd /var/www/bookstack
git status --short
php -v
composer --version
sudo mysql -Nse 'SELECT VERSION();'
grep -q '^APP_KEY=.\+' .env && echo "APP_KEY présent" || echo "APP_KEY ABSENT"
df -h /
- Ne continuez pas si
APP_KEYest absent. Depuis la v26.09, une clé est obligatoire, et sans elle l'accès renvoie une erreur. - Ne générez pas de nouvelle clé sans vérifier l'existante. Conservez toujours l'ancienne valeur dans une restauration, car elle protège notamment les identifiants MFA.
- Notez les fichiers non suivis par Git, comme
.env.bak, mais ne les publiez pas. - Vérifiez les prérequis, par exemple PHP 8.2 minimum pour la v25.02 et MySQL 8.0 ou MariaDB 10.6 pour la v25.12.
2. Sauvegarde
Le umask 077 ne sert qu'à protéger la sauvegarde. Remettez-le à 022 à l'étape suivante. C'est ce réglage resté actif qui a rendu des fichiers illisibles pour Apache après la mise à jour.
cd /var/www/bookstack
umask 077
BACKUP_DIR="$HOME/bookstack-backup-$(date +%F_%H%M)"
mkdir -p "$BACKUP_DIR"
mysqldump --no-tablespaces -u bookstack -p bookstack \
> "$BACKUP_DIR/bookstack.sql"
Saisissez le mot de passe MySQL à l'invite. Si vous ne le retrouvez pas, il se trouve dans DB_PASSWORD du fichier .env. Ne le partagez pas.
-p bookstack:-pdemande le mot de passe, et le dernierbookstackest le nom de la base.--no-tablespacesévite l'erreurPROCESS privilege. Elle avait bloqué votre première sauvegarde.- Si la commande échoue, arrêtez-vous : la redirection
>peut avoir créé un fichier vide.
Archivez ensuite les fichiers de l'instance :
tar -C /var/www/bookstack -czf "$BACKUP_DIR/bookstack-files.tar.gz" \
.env public/uploads storage/uploads themes
umask 022
umask
La dernière commande doit afficher 0022. Les chemins de tar sont relatifs, donc il faut lancer la commande depuis /var/www/bookstack ou utiliser -C.
Vérifiez les deux fichiers :
ls -lh "$BACKUP_DIR"
test -s "$BACKUP_DIR/bookstack.sql" && echo "SQL non vide"
tar -tzf "$BACKUP_DIR/bookstack-files.tar.gz" | head
Copiez enfin le dossier de sauvegarde hors de la VM. L'archive contient .env, donc des secrets : protégez-la.
3. Contrôles avant la mise à jour
Vérifiez les droits du cache, la cause de vos erreurs Failed to clear cache :
cd /var/www/bookstack
umask
command -v setfacl || sudo apt install acl
php artisan cache:clear
Si cache:clear échoue, corrigez le cache avant de lancer composer install : le script Composer le lance à la fin. Les ACL donnent l'écriture à votre utilisateur et à www-data sur le cache seulement, y compris pour les futurs fichiers :
sudo setfacl -R -m u:$USER:rwX,u:www-data:rwX storage/framework/cache
sudo find storage/framework/cache -type d \
-exec setfacl -m d:u:$USER:rwx,d:u:www-data:rwx {} +
php artisan cache:clear
Si setfacl est absent, installez d'abord le paquet acl. Ne faites pas de chmod -R 777.
Lisez aussi les instructions propres aux versions que vous franchissez. Elles signalent par exemple des changements de droits, de prérequis ou de sécurité :
- Si vous passez à la v26.05 ou plus, le dossier
storage/fontsdoit être accessible en écriture par le serveur web. Des erreurs lors des exports PDF indiquent ce problème. - Les mises à jour importantes de base de données, comme la v25.11, peuvent allonger la migration.
4. Mise à jour
Lancez les commandes une par une depuis /var/www/bookstack, avec umask 022 actif. Utilisez votre utilisateur habituel, sans sudo pour Git ou Composer.
cd /var/www/bookstack
umask 022
git pull origin release
composer install --no-dev
Arrêtez-vous si Git ou Composer affiche une erreur, y compris Script @php artisan cache:clear ... returned with error code 1. Corrigez-la avant la migration. Puis :
php artisan migrate
php artisan cache:clear
php artisan config:clear
php artisan view:clear
À l'invite APPLICATION IN PRODUCTION, confirmez Yes seulement après avoir vérifié les sauvegardes. Si une migration échoue, relevez le message d'erreur. Ne relancez pas la commande en boucle.
5. Correction des droits après mise à jour
Faites cette étape à chaque fois. Elle rend le code lisible par Apache sans lui donner l'écriture, et c'est ce qui a résolu votre erreur 500.
cd /var/www/bookstack
umask 022
sudo chmod -R a+rX app bootstrap database lang public resources routes themes vendor
sudo chmod a+r artisan composer.json composer.lock version
sudo -u www-data find app bootstrap database lang public resources routes themes vendor \
! -readable -print 2>/dev/null | head
sudo -u www-data php -r 'require "vendor/autoload.php"; echo "Autoload OK\n";'
La commande find ne doit rien afficher et Autoload OK doit apparaître. L'application doit avoir l'écriture seulement sur storage, bootstrap/cache et public/uploads. Vérifiez ces droits :
sudo -u www-data test -w storage/logs && echo "logs OK"
sudo -u www-data test -w storage/framework/cache && echo "cache OK"
sudo -u www-data test -w public/uploads && echo "uploads OK"
sudo -u www-data test -w storage/uploads && echo "storage/uploads OK"
sudo -u www-data test -r .env && echo ".env lisible"
Ne donnez pas la lecture à tous sur .env : il doit rester lisible par www-data, pas par tous les utilisateurs. Restreignez aussi les copies comme .env.bak : chmod 640 .env.bak.
6. Tests finaux
curl -sS -o /dev/null -w 'HTTPS : %{http_code}\n' https://doc-trevette.duckdns.org/
curl --noproxy '*' -sS -o /dev/null -w 'HTTP : %{http_code} -> %{redirect_url}\n' http://doc-trevette.duckdns.org/
sudo apache2ctl configtest
sudo certbot renew --dry-run
sudo tail -n 20 /var/log/apache2/error.log
Résultats attendus :
- HTTPS :
200, ou une redirection vers la page de connexion. - HTTP :
301vers l'adresse HTTPS. - Apache :
Syntax OK. L'avertissementAH00558est sans gravité. - Certbot : renouvellement simulé réussi.
- Journal : aucune nouvelle erreur
Permission deniedaprès l'heure de la mise à jour.
Ouvrez ensuite BookStack dans le navigateur. Connectez-vous, ouvrez une page avec des images, enregistrez une modification et téléversez une image.
7. En cas d'erreur 500
- Lisez l'erreur Apache récente, sans modifier les droits au hasard :
sudo tail -n 30 /var/log/apache2/error.log. - Regardez aussi
storage/logs/laravel.log. Comparez l'heure de chaque ligne avec l'heure de votre dernier essai, car les anciennes erreurs restent dans le fichier. Permission deniedsur un fichier devendorouapp: reprenez la section 5.umaskdoit afficher0022.- Erreur après la mise à jour vers la v26.09 ou plus : vérifiez que
APP_KEYest présent, sans l'afficher. - En dernier recours, restaurez les sauvegardes. Le fichier
.envsauvegardé conserve l'APP_KEYd'origine. Si vous restaurez dans une nouvelle version, lancez ensuitephp artisan migrate:
mysql -u bookstack -p bookstack < ~/bookstack-backup-AAAA-MM-JJ_HHMM/bookstack.sql
Si l'URL change, mettez APP_URL exactement à la nouvelle adresse dans .env, par exemple https://doc-trevette.duckdns.org. Lancez ensuite la commande « Update System URL » de BookStack sur la base. Faites cette opération seulement après une sauvegarde récente.
8. Rappel des corrections
| Problème rencontré | Cause | Correction |
|---|---|---|
Access denied ... using password: NO |
Mot de passe MySQL non saisi | Utiliser -p et saisir le mot de passe à l'invite |
PROCESS privilege |
Droit MySQL supplémentaire demandé par mysqldump |
Ajouter --no-tablespaces |
tar: Cannot stat |
Commande lancée hors de /var/www/bookstack |
cd d'abord, ou tar -C |
Failed to clear cache |
Fichiers de cache créés par www-data |
ACL sur storage/framework/cache |
| Erreur 500 après mise à jour | Fichiers illisibles par Apache à cause de umask 077 |
umask 022 puis chmod -R a+rX ciblé |
HTTP encore accessible en 200 |
RewriteEngine On manquait dans le vhost du port 80 |
L'ajouter avant la règle de redirection Certbot |