Mettre à jour son instance

Kledg évolue régulièrement : corrections, nouveaux états, nouvelles banques. Comme vous hébergez votre propre instance, c’est vous qui décidez quand l’installer. La page Mises à jour vous dit où vous en êtes, reconnaît votre hébergeur et vous guide.

Ce que vous allez faire

Voir la version installée et les nouveautés disponibles.
Sauvegarder la base si la mise à jour apporte des migrations.
Installer la mise à jour.
Vérifier dans l’historique que la nouvelle version tourne.

Prérequis

Le compte administrateur de l’instance.
Pour la mise à jour en deux clics : un accès à votre dépôt GitHub (la copie ou le fork de Kledg depuis lequel l’instance est déployée).
Sinon : un accès au serveur, ou à l’outil en ligne de commande de l’hébergeur.

Étape 1 : ouvrir la page Mises à jour

Dans le menu de votre compte, choisissez Paramètres, puis Mises à jour dans la partie Instance de la barre latérale. La page indique :

la version installée, le commit déployé et sa date de construction ;
la dernière version publiée, ou « Vous utilisez la dernière version publiée » ;
les nouveautés depuis votre version ;
les migrations de la base que la mise à jour appliquera, ou « Aucune migration de la base ».

Un indicateur « Mise à jour disponible » apparaît aussi dans l’en-tête des administrateurs.

Étape 2 : sauvegarder

Une migration modifie la structure de votre base de données. Avant d’installer une mise à jour qui en annonce, sauvegardez la base :

sur Neon, créez une branche de la base, en un clic dans la console Neon ;
sur Railway, Render ou Clever Cloud, vérifiez la dernière sauvegarde de la base managée, ou lancez un pg_dump ;
avec Fly Postgres, qui n’est pas une base managée, lancez un pg_dump ;
avec Docker, Coolify ou Dokploy, le conteneur sauvegarde la base tout seul avec pg_dump dès qu’il y a des migrations à appliquer (volume kledg-backups, cinq dernières sauvegardes) ;
avec Node.js, lancez pg_dump vous-même avant pnpm db:migrate.

Étape 3 : installer en deux clics

La mise à jour en deux clics fusionne une pull request dans votre dépôt GitHub ; l’hébergeur redéploie ensuite l’instance et applique les migrations. Elle suppose donc que l’hébergeur redéploie à chaque fusion sur la branche principale :

Hébergeur	Mise à jour en deux clics
Vercel	Automatique
Railway, Render	Automatique quand le déploiement vient d’un commit GitHub
Fly.io	Avec le workflow GitHub Actions et `KLEDG_DEPLOYS_FROM_GITHUB=true`
Clever Cloud	Application liée à votre dépôt GitHub, et `KLEDG_DEPLOYS_FROM_GITHUB=true`
Coolify	Déploiement automatique activé sur la ressource, et `KLEDG_DEPLOYS_FROM_GITHUB=true`
Dokploy	Webhook de déploiement activé, et `KLEDG_DEPLOYS_FROM_GITHUB=true`
Docker, Node.js	Avec `KLEDG_DEPLOYS_FROM_GITHUB=true`, si votre propre outillage redéploie à chaque fusion

La page dit, pour votre hébergeur, comment la fusion arrive jusqu’à l’instance. KLEDG_DEPLOYS_FROM_GITHUB=false désactive la mise à jour en deux clics partout.

Connectez GitHub une fois :

Cliquez sur Créer le jeton sur GitHub : le formulaire de GitHub s’ouvre déjà rempli (nom, durée, autorisations).
Limitez le jeton à votre dépôt Kledg, créez-le, puis collez-le dans Kledg. Il est chiffré et ne sert qu’à ce dépôt.

Ensuite, à chaque nouvelle version :

Préparer la mise à jour : Kledg ouvre dans votre dépôt une pull request « Mise à jour Kledg x.y.z ». Si l’hébergeur construit un aperçu des pull requests (Vercel, environnements de pull request de Railway ou Render), la page l’affiche.
Installer : Kledg rappelle les migrations à appliquer, puis fusionne la pull request. L’hébergeur redéploie l’instance avec ses migrations ; la page détecte la nouvelle version à la fin du déploiement.

Sans jeton, rien ne change : le workflow Update from Kledg de votre dépôt ouvre chaque lundi une pull request « Mise à jour Kledg x.y.z », à vérifier puis fusionner sur GitHub.

Le canal de mise à jour

Par défaut, seules les versions publiées sont proposées (recommandé). La page Mises à jour, ou la variable de dépôt KLEDG_UPDATES, permet de suivre la branche principale (main, chaque changement, pour tester) ou de désactiver ces pull requests (off).

Si GitHub n’autorise pas les Actions à ouvrir des pull requests (réglage Allow GitHub Actions to create and approve pull requests, dans Settings, Actions, General), le workflow pousse la branche kledg-update et affiche un lien pour ouvrir la pull request en un clic.

Étape 3 bis : installer avec des commandes

Quand la fusion sur GitHub ne redéploie pas l’instance, la page affiche les commandes à lancer, adaptées à l’hébergeur, avec un bouton pour les copier. Elles commencent toutes par récupérer la nouvelle version dans votre clone du dépôt :

cd kledg   # votre clone du dépôt
git pull https://github.com/kledghq/kledg.git main

Puis, selon l’hébergeur :

Hébergeur	Commande suivante
Docker	`export KLEDG_COMMIT=$(git rev-parse HEAD)` puis `docker compose up -d --build`
Fly.io	`fly deploy --build-arg KLEDG_COMMIT=$(git rev-parse HEAD)`
Railway	`railway up`, ou un push sur la branche suivie par Railway
Render	`git push` : Render redéploie la branche suivie
Clever Cloud	`git push clever main:master`, vers le dépôt Git de l’application
Coolify	`git push`, puis Redeploy dans Coolify
Vercel	`git push`

Avec Node.js :

pnpm install --frozen-lockfile
pnpm db:migrate
pnpm build
# puis redémarrez le service (pnpm start)

Le détail de chaque hébergeur est dans sa page : Railway, Render, Fly.io, Clever Cloud, Docker, Coolify et Dokploy.

Étape 4 : vérifier l’historique des mises à jour

En bas de la page Mises à jour, la carte Historique des mises à jour liste les versions que votre instance a fait tourner, de la plus récente à la plus ancienne. Pour chacune :

Colonne	Ce qu’elle indique
Date	Le premier démarrage de l’instance avec cette version.
Version	La version précédente et la nouvelle, avec le commit court.
Installée par	L’administrateur de l’instance qui l’a installée depuis la page, avec Installer la mise à jour. Sinon, « Hôte ou dépôt (hors de cette page) » : un redéploiement par l’hébergeur, un `git push` ou une mise à jour en ligne de commande.
Migrations	Les migrations de la base appliquées avec cette version, ou « Aucune ».
Notes de version	Le lien vers les notes de la version publiée sur GitHub, sinon vers le commit déployé de votre dépôt quand l’hébergeur le donne ; « Indisponibles » sinon.

Kledg enregistre la version à chaque démarrage du serveur, une seule fois même si plusieurs serveurs démarrent en même temps, sans ralentir les pages. Quelques précisions :

L’historique commence à la première version qui a cette carte : sa ligne n’indique pas de migrations.
Revenir à une version déjà installée (un retour en arrière) n’ajoute pas de ligne : la version garde sa première date.
Avec KLEDG_RLS=enforce, l’application n’a pas le droit de lire la liste des migrations de la base : la colonne Migrations indique « Inconnues ».

Après une mise à jour, une nouvelle ligne en haut de l’historique confirme que la version tourne, avec les migrations appliquées.

Et le bouton Sync fork de GitHub ?

Si votre dépôt est un fork de Kledg, GitHub affiche un bouton Sync fork. Il agit directement sur votre branche principale, que Vercel redéploie aussitôt en production.

Update branch fusionne la dernière version de la branche main de Kledg. Cela fonctionne, mais sans les garde-fous de la page Mises à jour : vous recevez les changements du moment, pas la dernière version publiée ; aucun aperçu n’est construit avant la production ; et rien ne vous rappelle de sauvegarder la base avant les migrations. Préférez Préparer la mise à jour.
Discard N commits remet votre dépôt exactement dans l’état de Kledg : vos propres modifications disparaissent et la production est redéployée ainsi. N’utilisez pas ce bouton.

Changer le secret de l’instance

Si BETTER_AUTH_SECRET a pu être lu par quelqu’un d’autre, remplacez-le en deux déploiements, sans reconnecter vos banques : voir Changer le secret de l’instance.

Les erreurs fréquentes

Installer sans sauvegarde une mise à jour qui annonce des migrations.
Modifier le code de votre copie : vos changements entreront en conflit avec les mises à jour. Proposez-les plutôt sur le dépôt de Kledg.
Laisser expirer le jeton GitHub : Kledg vous prévient deux semaines avant. Créez-en un nouveau et reconnectez GitHub.
Définir KLEDG_DEPLOYS_FROM_GITHUB=true alors que l’hébergeur ne redéploie pas depuis GitHub : la pull request serait fusionnée sans que l’instance change.
Suivre la branche principale en production : réservez-la aux tests.