Setup

Guide d'installation

Comment deployer QuoteNode sur votre propre infrastructure avec Docker Compose.

Installation

QuoteNode fonctionne comme un ensemble de conteneurs Docker. Vous n’avez pas besoin d’installer Java, Node.js ni PostgreSQL directement sur votre machine. Docker s’occupe de tout.

Prerequis

Docker Engine 24.0 ou version ulterieure (installer Docker)
Docker Compose v2 (inclus dans les versions modernes de Docker Desktop et Docker Engine)
Une machine avec au moins 2 Go de RAM et 10 Go d’espace disque libre

Pour verifier votre environnement :

docker --version        # Doit afficher 24.0+
docker compose version  # Doit afficher v2.x

Demarrage rapide (5 minutes)

Cette procedure lance QuoteNode sur votre machine locale pour evaluation. Pas pour la production. Voir plus bas pour les exigences de production.

Etape 1 — Creer un repertoire de projet

mkdir quotenode && cd quotenode

Etape 2 — Creer le fichier de configuration

Creer un fichier .env avec le minimum de reglages requis :

# Base de donnees
DB_URL=jdbc:postgresql://postgres:5432/quotenode
DB_USERNAME=quotenode
DB_PASSWORD=remplacez-moi-par-un-mot-de-passe-aleatoire-de-32-caracteres
DB_NAME=quotenode

# ============================================================
# SECRETS DE SECURITE — A LIRE AVANT DE CONTINUER
# Ces valeurs sont UNIQUES pour votre installation.
# Si vous perdez ce fichier, vous ne pourrez PAS regenerer les memes secrets.
# SAUVEGARDEZ CE FICHIER et conservez-en une copie securisee.
# ============================================================
DB_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
TIMING_TOKEN_SECRET=remplacez-moi-par-un-secret-timing-de-32-caracteres-minimum
PUBLIC_LINK_PASSWORD_SESSION_SECRET=remplacez-moi-par-un-secret-session-de-32-caracteres-minimum

# Domaine (pour CORS et Caddy)
CORS_ALLOWED_ORIGINS=http://localhost
DOMAIN=localhost

# Logging
LOG_LEVEL=INFO
SPRING_PROFILES_ACTIVE=prod

Sauvegardez votre fichier .env immediatement. Les secrets ci-dessus sont uniques a cette installation. Si vous perdez ce fichier, vous ne pourrez pas regenerer exactement les memes valeurs. Sans le DB_ENCRYPTION_KEY d’origine, les donnees chiffrees (codes MFA, mot de passe SMTP, cles API) deviennent definitivement illisibles. Copiez ce fichier dans un endroit sur. Pour la production, envisagez aussi d’imprimer les secrets et de les conserver dans un coffre physique.

Etape 3 — Creer le fichier Docker Compose

Creer un fichier docker-compose.yml :

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME}"]
      interval: 10s
      timeout: 5s
      retries: 10
    restart: unless-stopped

  gotenberg:
    image: gotenberg/gotenberg:8
    environment:
      LOG_LEVEL: info
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  backend:
    image: ghcr.io/lesisty7/quotenode/quotenode-api:latest
    depends_on:
      postgres: { condition: service_healthy }
      gotenberg: { condition: service_healthy }
    env_file: .env
    environment:
      SPRING_PROFILES_ACTIVE: prod
      JOBS_MODE: web
      PDF_ENABLED: "true"
      PDF_GOTENBERG_URL: http://gotenberg:3000
    volumes:
      - backend_uploads:/app/data/uploads
      - backend_pdfs:/app/data/pdfs
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 45s
    restart: unless-stopped

  frontend:
    image: ghcr.io/lesisty7/quotenode/quotenode-frontend:latest
    depends_on:
      backend: { condition: service_healthy }
    ports:
      - "80:80"
      - "443:443"
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:80/"]
      interval: 15s
      timeout: 5s
      retries: 3
    restart: unless-stopped

volumes:
  postgres_data:
  backend_uploads:
  backend_pdfs:

Etape 4 — Demarrer QuoteNode

docker compose up -d

Docker telecharge les images de conteneurs. Lors du premier lancement, cela prend quelques minutes. Vous pouvez suivre le demarrage avec :

docker compose logs -f backend

Attendez l’apparition d’une ligne du type Started QuoteNodeApplication. Cela signifie que le backend est pret.

Etape 5 — Ouvrir QuoteNode

Ouvrez http://localhost dans votre navigateur.

Identifiants par defaut :

Champ	Valeur
Email	`[email protected]`
Mot de passe	`Admin123!`

Changez le mot de passe par defaut immediatement apres la premiere connexion (Settings > My Profile > Change Password).

Que tourne-t-il actuellement ?

Apres docker compose up, vous avez 4 conteneurs :

Conteneur	Role	RAM
`postgres`	Stocke toutes vos donnees	~256 MB
`backend`	Serveur API Java et logique metier	~512 MB – 1.5 GB
`gotenberg`	Convertit HTML en PDF (base Chromium)	~200 MB
`frontend`	Sert l’interface web et le reverse proxy	~20 MB

Total : environ 1.5 – 2.5 GB de RAM.

Commandes frequentes

# Verifier que tous les services tournent
docker compose ps

# Voir les logs de tous les services
docker compose logs -f

# Voir uniquement les logs du backend
docker compose logs -f backend

# Arreter QuoteNode
docker compose down

# Mettre a jour vers la derniere version
docker compose pull && docker compose up -d

Garder vos secrets en securite

Votre fichier .env contient des secrets cryptographiques uniques a votre installation. Comprendre ce que chaque secret protege vous aide a planifier votre strategie de backup :

Secret	Ce qu’il protege	Si perdu
`DB_PASSWORD`	Acces a la base de donnees	Recuperable — reinitialisable avec les outils d’administration PostgreSQL
`DB_ENCRYPTION_KEY`	Codes MFA (TOTP), mot de passe SMTP, cle API FX — et tous les champs PII quand `ENCRYPT_PII=true`	Definitivement illisible — ces champs ne peuvent pas etre dechiffres sans la cle d’origine
`TIMING_TOKEN_SECRET`	Tokens anti-timing attack	Regenerable — les tokens existants deviennent invalides, les utilisateurs se reconnectent
`PUBLIC_LINK_PASSWORD_SESSION_SECRET`	Sessions des liens publics	Regenerable — les sessions actives expirent, les liens continuent de fonctionner

Le secret critique est DB_ENCRYPTION_KEY. Tous les autres secrets peuvent etre regeneres avec un impact limite. Mais DB_ENCRYPTION_KEY protege les donnees chiffrees au repos. Si vous le perdez, ces champs sont perdus pour toujours. Si ENCRYPT_PII=true etait active, cela inclut aussi toutes les donnees personnelles de clients, contacts, fournisseurs et utilisateurs (noms, emails, telephones, identifiants fiscaux). Sans chiffrement PII actif, vos donnees metier restent stockees en clair et restent accessibles.

Pour les systemes de production, nous recommandons :

Conserver une copie de .env dans un gestionnaire de mots de passe (1Password, Bitwarden, etc.)
Pour une securite maximale, imprimer les secrets et conserver l’impression dans un coffre physique
Ne jamais committer .env dans le controle de version

Recuperation si `.env` est perdu

Si vous perdez votre fichier .env mais disposez d’un backup de base non chiffre (mode de backup par defaut), vous pouvez restaurer vos donnees :

Creez un nouveau .env avec de nouveaux secrets
Restaurez la base depuis votre backup (pg_dump / pg_restore)
Toutes les donnees metier (clients, offres, produits, utilisateurs) restent totalement accessibles
Seuls quelques champs sont perdus : codes MFA (les utilisateurs devront se reinscrire), mot de passe SMTP (a ressaisir dans les reglages), cle API FX (a ressaisir). Si ENCRYPT_PII=true etait active, toutes les donnees personnelles (noms, emails, telephones, identifiants fiscaux) seront aussi perdues. Il faut bien mesurer ce choix avant d’activer le chiffrement PII.

Si vos backups sont chiffres via BACKUP_GPG_RECIPIENT, vous avez d’abord besoin de la cle privee GPG pour les dechiffrer.

Deploiement de production

Pour la production, vous devez :

Generer de vrais secrets. N’utilisez jamais les valeurs d’exemple ci-dessus en production :

# Generer une cle hexadecimale de 64 caracteres pour le chiffrement de la base
openssl rand -hex 32

# Generer des secrets aleatoires pour les tokens
openssl rand -base64 32

Configurer un domaine avec HTTPS. Renseignez DOMAIN et CORS_ALLOWED_ORIGINS avec votre vrai domaine. Le conteneur frontend (Caddy) obtient automatiquement les certificats Let’s Encrypt.
Configurer l’e-mail. Choisissez l’un de ces deux chemins :

Recommande : configurer SMTP plus tard dans Settings > Email SMTP directement dans QuoteNode. Dans le code actuel, les reglages SMTP tenant sont stockes en base, et le mot de passe est chiffre avant persistance. Cela evite de placer le mot de passe mail dans docker-compose.yml ou .env.
Fallback : si vous voulez SMTP operationnel avant la premiere connexion admin, configurez-le dans .env :

SMTP_HOST=smtp.votre-fournisseur.fr
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=votre-mot-de-passe-smtp
SMTP_AUTH=true
SMTP_STARTTLS=true

Si vous choisissez la voie du panneau d’administration, gardez DB_ENCRYPTION_KEY sauvegarde avec soin. Le mot de passe SMTP stocke est chiffre avec la meme cle applicative.

Sauvegardez votre fichier .env avant toute autre chose. Voir plus haut Garder vos secrets en securite.
Activez les backups de base de donnees. Voir le guide Sauvegarde et restauration.
Revoyez l’ensemble des reglages. Utilisez la page wiki Reference des variables d’environnement pour la liste complete des variables applicatives, de deploiement et de developpement.

Pour les options de deploiement avancees (Coolify PaaS, backup workers, GeoIP), voir la page wiki Deploiement.

Mise a jour de QuoteNode

Pour mettre a jour vers la derniere version :

docker compose pull && docker compose up -d

Votre fichier .env n’est jamais modifie par les mises a jour. Docker telecharge de nouvelles images, mais votre configuration et vos donnees restent intactes. Ne supprimez pas et ne recreez pas .env pendant les mises a jour. Les memes secrets doivent rester valides pendant toute la vie de l’installation.

Les migrations de schema de base se lancent automatiquement au demarrage du backend. Aucune migration manuelle n’est necessaire.

Depannage

Le backend ne demarre pas

Verifiez les logs : docker compose logs backend. Problemes frequents :

Base pas encore prete — le backend attend que PostgreSQL devienne healthy. Si PostgreSQL demarre lentement, le backend retente automatiquement.
Secrets invalides — DB_ENCRYPTION_KEY doit contenir exactement 64 caracteres hexadecimaux. DB_PASSWORD doit correspondre entre le backend et le conteneur PostgreSQL.
Conflit de port — si le port 80 ou 443 est deja utilise, modifiez le mapping ports dans docker-compose.yml.

Impossible de se connecter a QuoteNode

Verifiez que tous les conteneurs tournent : docker compose ps
Verifiez que le conteneur frontend est marque “healthy”
Pour un test local sans vrai domaine, utilisez http://localhost et non https://

Mot de passe admin oublie

Utilisez plutot un chemin de recuperation non destructif :

Si SMTP est configure, commencez par le flux de connexion : Mot de passe oublie ?
Si un autre administrateur peut encore se connecter, ouvrez Users dans le panneau d administration et reinitialisez le mot de passe depuis cet ecran. Les administrateurs peuvent definir un nouveau mot de passe et forcer un changement au prochain login.
Si aucun administrateur ne peut se connecter et que le reset par e-mail n est pas disponible, traitez cela comme un incident de recuperation operateur. Restaurez l acces depuis un backup sain ou utilisez la procedure interne de maintenance adaptee a cet environnement.

docker compose down -v n est pas une procedure de reinitialisation de mot de passe. Cette commande recree toute l instance et supprime toutes les donnees persistantes, y compris utilisateurs, offres, clients, reglages et backups locaux. Utilisez-la uniquement dans des environnements locaux jetables lorsque vous voulez volontairement repartir de zero.

Voir aussi : Reinitialiser un mot de passe et Sauvegarde et restauration.

Etapes suivantes

Guide de configuration — branding, templates email, parametres de securite
Reference des variables d’environnement — catalogue complet des variables .env et Docker Compose
Deploiement — Coolify, topologie de production, backup workers
Sauvegarde et restauration — backups automatises avec chiffrement