Aller au contenu principal

Auto-hébergez Beancount.io sur bex en un clic

Déployez Beancount.io sur votre propre espace de travail bex en un clic, puis connectez bea, les clients MCP, Git et l'application mobile, ajoutez des comptes et sauvegardez.

Un clic déploie toute la pile Beancount.io, y compris le tableau de bord web, l'API et le serveur MCP, le service de registre et vos registres adossés à Git, dans un espace de travail bex que vous possédez. Ce guide va du bouton jusqu'à un registre fonctionnel. Il couvre ensuite la connexion de vos outils, l'ajout de comptes, la mise à jour, la sauvegarde et la suppression de la pile.

La pile est sous licence MIT, n'applique aucune limite de forfait et coûte environ 33 $ par mois en hébergement, facturés à votre espace de travail. Pour l'annonce, lisez Exécutez votre propre Beancount.io en un clic.

Déployez la pile​

Deploy to bex.co

  1. Lancez-le. Appuyez sur Deploy to bex.co, choisissez l'espace de travail qui doit posséder la pile, examinez le plan et appliquez. Rien n'est créé tant que vous n'avez pas approuvé l'aperçu, et il n'y a rien à remplir : chaque secret est généré à l'intérieur de votre espace de travail.
  2. Attendez la première compilation. Elle a pris 27 à 30 minutes lors de nos exécutions, et plus longtemps lorsque la file de compilation de bex est chargée. Un service dont le déploiement est marqué comme échoué n'est pas réessayé ; redéployez ce service depuis le tableau de bord bex.
  3. Revendiquez votre instance. Ouvrez l'URL du service beancount-dashboard et inscrivez-vous tout de suite. Il n'y a pas d'étape de vérification par e-mail, et l'inscription se ferme derrière le premier compte.
  4. Créez un registre. Partez du modèle de démarrage, ou chargez le registre d'exemple pour explorer.
attention

Tant que le premier compte n'existe pas, quiconque trouve l'adresse du tableau de bord peut le créer. Si quelqu'un s'inscrit avant vous, supprimez ce compte avec le jeton d'administration de la pile pour rouvrir l'inscription.

Sign-up on a new self-hosted deployment. Beside the form, the page says this copy is run by its owner and the books are plain text in Git.

Chaque compte sur une pile auto-hébergée obtient le niveau le plus élevé : les registres, les directives, les collaborateurs et l'utilisation de l'IA sont illimités.

Ce qui tourne et ce que cela coûte​

Le Blueprint crée six ressources dans votre espace de travail (prix issus de l'aperçu du plan bex au 2026-11-18) :

Ressource bexCe qu'elle faitCoût mensuel (USD)
beancount-dashboardL'application web, et la seule adresse publique que vous utilisez4,90
beancount-apiGraphQL, REST, le serveur MCP et le proxy Git4,90
beancount-ledgerValide et interroge vos comptes (privé, sans adresse publique)4,90
beancount-giteaStocke chaque registre comme un dépôt Git sur un disque de 10 Go (privé)6,65
beancount-backend-dbPostgres pour les comptes, les jetons et les paramètres4,41
beancount-cacheKey Value pour les sessions de connexion et les caches7,21
Total32,97

Un fournisseur de modèle, un service d'e-mail ou un compartiment S3 que vous connectez vous est facturé séparément.

Activez les fonctionnalités optionnelles​

La pile démarre sans aucune intégration. Une fonctionnalité qui en nécessite une indique quel paramètre manque. Pour en ajouter une, ouvrez le service beancount-api dans bex, ajoutez les variables dans son onglet Environment, et redéployez le service. Une variable que vous ajoutez là est conservée lorsque vous synchronisez ensuite le Blueprint.

VariablesCe qu'elles activent
ANTHROPIC_API_KEY ou OPENAI_API_KEYLa numérisation des reçus, la catégorisation et l'assistant. bea ask nécessite OPENAI_API_KEY.
TEMP_ASSETS_AWS_S3_* et PERM_ASSETS_AWS_S3_* (BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY)Le téléversement des reçus et des pièces jointes
SEND_GRID_API_KEYLe courrier, comme les liens de réinitialisation du mot de passe
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRETLa connexion via votre propre fournisseur d'identité, et davantage de comptes (voir Ajoutez davantage de comptes)

Connectez vos outils​

Utilisez l'adresse du tableau de bord partout, sauf pour Git, qui utilise l'adresse de l'API.

La CLI bea​

Installez ou mettez à jour bea avec uv tool install beancount-io ou brew install bex-co/tap/bea, puis pointez-le vers votre tableau de bord :

export BEA_API_URL=https://<your dashboard address>
export BEA_DASHBOARD_URL=https://<your dashboard address>
bea cloud login            # signs in through your browser
bea cloud ledger list

Les deux variables prennent l'adresse du tableau de bord, car le tableau de bord transmet le trafic de l'API. La Référence de la CLI Beancount liste toutes les autres commandes bea cloud.

Agents de codage via MCP​

Ajoutez le serveur MCP du déploiement à Claude Code ou à tout client MCP :

claude mcp add --transport http beancount \
  https://<your dashboard address>/api-gateway/mcp

Connectez-vous avec /mcp dans Claude Code. La page de consentement est servie par votre propre instance ; choisissez le registre que le client peut utiliser et approuvez. Pour un client qui envoie plutôt un en-tête, créez un jeton d'accès personnel (ci-dessous) et envoyez-le comme Authorization: Bearer <token>.

Git via HTTPS​

Chaque registre est un dépôt Git à l'adresse https://<your API address>/git/<owner>/<ledger>.git. Copiez l'adresse exacte depuis le menu Git Clone du registre. bex n'achemine pas SSH, donc Git passe par HTTPS. Sur une machine disposant de bea, laissez-le connecter Git :

bea cloud login            # once, if you haven't already
bea cloud git setup        # Git now signs in with your bea session
git clone https://<your API address>/git/<owner>/<ledger>.git

Ensuite, git clone, git pull et git push vers cet hôte ne demandent plus rien, et bea cloud logout supprime aussi la connexion de Git. bea cloud ledger clone clone via SSH, donc sur cette pile, il affiche les commandes ci-dessus à la place.

A ledger's Git Clone menu: the API's HTTPS address, with a personal access token as the password.

Git sans bea​

Sur un runner de CI ou une machine sans bea, connectez Git avec un jeton d'accès personnel :

  1. Créez un jeton. Dans le tableau de bord, ouvrez Settings → Personal access tokens → New token. Nommez-le selon l'endroit où il s'exécute (laptop, nightly-backup), choisissez ledger.read pour cloner et tirer (pull), et ajoutez ledger.write s'il pousse (push). Pour un script non surveillé, limitez-le à un seul registre et définissez une expiration. Copiez le jeton bcio_ maintenant ; il n'est affiché qu'une seule fois.
  2. Clonez. Git demande un nom d'utilisateur et un mot de passe : saisissez un nom d'utilisateur non vide et collez le jeton comme mot de passe. Le trousseau macOS et Git Credential Manager sous Windows le conservent pour la prochaine fois. Sous Linux, activez d'abord un gestionnaire d'identifiants, par exemple git config --global credential.helper 'cache --timeout=86400' (en mémoire pendant un jour).

Settings, Personal access tokens: a token with ledger.read and ledger.write, its prefix, and when it was created and last used.

Dans un script, gardez le jeton hors de l'URL distante, où Git l'enregistrerait dans .git/config, et hors de l'historique du shell. Confiez-le à Git via un gestionnaire d'identifiants ponctuel :

read -rs BEANCOUNT_TOKEN; export BEANCOUNT_TOKEN
helper='!f() { echo username=token; echo "password=$BEANCOUNT_TOKEN"; }; f'
git -c credential.helper= -c credential.helper="$helper" \
  clone --mirror https://<your API address>/git/<owner>/<ledger>.git

Le -c credential.helper= vide empêche un gestionnaire enregistré d'enregistrer le jeton. Passez les deux options -c à chaque git fetch ou git push ultérieur du script.

Si Git continue de proposer un ancien mot de passe ou un jeton révoqué, effacez-le :

printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject

L'application mobile​

Sur l'écran d'accueil de l'application iOS ou Android, ouvrez les paramètres, définissez l'URL du serveur sur l'adresse de votre tableau de bord, et connectez-vous.

Importez vos registres existants​

Créez un registre dans le tableau de bord, clonez-le, fusionnez-y vos fichiers ou votre historique Git, et poussez. La pile ouvre main.bean comme point d'entrée du registre, donc nommez votre fichier racine main.bean ou utilisez main.bean pour include vos fichiers existants.

Ajoutez davantage de comptes​

L'inscription reste fermée après le premier compte. D'autres personnes rejoignent via un fournisseur OpenID Connect que vous connectez, qui gère aussi leur authentification à deux facteurs. Dans l'onglet Environment du service beancount-api :

  1. Définissez OIDC_ISSUER, OIDC_CLIENT_ID et OIDC_CLIENT_SECRET, et enregistrez https://<your dashboard address>/api-gateway/auth/oidc/callback comme URI de redirection du client. La page de connexion propose alors Sign in with suivi de OIDC_NAME (par défaut SSO).
  2. Listez qui peut rejoindre dans OIDC_ALLOWED_EMAILS, séparés par des virgules : une adresse ([email protected]), un domaine (@example.com), ou ses sous-domaines (@*.example.com). Une adresse listée et vérifiée obtient un compte et un registre par défaut la première fois qu'elle se connecte. Sans la liste, le fournisseur ne connecte que les comptes déjà liés à lui.

Toutes les personnes que vous laissez entrer partagent votre disque et votre clé de modèle, sans limites de forfait. Avec un fournisseur où tout le monde peut s'inscrire, listez des adresses plutôt qu'un domaine tel que @gmail.com.

Réinitialisez un mot de passe oublié​

Sans SEND_GRID_API_KEY, la page de mot de passe oublié indique à l'utilisateur que le serveur ne peut pas envoyer d'e-mail. Émettez-lui plutôt un lien de réinitialisation à usage unique depuis l'API d'administration. Copiez ADMIN_TOKEN depuis l'onglet Environment du service beancount-api, et appelez l'adresse onbex.co propre à ce service, pas celle du tableau de bord :

read -rs ADMIN_TOKEN; export ADMIN_TOKEN
curl -sS -X POST "https://<your API address>/api/admin/password-reset-link" \
  -H "x-admin-token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Envoyez le resetUrl renvoyé à l'utilisateur par un canal de confiance. Il fonctionne une seule fois et expire au bout d'une heure.

attention

L'API d'administration est joignable par quiconque peut atteindre l'adresse de l'API, et seul ADMIN_TOKEN la protège. Le jeton peut se connecter en tant que n'importe quel utilisateur, alors traitez-le comme un mot de passe racine : gardez-le hors de l'historique du shell et des conversations, et changez-le s'il a pu fuiter.

Mettez à jour vers une version plus récente​

La pile reste sur la version que vous avez déployée jusqu'à ce que vous la mettiez à jour. Un Blueprint créé depuis le bouton n'obtient pas de webhook push, donc une mise à jour se fait en deux étapes :

  1. Synchronisez le Blueprint pour appliquer les changements à ses paramètres (API bex : POST /v1/blueprints/<id>/sync).
  2. Déployez chaque service au nouveau commit, car les changements de code nécessitent une compilation (POST /v1/services/<id>/deploys avec commitId).

bex compile un service à la fois et l'API en dernier, donc un déploiement complet peut prendre presque une heure. Avant de synchroniser un Blueprint plus récent dans une pile qui contient des données, lisez Upgrading a stack that is already running et sauvegardez d'abord.

Sauvegardez et restaurez​

Les registres sont des dépôts Git sur le disque de Gitea. Les comptes, les jetons d'accès personnels et les paramètres vivent dans le Postgres géré. Sauvegardez chacun à sa manière.

Les registres​

Un clone miroir est une sauvegarde complète des fichiers et de l'historique d'un registre :

git clone --mirror https://<your API address>/git/<owner>/<ledger>.git

Exécutez-le sur une machine où bea cloud git setup a été exécuté, ou avec le gestionnaire de jeton de Git sans bea. Pour restaurer, supprimez le registre dans le tableau de bord s'il y figure encore et créez-en un du même nom. Le serveur refuse un push forcé vers la branche principale d'un registre, donc fusionnez la sauvegarde par-dessus le premier commit du nouveau registre, en utilisant un jeton avec ledger.write lorsque vous n'utilisez pas bea :

git clone https://<your API address>/git/<owner>/<ledger>.git restore
cd restore
git fetch ../<ledger>.git main
git merge --allow-unrelated-histories -X theirs -m "Restore from backup" FETCH_HEAD
git push origin HEAD

La base de données​

bex sauvegarde beancount-backend-db en continu et peut la restaurer telle qu'elle était à un moment antérieur. Elle restaure dans une nouvelle base de données, jamais sur place, donc vous copiez cette base de données par-dessus celle de la pile :

  1. Dans bex, ouvrez beancount-backend-db, choisissez Recovery, sélectionnez un moment il y a au moins dix minutes, et restaurez. bex crée une nouvelle base de données avec les données telles qu'à ce moment.

  2. Suspendez beancount-api et beancount-gitea, pour que rien n'écrive pendant la restauration.

  3. Copiez les données avec pg_dump et pg_restore de PostgreSQL 16 (l'image Docker postgres:16 contient les deux). Utilisez la chaîne de connexion externe de beancount-backend-db pour les deux extrémités, et pour la copie, changez uniquement l'hôte par celui de la copie. N'utilisez pas les détails de connexion que bex affiche pour la copie ; ils nomment une base de données et un utilisateur qui ne peuvent pas lire les données restaurées.

    read -rs DB_URL; export DB_URL   # beancount-backend-db's external connection string
    COPY_URL="${DB_URL/@<database host>/@<copy host>}"
    pg_dump -Fc --no-owner --no-privileges "$COPY_URL" > backend.dump
    pg_restore --clean --if-exists --no-owner --no-privileges -d "$DB_URL" backend.dump

    pg_restore signale qu'il ne peut peut-être pas supprimer les extensions vector et pg_stat_statements ; ces erreurs sont attendues. Si le certificat de la copie est encore en cours d'émission, ajoutez ?sslmode=verify-full à COPY_URL et enregistrez le CA que bex affiche pour la copie sous ~/.postgresql/root.crt. Si la connexion expire, réessayez.

  4. Reprenez beancount-gitea et beancount-api, puis supprimez la copie.

Ce qui sort de votre espace de travail​

La pile n'envoie aucune analyse ni télémétrie à Beancount.io, et le script d'analyse du navigateur est exclu de la compilation. Les seules requêtes sortantes dont nous avons connaissance sont :

  • Vérifications de fuite de mot de passe : les cinq premiers caractères du hachage SHA-1 d'un nouveau mot de passe, vérifiés par k-anonymat, de sorte que ni le mot de passe ni le compte ne soit révélé.
  • Avatars : le navigateur demande une image à Gravatar via un hachage de l'adresse e-mail de l'utilisateur.
  • Flux : les flux du blog et du journal des modifications de Beancount.io, qui ne reçoivent qu'une préférence de langue.
  • Flux de prix : des requêtes vers beancount.io uniquement lorsqu'un registre inclut une URL de prix gérée.
  • Vos intégrations : tout ce que vous connectez, comme un fournisseur de modèle, SendGrid, S3, Plaid ou votre fournisseur d'identité.

Le tableau de confidentialité dans PRFAQ006 indique quand chaque requête se déclenche. Vos services, votre disque et votre base de données tournent sur l'infrastructure de bex, sous la politique de confidentialité et les conditions d'utilisation de bex. bex est édité par Stargately, Inc., la société derrière Beancount.io ; le service Beancount.io hébergé est distinct de votre pile et ne détient aucun de ses secrets.

Supprimez la pile​

attention

Supprimer les ressources arrête la facture et supprime vos données avec elles. Clonez d'abord chaque registre.

Sauvegardez comme décrit ci-dessus, puis supprimez les six ressources dans bex, suivi du Blueprint. Pour supprimer uniquement votre propre compte et conserver la pile, supprimez-le sous Settings → General → Danger Zone, comme sur le service hébergé ; supprimer le seul compte rouvre l'inscription.

Exécutez-la plutôt sur votre propre serveur​

Le déploiement Docker exécute la même pile sur n'importe quel serveur que vous contrôlez. Les notes de déploiement bex couvrent plus en profondeur chaque paramètre de ce guide.

Un obstacle ? Ouvrez un ticket GitHub ou posez la question dans le chat Telegram Beancount.

Source : https://beancount.io/fr/docs/self-host-beancount-io