config.php Nextcloud : emplacement, syntaxe et modifications sûres

Le fichier Nextcloud config.php contient les paramètres système de l'instance : base de données, domaine, répertoire de données, cache, proxy, journalisation et autres réglages d'infrastructure. Une simple erreur de syntaxe peut rendre l'application indisponible. Une valeur correcte placée dans le mauvais fichier peut, elle, ne produire aucun effet visible.

La méthode sûre tient en six actions : trouver le répertoire réellement chargé, lire la configuration fusionnée, sauvegarder hors du dossier actif, modifier une seule clé, valider la syntaxe, puis tester l'effet et le retour arrière.

Où se trouve config.php dans Nextcloud ?

Dans une installation classique à partir de l'archive Nextcloud, le fichier principal se trouve dans le sous-dossier config/ du répertoire de l'application :

<racine-nextcloud>/config/config.php

Le chemin absolu dépend du mode d'installation. La documentation officielle des images Docker place la configuration locale dans /var/www/html/config/ à l'intérieur du conteneur. Le paquet Snap utilise le dossier /var/snap/nextcloud/current/, puis le chemin relatif nextcloud/config/config.php. Une distribution, une image d'hébergement ou un orchestrateur peut utiliser un autre montage.

La variable d'environnement NEXTCLOUD_CONFIG_DIR peut aussi remplacer le dossier config/ situé dans la racine web. Elle doit être cohérente pour le serveur web et les commandes CLI. Vérifiez donc le paquet et le conteneur réellement utilisés avant d'éditer un chemin trouvé dans un ancien tutoriel.

• Archive Nextcloud : fichier config/config.php sous la racine de l'application, modifié sous le compte d'exploitation ou avec occ.
• Image Docker officielle : dossier /var/www/html/config/ dans le conteneur, normalement conservé dans un volume ou un montage persistant.
• Snap officiel : dossier /var/snap/nextcloud/current/, avec nextcloud.occ comme interface de commande.
• Dossier personnalisé : chemin défini par NEXTCLOUD_CONFIG_DIR, selon la procédure propre au service.

Le guide Nextcloud présente l'architecture générale d'une instance. Pour une modification précise, la documentation du mode d'installation reste prioritaire sur un chemin générique.

Quelle syntaxe respecter dans config.php ?

config.php est un fichier PHP qui définit un tableau nommé $CONFIG. Chaque paramètre associe une clé à une valeur. Les éléments sont séparés par des virgules.

<?php
$CONFIG = [
    'loglevel' => 2,
    'maintenance' => false,
    'logtimezone' => 'Europe/Paris',
    'trusted_domains' => [
        'cloud.example.fr',
    ],
];

Le type de chaque valeur compte :

• une chaîne est entourée de guillemets simples ou doubles ;
• un booléen utilise true ou false, sans guillemets ;
• un entier comme 2 reste sans guillemets ;
• une liste utilise un tableau PHP ;
• une classe PHP contenant des antislashs doit conserver l'échappement attendu par l'exemple officiel.

'false' est une chaîne de caractères, pas le booléen false. De même, '2' n'est pas l'entier 2. Nextcloud peut corriger certains formats, mais sa documentation précise que ce mécanisme n'est pas infaillible.

Pourquoi une valeur correcte peut-elle être ignorée ?

Nextcloud charge config.php, puis fusionne les fichiers dont le nom se termine par .config.php dans le même répertoire. Les valeurs de ces fichiers supplémentaires ont toujours priorité sur celles du fichier principal.

Ainsi, ce réglage peut sembler correct dans config.php :

'loglevel' => 2,

Mais un fichier logging.config.php contenant 'loglevel' => 0 rendra 0 effectif. La commande suivante affiche la configuration système après fusion :

sudo -u www-data php occ config:list system

Le compte, le binaire PHP, le chemin vers occ et le wrapper changent selon l'installation. Dans Docker, la commande s'exécute normalement dans le conteneur. Avec Snap, l'outil est nextcloud.occ. Utilisez le mécanisme prévu par votre paquet au lieu de copier aveuglément sudo -u www-data.

Une sauvegarde mal nommée peut aussi modifier la production. Un fichier comme backup.config.php placé dans config/ est chargé et peut écraser les valeurs de config.php. Stockez les copies dans un répertoire non interprété, par exemple un dossier de sauvegarde protégé hors de config/.

Faut-il éditer le fichier ou utiliser occ ?

Les deux méthodes sont valides dans leur périmètre. Le choix dépend du type de valeur, du paquet et de la manière dont la configuration est gérée.

• Lire la valeur fusionnée : occ config:list system évite d'oublier un fichier supplémentaire.
• Changer une valeur simple : occ config:system:set limite les erreurs de syntaxe si le fichier est inscriptible.
• Modifier un tableau imbriqué : l'édition directe reste souvent plus lisible, tandis que la commande demande de maîtriser les indices.
• Déploiement géré par fichiers : modifiez la source d'automatisation, car une commande locale peut être écrasée au redéploiement.
• Configuration en lecture seule : passez par le système qui fournit le fichier, car l'écriture avec occ sera refusée ou ne sera pas durable.

Pour une valeur scalaire, occ oblige à déclarer le type :

sudo -u www-data php occ config:system:set loglevel --type=integer --value=2

Vérifiez ensuite la valeur effective :

sudo -u www-data php occ config:system:get loglevel

Pour retirer une clé ajoutée volontairement :

sudo -u www-data php occ config:system:delete loglevel

Supprimer une clé ne signifie pas toujours désactiver la fonction. Nextcloud reprend alors sa valeur par défaut ou une valeur définie dans un autre fichier. Avant une suppression, consultez le paramètre officiel et recherchez ses occurrences dans tous les fichiers actifs.

N'utilisez pas occ config:list system --private dans un ticket ou un canal partagé. Cette option affiche la configuration fusionnée avec ses valeurs privées. Le fichier peut contenir le mot de passe de base de données, le secret, des clés de stockage objet, des identifiants de messagerie et d'autres données à protéger.

Quelle procédure appliquer avant une modification ?

Voici une séquence qui limite l'interruption et fournit un retour arrière vérifiable.

1. Identifier la source de configuration

Confirmez le mode d'installation, la racine Nextcloud et l'éventuelle variable NEXTCLOUD_CONFIG_DIR. Inventoriez les fichiers *.config.php réellement chargés. Ne modifiez pas un fichier généré par Docker, Kubernetes, un panneau d'hébergement ou un outil de gestion de configuration sans comprendre sa source.

2. Capturer l'état utile sans exposer les secrets

Notez la clé, sa valeur attendue, sa valeur actuelle et le fichier qui la fournit. Préférez config:system:get <clé> ou une lecture ciblée. Une exportation complète doit être chiffrée, à accès limité et supprimée selon la politique de sauvegarde.

3. Sauvegarder hors du dossier actif

Copiez uniquement les fichiers nécessaires vers un emplacement qui ne se termine pas par .config.php dans le dossier chargé. Conservez leurs propriétaires, droits et date. Si la modification concerne un déploiement automatisé, sauvegardez aussi la source déclarative, pas seulement le fichier rendu dans le conteneur. Pour protéger l'instance complète, le guide de sauvegarde Nextcloud distingue la configuration, les données, la base et les applications à restaurer ensemble.

4. Modifier une seule intention

Évitez de changer le cache, le proxy et le domaine dans le même lot. Une modification atomique simplifie l'analyse. Pour Redis, par exemple, le guide cache APCu et Redis dans Nextcloud détaille les extensions, sockets et tests propres à ce composant.

5. Vérifier la syntaxe PHP

Avant de recharger l'application, contrôlez le fichier modifié :

php -l /chemin/vers/nextcloud/config/config.php

Le résultat No syntax errors detected valide uniquement la grammaire PHP. Il ne vérifie ni le nom du paramètre, ni son type métier, ni la disponibilité d'un service externe. Utilisez le même environnement PHP que celui prévu par le paquet lorsque c'est possible.

6. Vérifier la valeur fusionnée et l'effet attendu

Relisez la clé avec occ, ouvrez l'interface d'administration, puis testez la fonction directement concernée. Un changement de tâche de fond se valide avec le parcours décrit dans le guide cron Nextcloud. Un changement de proxy se valide avec les en-têtes et les URL du guide reverse proxy Nextcloud.

7. Tester le retour arrière

Restaurez la valeur précédente ou le fichier sauvegardé, relancez les contrôles de syntaxe et confirmez que la configuration fusionnée revient à l'état attendu. Une copie qui n'a jamais été restaurée est seulement une hypothèse de secours.

Comment diagnostiquer les erreurs fréquentes ?

L'interface affiche une erreur 500 après l'édition

Commencez par php -l sur chaque fichier touché. Cherchez une virgule manquante, un crochet non fermé, un guillemet orphelin ou un antislash mal échappé. Restaurez le dernier fichier valide si l'accès à occ est lui-même cassé.

La modification n'a aucun effet

Affichez la configuration fusionnée avec occ config:list system. Recherchez un fichier *.config.php prioritaire, une variable NEXTCLOUD_CONFIG_DIR, un montage de conteneur ou un cache OPcache qui retarde la prise en compte. La documentation Nextcloud indique que la détection des changements peut prendre environ deux secondes dans un environnement PHP standard et environ soixante secondes dans de nombreux paquets préconfigurés.

La commande occ utilise le mauvais environnement

Le PHP du terminal peut différer de PHP-FPM ou du module Apache. Comparez leur version et leurs extensions. Exécutez occ avec le compte du serveur HTTP et le binaire PHP attendu par l'installation. L'absence d'APCu en CLI ou une version PHP différente peut provoquer un résultat qui ne représente pas le service web.

occ refuse d'écrire la configuration

Vérifiez les droits, le propriétaire et config_is_read_only. Lorsque ce paramètre vaut true, Nextcloud interdit l'écriture du fichier. La documentation précise aussi qu'une mise à jour demande de rendre la configuration à nouveau inscriptible et de remettre ce réglage à false pendant l'opération. Sur une image gérée, suivez d'abord la procédure du fournisseur, car le fichier peut être régénéré.

Une valeur change après un redémarrage ou un redéploiement

La source de vérité se trouve probablement hors du fichier édité : variable d'environnement, secret Docker, volume, manifeste d'orchestration, script d'entrée ou gestionnaire de configuration. Corrigez cette source, puis recréez le service et vérifiez la valeur fusionnée. Une modification directe dans un conteneur éphémère ne constitue pas un changement durable.

Conclusion

Une modification sûre de config.php ne se résume pas à trouver une ligne dans un tutoriel. Il faut identifier le répertoire chargé, respecter le type PHP, tenir compte des fichiers *.config.php, sauvegarder hors du dossier actif, valider la syntaxe et contrôler la valeur fusionnée avec occ.

Sur une offre administrée, demandez qui possède la configuration, quelles clés restent accessibles au client et comment sont réalisés la sauvegarde, le test et le retour arrière avant toute intervention.

Découvrir l'offre Nextcloud GaprodNextcloud géré avec administration de l'infrastructure

Sources officielles

• Nextcloud 35 Administration Manual : paramètres de configuration
• Nextcloud 35 Administration Manual : utilisation de occ
• Fichier config.sample.php officiel de Nextcloud 35
• Image Docker officielle Nextcloud : volumes, config.php et occ
• Paquet Snap officiel Nextcloud : configuration et commandes