VirtualHost Virtualmin pour Dolibarr

1. Contexte et problématique

Vous hébergez Dolibarr sur un serveur géré par Webmin / Virtualmin. Votre Dolibarr est accessible via un domaine existant, par exemple demo.votredomaine.fr.

Un module comme SmartInterventions (ou tout autre module disposant d’une PWA) nécessite un sous-domaine dédié avec son propre VirtualHost Apache, dont le DocumentRoot pointe vers un sous-dossier spécifique de votre Dolibarr :

/home/demo/public_html/custom/smartinterventions/pwa

La documentation officielle du module fournit un exemple de VirtualHost Apache générique :

<VirtualHost *:443>
    ServerName interventions.votredomaine.fr
    DocumentRoot /chemin/vers/dolibarr/custom/smartinterventions/pwa
    <Directory /chemin/vers/dolibarr/custom/smartinterventions/pwa>
        AllowOverride All
        Require all granted
    </Directory>
    # + configuration SSL
</VirtualHost>

Le problème : sous Virtualmin, vous ne pouvez pas simplement coller ce bloc dans un fichier de configuration Apache. Virtualmin gère les VirtualHosts à sa manière.

2. Pourquoi les solutions évidentes ne marchent pas

Quand on utilise Virtualmin, plusieurs approches semblent logiques mais ne fonctionnent pas :

3. La méthode qui fonctionne

La solution est en trois temps :

1. Créer un Virtual Server dans Virtualmin pour le sous-domaine. Virtualmin va créer un répertoire home inutile — ce n’est pas grave.
2. Modifier les directives Apache de ce nouveau Virtual Server via « Edit Directives » pour changer le DocumentRoot vers le dossier du module Dolibarr existant.
3. Corriger le socket PHP-FPM pour utiliser celui du Virtual Server propriétaire des fichiers (le serveur Dolibarr parent), sans quoi PHP ne pourra pas lire les fichiers.

4. Procédure pas à pas

interventions.votredomaine.fr  →  IP_DU_SERVEUR

# Trouver le socket du serveur Dolibarr (ex: demo.votredomaine.fr)
grep -r "SetHandler.*sock" /etc/apache2/sites-enabled/demo.votredomaine.fr.conf

SetHandler proxy:unix:/run/php/17665503967645.sock|fcgi://127.0.0.1

# AVANT (généré par Virtualmin)
DocumentRoot /home/interveti/public_html
<Directory /home/interveti/public_html>

# APRÈS (modifié par vous)
DocumentRoot /home/demo/public_html/custom/smartinterventions/pwa
<Directory /home/demo/public_html/custom/smartinterventions/pwa>

# AVANT (socket du nouveau Virtual Server - n'a PAS les droits sur les fichiers)
<FilesMatch \.php$>
    SetHandler proxy:unix:/run/php/1772686153847109.sock|fcgi://127.0.0.1
</FilesMatch>

# APRÈS (socket du serveur Dolibarr parent - propriétaire des fichiers)
<FilesMatch \.php$>
    SetHandler proxy:unix:/run/php/17665503967645.sock|fcgi://127.0.0.1
</FilesMatch>

<Files "api.php">
    AcceptPathInfo On
</Files>

SuexecUserGroup #1002 #1002
ServerName interventions.votredomaine.fr
DocumentRoot /home/demo/public_html/custom/smartinterventions/pwa
ErrorLog /var/log/virtualmin/interventions.votredomaine.fr_error_log
CustomLog /var/log/virtualmin/interventions.votredomaine.fr_access_log combined
DirectoryIndex index.php index.htm index.html
<Directory /home/demo/public_html/custom/smartinterventions/pwa>
    Options -Indexes +IncludesNOEXEC +SymLinksIfOwnerMatch
    Require all granted
    AllowOverride All Options=ExecCGI,Includes,IncludesNOEXEC,Indexes,MultiViews,SymLinksIfOwnerMatch
</Directory>
<Files "api.php">
    AcceptPathInfo On
</Files>
ProxyPass /.well-known !
RemoveHandler .php
RemoveHandler .php8.4
<FilesMatch \.php$>
    SetHandler proxy:unix:/run/php/SOCKET_DU_SERVEUR_DOLIBARR.sock|fcgi://127.0.0.1
</FilesMatch>
SSLEngine on
SSLCertificateFile /etc/ssl/virtualmin/XXXXXX/ssl.cert
SSLCertificateKeyFile /etc/ssl/virtualmin/XXXXXX/ssl.key
SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
SSLCACertificateFile /etc/ssl/virtualmin/XXXXXX/ssl.ca

5. Certificat SSL avec Let’s Encrypt

Virtualmin génère un certificat SSL à la création du Virtual Server. Il demande souvent automatiquement un certificat Let’s Encrypt si le DNS pointe déjà vers le serveur.

Vérifiez en cliquant sur le cadenas dans votre navigateur :

• Émetteur : doit indiquer « Let’s Encrypt » (R10, R11 ou R12)
• Domaine : doit correspondre à votre sous-domaine
• Expiration : environ 90 jours après la création

Si le certificat est auto-signé, demandez-en un manuellement :

• Virtualmin → Virtual Server → Server Configuration → SSL Certificate → Let’s Encrypt
• Cliquez sur Request Certificate

6. Configuration PHP-FPM : le piège du socket

Comprendre le problème

Virtualmin isole chaque Virtual Server avec son propre processus PHP-FPM. Voici ce qui se passe :

Le socket de interveti ne peut pas lire les fichiers de demo → erreur 404 / « Primary script unknown » sur tous les fichiers PHP.

La solution

Dans les directives du VirtualHost, remplacez le socket PHP-FPM par celui du serveur propriétaire des fichiers :

# Remplacer le socket du nouveau serveur par celui du serveur Dolibarr
<FilesMatch \.php$>
    SetHandler proxy:unix:/run/php/SOCKET_DU_SERVEUR_DOLIBARR.sock|fcgi://127.0.0.1
</FilesMatch>

7. Configuration de l’API SmartAuth

Le module SmartInterventions utilise SmartAuth, un système d’authentification JWT indépendant de l’API standard de Dolibarr. La PWA appelle l’endpoint /api.php/login, /api.php/home, etc.

Architecture de l’API

Le fichier api.php est situé directement dans le dossier pwa/ (le DocumentRoot). Il utilise le routeur personnalisé de SmartAuth (RouteController) qui parse l’action depuis le PATH_INFO de l’URL :

# Requête du navigateur :
POST https://interventions.votredomaine.fr/api.php/login

# Apache sert le fichier pwa/api.php avec PATH_INFO = /login
# Le routeur SmartAuth extrait "login" et appelle AuthController::login()

Ce qu’il ne faut PAS faire

## FAUX - ne faites PAS cela
ProxyPass /api.php/ https://demo.votredomaine.fr/api/index.php/
ProxyPassReverse /api.php/ https://demo.votredomaine.fr/api/index.php/

Ce qu’il faut faire

Le fichier api.php étant déjà dans le DocumentRoot, il suffit de :

1. Utiliser le bon socket PHP-FPM (celui du serveur Dolibarr, voir section 6)
2. Activer AcceptPathInfo pour que Apache transmette /login comme PATH_INFO à api.php

<Files "api.php">
    AcceptPathInfo On
</Files>

Aucun ProxyPass, Alias ou RewriteRule n’est nécessaire. Apache sert api.php directement.

8. Règles de réécriture (.htaccess)

Certains modules Dolibarr nécessitent des règles de réécriture pour router les appels API. La doc officielle donne un exemple nginx :

# Directive nginx (documentation officielle)
location ~ {
    try_files $uri $uri/ /api.php/$1?$args;
}

L’équivalent Apache, dans un fichier .htaccess à la racine du dossier pwa :

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ /api.php/$1 [QSA,L]

9. Vérification et tests

Test navigateur

Ouvrez https://interventions.votredomaine.fr. Vous devez voir l’interface de connexion du module.

Test de l’API

Ouvrez les DevTools du navigateur (F12 → onglet Network). Tentez une connexion. Vous devez voir :

• Une requête POST vers /api.php/login
• Un code de réponse 200 (succès) ou 401 (identifiants incorrects)
• Pas d’erreur 400, 404 ou 500

Test en ligne de commande (SSH)

# Tester l'API depuis le serveur
curl -s -X POST https://interventions.votredomaine.fr/api.php/login   -H "Content-Type: application/json"   -d '{"email":"user@example.com","password":"test"}' | head -c 200

Vérifications complémentaires

• Le cadenas SSL est présent et valide (Let’s Encrypt)
• La page se charge sans erreur 403 ou 404
• La connexion au module fonctionne avec des identifiants valides

En cas de problème

10. Récapitulatif