Installation

Résolution des problèmes d'installation

Problèmes courants de déploiement QuoteNode avec liens, CORS, SMTP, DNS, health checks Docker et secrets perdus.

Résolution des problèmes d’installation

La plupart des problèmes d’installation viennent d’une inadéquation d’URL, d’un SMTP manquant, de ports bloqués ou de secrets perdus. Commencez par l’URL visible dans votre navigateur et progressez vers l’intérieur.

Les liens publics s’ouvrent sur mon ordinateur mais pas pour les clients

Vérifiez quelle URL a été copiée ou envoyée.

http://localhost/... fonctionne uniquement sur la même machine.
http://192.168.x.x/... fonctionne uniquement sur le LAN ou VPN. Le VPN peut être un pont valide pour les équipes internes, mais ce n’est pas une stratégie de lien client public.
https://crm.example.com/... fonctionne publiquement uniquement quand DNS, HTTPS, proxy et pare-feu sont corrects.

Pour les liens clients publics, déployez avec un domaine public en utilisant Serveur public Ubuntu ou Coolify.

Le navigateur affiche des erreurs CORS

CORS_ALLOWED_ORIGINS doit correspondre exactement à l’origine navigateur. Ce sont des origines différentes :

https://crm.example.com
https://www.crm.example.com
http://crm.example.com
https://crm.example.com:8443

Corrigez la variable, redéployez, et réessayez dans une nouvelle session navigateur.

Les emails ne sont pas délivrés

Vérifiez ces points d’abord :

SMTP_HOST et SMTP_PORT sont corrects.
SMTP_AUTH=true quand votre fournisseur nécessite une authentification.
SMTP_STARTTLS=true pour le port 587.
SMTP_USERNAME et SMTP_PASSWORD sont valides.
Le fournisseur autorise la connexion SMTP/app-password.
NOTIFICATIONS_EMAIL_ENABLED=true quand les emails de notification doivent être envoyés.

Le partage manuel de lien public et le téléchargement PDF peuvent toujours fonctionner sans SMTP.

Les liens de préférence de notification sont incorrects

Définissez :

NOTIFICATIONS_PUBLIC_PREFERENCES_URL=https://<frontend-domain>/notifications/preferences

Ne la laissez pas pointer vers localhost dans un déploiement public.

Les conteneurs Docker sont unhealthy

Exécutez :

docker compose ps
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f gotenberg

Causes courantes :

PostgreSQL est encore en cours de démarrage.
DB_PASSWORD diffère entre PostgreSQL et le backend.
DB_ENCRYPTION_KEY est manquant ou malformé.
Gotenberg n’est pas sain, donc la génération PDF ne peut pas démarrer.
Les ports hôtes 80/443 sont déjà utilisés par un autre service.

Après avoir corrigé la configuration, redémarrez le service affecté ou la stack :

docker compose restart backend
docker compose up -d

Mon IP est bloquée — connexion impossible

Deux causes fréquentes : la liste d’autorisation IP a bloqué l’accès ou la protection anti-brute-force a bloqué votre IP après trop de tentatives de connexion échouées.

Blocage par la liste d’autorisation IP

QuoteNode dispose d’une liste d’autorisation IP configurable dans Paramètres > Sécurité > Liste d’autorisation IP (ou via la variable SECURITY_IP_WHITELIST). Lorsqu’elle est activée, elle protège toute la surface d’administration — y compris les écrans de connexion et de 2FA — de sorte qu’une adresse exclue reçoit 403 IP_NOT_ALLOWED et ne peut même pas se connecter. (Les health checks et les liens publics d’offres destinés aux clients restent accessibles.)

Attendez d’abord deux minutes si vous venez de la modifier dans l’application. Une activation ou un resserrement dans l’application est protégé contre le verrouillage : votre session doit le reconfirmer dans une courte fenêtre (120 s par défaut), et si votre adresse actuelle n’est pas couverte, la liste revient automatiquement à la précédente. Un auto-verrouillage accidentel depuis l’écran Sécurité se résout donc de lui-même — attendez et réessayez. (Ce filet de sécurité ne s’applique pas à la variable SECURITY_IP_WHITELIST, qui est appliquée au démarrage.)

Récupération (dérogation opérateur) : si vous êtes toujours verrouillé — p. ex. une SECURITY_IP_WHITELIST opérateur, une liste stockée invalide ou si vous ne pouvez pas attendre — ajoutez cette variable à l’environnement du conteneur backend (.env ou section environment: du docker-compose) et redémarrez :

SECURITY_IP_WHITELIST_FORCE_DISABLE=true

docker compose restart backend

Cela désactive entièrement la liste d’autorisation et permet de se connecter. Une fois connecté, corrigez la liste dans Paramètres > Sécurité, puis supprimez SECURITY_IP_WHITELIST_FORCE_DISABLE et redémarrez.

Ne laissez pas SECURITY_IP_WHITELIST_FORCE_DISABLE=true en production. Cela désactive tout le contrôle d’accès par IP.

Blocage par la protection anti-brute-force

QuoteNode bloque les adresses IP après trop de tentatives de connexion échouées en une heure :

Seuil	Échecs en 1 h	Effet
Soft	10	Délai progressif (1 s par tentative supplémentaire, max. 30 s)
Verrouillage temporaire	20	Bloqué pendant 5 minutes
Verrouillage permanent	50	Bloqué jusqu’au déblocage manuel

Comment débloquer :

Panneau d’administration — un autre administrateur ouvre Paramètres > Tableau de bord sécurité > IP bloquées et clique sur Débloquer.
Attendre — les verrouillages temporaires expirent après SECURITY_TEMP_LOCK_MINUTES (5 minutes par défaut). Les verrouillages permanents n’expirent pas d’eux-mêmes.
Augmenter temporairement les seuils si vous êtes bloqué et qu’aucun autre admin ne peut aider. Ajoutez au .env, redémarrez, connectez-vous, puis supprimez :

SECURITY_MAX_FAILED_LOGINS_SOFT=9999
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK=9999
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK=9999

Rétablissez les valeurs par défaut après avoir récupéré l’accès.

Blocages IP des liens publics

Le limiteur de débit des liens publics bloque les adresses IP qui dépassent les limites de tentatives. Ces blocages sont en mémoire et expirent après PUBLIC_RATE_LIMIT_IP_BLOCK_MINUTES (60 minutes par défaut) ou après un redémarrage du backend.

Le certificat HTTPS ne s’émet pas

Pour les déploiements publics :

Le DNS doit pointer vers le serveur de déploiement.
Les ports 80 et 443 doivent être joignables depuis internet.
Un seul proxy devrait terminer le HTTPS pour le même domaine.
Dans Coolify, attribuez le domaine au service frontend.

J’ai perdu `.env`

Si vous avez perdu .env, arrêtez-vous et évaluez avant de faire tourner les valeurs.

DB_PASSWORD peut généralement être redéfini avec un accès admin PostgreSQL.
TIMING_TOKEN_SECRET et PUBLIC_LINK_PASSWORD_SESSION_SECRET peuvent être régénérés, mais les sessions/tokens existants peuvent expirer.
DB_ENCRYPTION_KEY est critique. Sans la clé originale, les valeurs chiffrées ne peuvent pas être déchiffrées.
Si le chiffrement PII est activé, les champs client/contact chiffrés dépendent de DB_ENCRYPTION_KEY.

Restaurez .env depuis une sauvegarde quand c’est possible.

Récupération si `.env` est perdu mais une sauvegarde de base de données existe

Créez un nouveau .env avec de nouveaux secrets.
Restaurez la base de données depuis votre sauvegarde (pg_dump / pg_restore).
Toutes les données métier (clients, offres, produits, utilisateurs) seront pleinement accessibles.
Seuls quelques champs sont perdus : codes MFA (les utilisateurs se ré-inscrivent), mot de passe SMTP (à resaisir dans les paramètres), clé API FX (à resaisir). Si ENCRYPT_PII=true était activé, les données clients chiffrées sont également perdues.

Si vos sauvegardes sont chiffrées avec age (par défaut), vous avez besoin du fichier d’identité age de votre kit de récupération pour les déchiffrer. Consultez le guide Sauvegarde et Restauration.

Mot de passe admin oublié

Utilisez un chemin de récupération non-destructif :

Si SMTP est configuré, utilisez la page de connexion : Mot de passe oublié ?
Si un autre administrateur peut encore se connecter, ouvrez Utilisateurs dans le panneau admin et réinitialisez le mot de passe.
Si aucun administrateur ne peut se connecter et que le flux de réinitialisation par email est indisponible, restaurez l’accès depuis une sauvegarde connue bonne ou utilisez votre procédure de maintenance interne.

docker compose down -v n’est pas une procédure de réinitialisation de mot de passe. Elle supprime toutes les données — utilisateurs, offres, clients, paramètres et sauvegardes. Utilisez-la uniquement pour les environnements de test jetables.

La vérification de licence échoue

Pour les vrais déploiements, gardez :

LICENSE_SKIP_SIGNATURE_CHECK=false

Si une licence valide échoue toujours, vérifiez que le déploiement a la version d’application attendue et une horloge système synchronisée NTP. Confirmez que la licence correspond à l’édition/version déployée, puis contactez le support ou remplacez le fichier de licence via le chemin opérateur documenté. Ne définissez pas le contournement de signature à true comme contournement de production.