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

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](/blog/2026/11/18/run-your-own-beancount-io-from-one-button).

## Déployez la pile

[![Deploy to bex.co](/img/blog/run-your-own-beancount-io-from-one-button/deploy-to-bex.svg)](https://dashboard.bex.co/deploy?repo=https://github.com/bex-co/beancount-io&path=bex.yaml)

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.

:::warning
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](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#13-someone-signed-up-before-me-what-now) 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.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

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 bex | Ce qu'elle fait | Coût mensuel (USD) |
| --- | --- | --- |
| `beancount-dashboard` | L'application web, et la seule adresse publique que vous utilisez | 4,90 |
| `beancount-api` | GraphQL, REST, le serveur MCP et le proxy Git | 4,90 |
| `beancount-ledger` | Valide et interroge vos comptes (privé, sans adresse publique) | 4,90 |
| `beancount-gitea` | Stocke chaque registre comme un dépôt Git sur un disque de 10 Go (privé) | 6,65 |
| `beancount-backend-db` | Postgres pour les comptes, les jetons et les paramètres | 4,41 |
| `beancount-cache` | Key Value pour les sessions de connexion et les caches | 7,21 |
| **Total** | | **32,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.

| Variables | Ce qu'elles activent |
| --- | --- |
| `ANTHROPIC_API_KEY` ou `OPENAI_API_KEY` | La 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_KEY` | Le courrier, comme les liens de réinitialisation du mot de passe |
| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` | La 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`](https://beancount.io/fr/docs/Basics/bea-cli) avec `uv tool install beancount-io` ou `brew install bex-co/tap/bea`, puis pointez-le vers votre tableau de bord :

```zsh
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](https://beancount.io/fr/docs/bea-cli-reference) 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 :

```zsh
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 :

```zsh
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.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### 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.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

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 :

```zsh
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 :

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

### L'application mobile

Sur l'écran d'accueil de l'application [iOS](/beancount-ios) ou [Android](/beancount-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 (`alice@example.com`), 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 :

```zsh
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":"user@example.com"}'
```

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

:::warning
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](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#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 :

```zsh
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` :

```zsh
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.

   ```zsh
   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](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) 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é](https://bex.co/privacy-policy) et les [conditions d'utilisation](https://bex.co/terms-of-service) 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

:::warning
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é](https://beancount.io/fr/docs/request-to-delete-account) ; supprimer le seul compte rouvre l'inscription.

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

Le [déploiement Docker](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) exécute la même pile sur n'importe quel serveur que vous contrôlez. Les [notes de déploiement bex](https://github.com/bex-co/beancount-io/tree/main/deploy/bex) couvrent plus en profondeur chaque paramètre de ce guide.

Un obstacle ? Ouvrez un [ticket GitHub](https://github.com/bex-co/beancount-io/issues) ou posez la question dans le [chat Telegram Beancount](https://t.me/beancount).
