Héberger Kledg avec Docker
Installez Kledg sur votre propre serveur avec le fichier docker-compose.yml du dépôt, ou avec Coolify et Dokploy : variables, HTTPS, sauvegardes, mises à jour et tâches planifiées.
Le dépôt Kledg contient une image Docker de production et un fichier docker-compose.yml prêt à l’emploi : il lance Kledg et sa base Postgres sur un serveur que vous contrôlez, un serveur virtuel chez un hébergeur ou une machine dans vos locaux. Le même fichier sert tel quel avec Coolify et Dokploy.
Pour les autres façons d’héberger Kledg, voir Choisir son hébergement.
Ce que contient docker-compose.yml
- le service
kledg, construit depuis leDockerfiledu dépôt, avec une vérification de santé sur/api/health; - le service
db, PostgreSQL 17, avec sa propre vérification de santé : Kledg ne démarre qu’une fois la base prête ; - le volume
kledg-postgres, pour les données, et le volumekledg-backups, pour les sauvegardes prises avant chaque migration ; - les variables obligatoires, marquées
:?: le déploiement refuse de démarrer sans elles.
Aucun port n’est publié : un reverse proxy (celui de Coolify ou de Dokploy, ou le vôtre) envoie le domaine vers le port 3000 du service kledg.
La base locale de développement est désormais dans un autre fichier, docker-compose.dev.yml (docker compose -f docker-compose.dev.yml up -d) : elle ne sert pas à une instance.
Les variables d’environnement
| Variable | Rôle | Statut |
|---|---|---|
POSTGRES_PASSWORD | Mot de passe de la base, en lettres et chiffres uniquement car il entre dans l’URL de connexion (openssl rand -hex 24 Générer) | Obligatoire |
BETTER_AUTH_SECRET | Secret aléatoire qui signe les sessions (openssl rand -base64 32 Générer) | Obligatoire |
BETTER_AUTH_URL | URL publique de l’instance, par exemple https://compta.votre-societe.fr | Obligatoire |
ADMIN_EMAIL | Le seul email autorisé à créer le compte administrateur | Obligatoire |
SETUP_TOKEN | Jeton exigé par /setup pour créer le compte administrateur (openssl rand -base64 24 Générer) | Obligatoire |
TRUST_PROXY_HOPS | Nombre de proxies devant Kledg : 1 par défaut, voir L’adresse IP des clients | Recommandé |
RESEND_API_KEY, EMAIL_FROM | Envoi des emails ; sans eux, les emails sont écrits dans les logs | Recommandé |
CRON_SECRET | Protège la synchronisation bancaire quotidienne | Optionnel |
ENCRYPTION_KEY | Chiffre les identifiants bancaires en base ; par défaut, dérivée de BETTER_AUTH_SECRET | Optionnel |
RATE_LIMIT_IP_HEADER | En-tête posé par votre proxy avec l’adresse du client, à la place de TRUST_PROXY_HOPS | Optionnel |
KLEDG_DEPLOYS_FROM_GITHUB | true quand la plateforme redéploie à chaque push sur GitHub (mise à jour en deux clics) | Optionnel |
KLEDG_COMMIT | Commit affiché par la page Mises à jour ($(git rev-parse HEAD)) | Optionnel |
KLEDG_BACKUP | off pour ne pas sauvegarder la base avant une migration (activé par défaut) | Optionnel |
DATABASE_URL est composée par le fichier Compose à partir de POSTGRES_PASSWORD. Pour une base existante, retirez le service db et définissez DATABASE_URL (TLS par défaut). Les autres variables sont décrites dans le guide de configuration.
Installer avec docker compose
Récupérez le code sur le serveur :
git clone https://github.com/kledghq/kledg.git /opt/kledg
cd /opt/kledg
Créez un fichier .env à côté de docker-compose.yml, lisible par vous seul (chmod 600 .env) :
POSTGRES_PASSWORD=resultat-de-openssl-rand-hex-24
BETTER_AUTH_SECRET=resultat-de-openssl-rand-base64-32
BETTER_AUTH_URL=https://compta.votre-societe.fr
ADMIN_EMAIL=vous@votre-societe.fr
SETUP_TOKEN=resultat-de-openssl-rand-base64-24
TRUST_PROXY_HOPS=1
RESEND_API_KEY=
EMAIL_FROM=
CRON_SECRET=resultat-de-openssl-rand-hex-32
Publiez le port 3000 sur l’interface locale du serveur seulement, dans un fichier docker-compose.override.yml (ignoré par Git, lu automatiquement par Compose) :
services:
kledg:
ports:
- "127.0.0.1:3000:3000"
Lancez l’instance :
export KLEDG_COMMIT=$(git rev-parse HEAD)
docker compose up -d --build
Au démarrage, le conteneur applique les migrations de la base, puis lance l’application sur le port 3000. Pour vérifier que tout répond :
curl http://127.0.0.1:3000/api/health
# {"status":"ok"}
docker compose ps indique aussi si les conteneurs sont en bonne santé.
Le HTTPS avec un reverse proxy
Kledg doit être servi en HTTPS. Caddy obtient et renouvelle le certificat tout seul ; installé sur le serveur, il suffit de trois lignes dans son Caddyfile :
compta.votre-societe.fr {
reverse_proxy 127.0.0.1:3000
}
L’adresse doit correspondre à BETTER_AUTH_URL. Ouvrez ensuite https://compta.votre-societe.fr/setup?token=<SETUP_TOKEN> : la page de configuration crée le compte administrateur avec l’email défini dans ADMIN_EMAIL.
L’adresse IP des clients
Kledg limite les tentatives de connexion par adresse IP et l’écrit dans le journal d’audit. Il ne croit l’en-tête X-Forwarded-For que pour le nombre de proxies indiqué par TRUST_PROXY_HOPS :
- derrière un reverse proxy (Caddy, nginx, Traefik, ou celui de Coolify et Dokploy) :
1, et un de plus par proxy en amont ; - derrière Cloudflare en mode proxy, en plus de votre proxy :
2; - sans proxy :
0, sinon un client pourrait choisir son adresse IP.
Une valeur trop petite ne prend que l’adresse d’un proxy (limites partagées, sans faille) ; une valeur trop grande laisse le client choisir son adresse. En cas de doute, choisissez la plus petite. Vérification : connectez-vous, puis lisez l’adresse de l’entrée de connexion dans le journal d’audit ; ce doit être la vôtre.
Coolify et Dokploy
Coolify et Dokploy utilisent docker-compose.yml tel quel. Renseignez les variables du tableau ci-dessus dans leur éditeur de variables ; leur proxy (Traefik ou Caddy) gère le domaine et le certificat, d’où TRUST_PROXY_HOPS=1, la valeur par défaut du fichier (2 derrière un DNS Cloudflare en mode proxy).
Coolify : New Resource, votre dépôt, Build Pack Docker Compose (fichier /docker-compose.yml). Remplissez les variables (Coolify signale celles qui manquent), puis indiquez le domaine du service kledg avec son port : https://compta.votre-societe.fr:3000. Activez le déploiement automatique (application GitHub ou webhook) et définissez KLEDG_DEPLOYS_FROM_GITHUB=true pour la mise à jour en deux clics. Pour afficher le commit sur la page Mises à jour, activez Include Source Commit in Build ou passez KLEDG_COMMIT. Voir la documentation de Coolify sur Docker Compose.
Dokploy : Create Service, Compose, votre dépôt et le chemin docker-compose.yml. Les variables de l’onglet Environment sont écrites dans un fichier .env à côté du fichier Compose. Dans Domains, ajoutez le domaine sur le service kledg, port 3000. Le webhook de Dokploy redéploie à chaque push : définissez alors KLEDG_DEPLOYS_FROM_GITHUB=true. Les volumes nommés peuvent être sauvegardés vers S3 par Volume Backups. Voir la documentation de Dokploy sur Docker Compose.
Avec l’une comme l’autre, ajoutez une sauvegarde planifiée de la base (Coolify sait sauvegarder une base Postgres vers S3) et copiez les fichiers hors du serveur.
Les sauvegardes
Quand une nouvelle version apporte des migrations, le conteneur sauvegarde d’abord la base avec pg_dump dans le volume kledg-backups (les cinq dernières sont conservées), puis applique les migrations. Si la sauvegarde échoue, le conteneur s’arrête sans toucher à la base.
Ces sauvegardes restent sur le serveur. Planifiez aussi un pg_dump quotidien, par exemple dans la crontab du serveur (crontab -e) :
0 2 * * * cd /opt/kledg && docker compose exec -T db pg_dump -U kledg -Fc kledg > /var/backups/kledg/kledg-$(date +\%F).dump
Copiez ces fichiers hors du serveur (stockage objet, autre machine), supprimez les plus anciens, et testez une restauration de temps en temps. Les livres comptables se conservent dix ans : gardez aussi l’export FEC de chaque exercice clôturé.
Le stockage des justificatifs
Depuis Kledg 0.4.0, les justificatifs (photos, PDF) sont rangés dans le volume kledg-storage (dossier /app/storage du conteneur). Sauvegardez ce volume avec la base : pg_dump ne contient pas les fichiers.
Pour un bucket compatible S3 à la place (Scaleway, Cloudflare R2, AWS S3), créez un bucket privé et définissez KLEDG_S3_BUCKET, KLEDG_S3_ENDPOINT, KLEDG_S3_REGION, KLEDG_S3_ACCESS_KEY_ID et KLEDG_S3_SECRET_ACCESS_KEY dans le fichier .env. Une instance mise à jour depuis une version qui gardait les justificatifs dans la base les déplace avec KLEDG_STORAGE_MIGRATE=on, à retirer ensuite.
La synchronisation bancaire quotidienne
Sur Vercel, une tâche planifiée synchronise les banques chaque jour. Ailleurs, planifiez vous-même l’appel, avec le secret défini dans CRON_SECRET. Dans la crontab du serveur :
0 5 * * * curl -fsS -H "Authorization: Bearer VOTRE_CRON_SECRET" https://compta.votre-societe.fr/api/cron/sync-banks
Ou depuis une GitHub Action planifiée, avec le secret enregistré dans votre dépôt :
name: Synchronisation bancaire
on:
schedule:
- cron: "0 5 * * *"
jobs:
sync:
runs-on: ubuntu-latest
steps:
- run: curl -fsS -H "Authorization: Bearer ${{ secrets.CRON_SECRET }}" https://compta.votre-societe.fr/api/cron/sync-banks
L’ancien chemin /api/cron/sync-qonto reste valable.
Mettre à jour
Sur le serveur, récupérez la nouvelle version puis reconstruisez l’image :
cd /opt/kledg
git pull https://github.com/kledghq/kledg.git main
export KLEDG_COMMIT=$(git rev-parse HEAD)
docker compose up -d --build
Lisez les notes de version avant une mise à jour. Pour revenir en arrière, redémarrez l’ancienne version et restaurez la sauvegarde prise avant la migration, avec le pg_restore de l’image Kledg (PostgreSQL 18, la version qui a écrit la sauvegarde) :
docker compose exec kledg sh -c 'pg_restore --clean --no-owner -d "$DATABASE_URL" /app/backups/kledg-AAAAMMJJTHHMMSSZ.dump'
Les migrations de Kledg sont uniquement additives : une version ne supprime jamais une colonne encore utilisée par la version précédente.
Avec Coolify ou Dokploy qui redéploient à chaque push et KLEDG_DEPLOYS_FROM_GITHUB=true, la page Mises à jour installe la nouvelle version en deux clics : voir Mettre à jour son instance.
Si vous ne souhaitez pas vous en occuper, l’installation accompagnée est sur devis.