Héberger Kledg sur Fly.io

Fly.io exécute l’image Docker de Kledg sur ses machines. Le fichier fly.toml du dépôt décrit le service : port 3000, région principale Paris (cdg), vérification de santé sur /api/health, migrations avant le remplacement des machines, arrêt et redémarrage automatiques des machines.

Ce qu’il vous faut

• un compte Fly.io et l’outil en ligne de commande fly ;
• un clone de votre fork ou de votre copie du dépôt kledghq/kledg ;
• de préférence, un compte Resend pour l’envoi des emails.

Déployer

Dans le dossier du dépôt, créez l’application en gardant fly.toml, puis définissez les secrets :

fly launch --no-deploy --copy-config      # garde fly.toml, choisit le nom de l’application
fly secrets set BETTER_AUTH_SECRET="$(openssl rand -base64 32)" \
  SETUP_TOKEN="$(openssl rand -base64 24)" ADMIN_EMAIL=vous@exemple.fr

Pour la base de données, au choix :

• Fly Postgres : fly postgres create, puis fly postgres attach <nom-de-la-base>, qui définit le secret DATABASE_URL sur le réseau privé de Fly.io ;
• Neon ou un autre Postgres : fly secrets set DATABASE_URL="postgresql://...", en choisissant une région proche de Paris.

Puis déployez :

fly deploy --build-arg KLEDG_COMMIT=$(git rev-parse HEAD)

fly secrets list ne réaffiche pas la valeur de SETUP_TOKEN : gardez celle que vous avez générée. Ouvrez https://<application>.fly.dev/setup?token=<SETUP_TOKEN> et créez le compte administrateur. Avec votre propre domaine (fly certs add), définissez BETTER_AUTH_URL.

L’adresse IP des clients

fly.toml définit RATE_LIMIT_IP_HEADER=Fly-Client-IP : Kledg prend l’adresse posée par Fly Proxy à partir de la connexion qu’il a acceptée, et non celle qu’un client pourrait écrire. Si vous placez Cloudflare devant (DNS en mode proxy), cette adresse est celle de Cloudflare : voir la section Adresse IP des clients du guide de référence. Vérifiez dans le journal d’audit que l’adresse de votre connexion est bien la vôtre.

Les migrations

release_command lance les migrations dans une machine temporaire, avec les secrets de l’application, avant de remplacer les machines ; une migration en échec arrête le déploiement.

Mettre à jour

Fly.io ne redéploie pas tout seul depuis GitHub. Pour la mise à jour en deux clics de la page Mises à jour, ajoutez ce workflow à votre dépôt, dans .github/workflows/fly-deploy.yml :

name: Fly Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    concurrency: deploy-group
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only --build-arg KLEDG_COMMIT=${{ github.sha }}
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

Créez ensuite le secret de dépôt FLY_API_TOKEN avec la sortie de fly tokens create deploy, puis fly secrets set KLEDG_DEPLOYS_FROM_GITHUB=true. Le workflow Update from Kledg laisse vos fichiers de workflow tels quels : celui-ci reste en place à chaque mise à jour. La documentation Fly.io décrit ce déploiement continu avec GitHub Actions.

Sans ce workflow, la page Mises à jour affiche les commandes à lancer (git pull, puis fly deploy). Voir Mettre à jour son instance.

Les sauvegardes

Fly Postgres n’est pas une base managée : vérifiez les instantanés de son volume (fly volumes list, puis fly volumes snapshots list <id du volume>) et planifiez un pg_dump vers un stockage que vous contrôlez. Avec Neon, utilisez ses branches et son historique de restauration. KLEDG_BACKUP=off (dans fly.toml) évite une sauvegarde sur le disque des machines, qui n’est pas conservé.

La synchronisation bancaire quotidienne

Définissez CRON_SECRET (fly secrets set), puis appelez chaque jour /api/cron/sync-banks, par exemple depuis une GitHub Action. Voir La synchronisation bancaire quotidienne.

Le coût

Voir la tarification de l’hébergeur. auto_stop_machines = "stop" arrête la machine sans trafic ; la première requête la redémarre.

Pour aller plus loin

• la documentation Fly.io : fichier fly.toml et Fly Postgres ;
• Choisir son hébergement ;
• le guide de référence : docs/self-hosting.md.