# Autoallotja Beancount.io a bex amb un clic

Un clic desplega tota la pila de Beancount.io, incloent-hi el tauler web, l'API i el servidor MCP, el servei de llibres i els teus llibres basats en Git, en un espai de treball de bex que tu posseeixes. Aquesta guia va des del botó fins a un llibre funcional. Després tracta com connectar les teves eines, afegir comptes, actualitzar, fer còpies de seguretat i eliminar la pila.

La pila té llicència MIT, no aplica límits de pla i costa uns \$33 al mes en allotjament, facturat al teu espai de treball. Per a l'anunci, llegeix [Executa el teu propi Beancount.io amb un sol clic](/blog/2026/11/18/run-your-own-beancount-io-from-one-button).

## Desplega la pila

[![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. **Engega-la.** Prem **Deploy to bex.co**, tria l'espai de treball que ha de posseir la pila, revisa el pla i aplica'l. No es crea res fins que aproves la previsualització, i no hi ha res a omplir: cada secret es genera dins del teu espai de treball.
2. **Espera la primera compilació.** Va trigar 27–30 minuts en les nostres execucions, i més quan la cua de compilació de bex està ocupada. Un servei el desplegament del qual està marcat com a fallit no es reintenta; torna a desplegar aquest servei des del tauler de bex.
3. **Reclama la teva instància.** Obre l'URL del servei `beancount-dashboard` i registra't de seguida. No hi ha cap pas de verificació per correu electrònic, i el registre es tanca darrere del primer compte.
4. **Crea un llibre.** Comença amb la plantilla inicial, o carrega el llibre d'exemple per fer una ullada.

:::warning
Fins que existeixi el primer compte, qualsevol que trobi l'adreça del tauler pot crear-lo. Si algú es registra abans que tu, [elimina aquest compte amb el testimoni d'administrador de la pila](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) per reobrir el registre.
:::

![Registre en un nou desplegament autoallotjat. Al costat del formulari, la pàgina diu que aquesta còpia la gestiona el seu propietari i que els llibres són text pla a Git.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

Cada compte en una pila autoallotjada obté el nivell més alt: els llibres, les directives, els col·laboradors i l'ús d'IA són il·limitats.

## Què s'executa i quant costa

El Blueprint crea sis recursos al teu espai de treball (preus de la previsualització del pla de bex el 2026-11-18):

| Recurs de bex | Què fa | Cost mensual (USD) |
| --- | --- | --- |
| `beancount-dashboard` | L'aplicació web, i l'única adreça pública que fas servir | 4.90 |
| `beancount-api` | GraphQL, REST, el servidor MCP i el proxy de Git | 4.90 |
| `beancount-ledger` | Valida i consulta els teus llibres (privat, sense adreça pública) | 4.90 |
| `beancount-gitea` | Emmagatzema cada llibre com a repositori Git en un disc de 10 GB (privat) | 6.65 |
| `beancount-backend-db` | Postgres per a comptes, testimonis i configuracions | 4.41 |
| `beancount-cache` | Key Value per a sessions d'inici de sessió i memòries cau | 7.21 |
| **Total** | | **32.97** |

Un proveïdor de models, un servei de correu o un bucket S3 que connectis es factura a part.

## Activa les funcions opcionals

La pila arrenca sense cap integració. Una funció que en necessiti una indica quina configuració falta. Per afegir-ne una, obre el servei `beancount-api` a bex, afegeix les variables a la pestanya **Environment** i torna a desplegar el servei. Una variable que afegeixis allà es conserva quan després sincronitzis el Blueprint.

| Variables | Què activen |
| --- | --- |
| `ANTHROPIC_API_KEY` o `OPENAI_API_KEY` | Escaneig de rebuts, categorització i l'assistent. `bea ask` necessita `OPENAI_API_KEY`. |
| `TEMP_ASSETS_AWS_S3_*` i `PERM_ASSETS_AWS_S3_*` (`BUCKET`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`) | Pujada de rebuts i adjunts |
| `SEND_GRID_API_KEY` | Correu, com ara enllaços de restabliment de contrasenya |
| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` | Inici de sessió a través del teu propi proveïdor d'identitat, i més comptes (vegeu **Afegeix més comptes**) |

## Connecta les teves eines

Fes servir l'adreça del tauler a tot arreu excepte per a Git, que fa servir l'adreça de l'API.

### La CLI bea

Instal·la o actualitza [`bea`](https://beancount.io/ca/docs/Basics/bea-cli) amb `uv tool install beancount-io` o `brew install bex-co/tap/bea`, i després apunta-la al teu tauler:

```zsh
export BEA_API_URL=https://<adreça del teu tauler>
export BEA_DASHBOARD_URL=https://<adreça del teu tauler>
bea cloud login            # inicia la sessió a través del navegador
bea cloud ledger list
```

Totes dues variables prenen l'adreça del tauler, perquè el tauler reenvia el trànsit de l'API. La [referència de la CLI de Beancount](https://beancount.io/ca/docs/bea-cli-reference) llista tots els altres comandaments de `bea cloud`.

### Agents de codi a través de MCP

Afegeix el servidor MCP del desplegament a Claude Code o a qualsevol client MCP:

```zsh
claude mcp add --transport http beancount \
  https://<adreça del teu tauler>/api-gateway/mcp
```

Inicia la sessió amb `/mcp` a Claude Code. La pàgina de consentiment la serveix la teva pròpia instància; tria el llibre que el client pot utilitzar i aprova. Per a un client que envia una capçalera en lloc d'això, crea un testimoni d'accés personal (a continuació) i envia'l com a `Authorization: Bearer <token>`.

### Git sobre HTTPS

Cada llibre és un repositori Git a `https://<adreça de la teva API>/git/<owner>/<ledger>.git`. Copia l'adreça exacta del menú **Git Clone** del llibre. bex no encamina SSH, així que Git funciona sobre HTTPS. En una màquina amb `bea`, deixa que iniciï la sessió de Git:

```zsh
bea cloud login            # una vegada, si encara no ho has fet
bea cloud git setup        # ara Git inicia la sessió amb la teva sessió de bea
git clone https://<adreça de la teva API>/git/<owner>/<ledger>.git
```

Després d'això, `git clone`, `git pull` i `git push` cap a aquest amfitrió no demanen res, i `bea cloud logout` elimina també l'inici de sessió de Git. `bea cloud ledger clone` clona per SSH, així que en aquesta pila mostra els comandaments anteriors en lloc de fer-ho.

![El menú Git Clone d'un llibre: l'adreça HTTPS de l'API, amb un testimoni d'accés personal com a contrasenya.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### Git sense bea

En un executor de CI o en una màquina sense `bea`, inicia la sessió de Git amb un testimoni d'accés personal:

1. **Crea un testimoni.** Al tauler, obre **Settings → Personal access tokens → New token**. Anomena'l segons on s'executa (`laptop`, `nightly-backup`), tria `ledger.read` per clonar i fer pull, i afegeix `ledger.write` si fa push. Per a un script desatès, limita'l a un sol llibre i estableix una caducitat. Copia ara el testimoni `bcio_`; només es mostra una vegada.
2. **Clona.** Git demana un nom d'usuari i una contrasenya: introdueix qualsevol nom d'usuari no buit i enganxa el testimoni com a contrasenya. El Keychain de macOS i el Git Credential Manager de Windows el conserven per a la propera vegada. A Linux, activa primer un assistent de credencials, per exemple `git config --global credential.helper 'cache --timeout=86400'` (en memòria durant un dia).

![Configuració, testimonis d'accés personal: un testimoni amb ledger.read i ledger.write, el seu prefix, i quan es va crear i quan es va fer servir per última vegada.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

En un script, mantén el testimoni fora de l'URL remot, on Git el desaria a `.git/config`, i fora de l'historial de l'intèrpret d'ordres. Passa'l a Git mitjançant un assistent de credencials d'un sol ús:

```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://<adreça de la teva API>/git/<owner>/<ledger>.git
```

El `-c credential.helper=` buit evita que un assistent emmagatzemat desi el testimoni. Passa totes dues opcions `-c` a cada `git fetch` o `git push` posterior de l'script.

Si Git continua oferint una contrasenya antiga o un testimoni revocat, esborra'l:

```zsh
printf 'protocol=https\nhost=<adreça de la teva API>\n\n' | git credential reject
```

### L'aplicació mòbil

A la pantalla de benvinguda de l'aplicació [iOS](/beancount-ios) o [Android](/beancount-android), obre la configuració, estableix l'URL del servidor a l'adreça del teu tauler i inicia la sessió.

## Porta els teus llibres existents

Crea un llibre al tauler, clona'l, fusiona-hi els teus fitxers o el teu historial de Git i fes push. La pila obre `main.bean` com a punt d'entrada del llibre, així que anomena el teu fitxer arrel `main.bean` o fes servir `main.bean` per `include` els teus fitxers existents.

## Afegeix més comptes

El registre es manté tancat després del primer compte. Més persones s'uneixen a través d'un proveïdor d'OpenID Connect que connectis, que també gestiona el seu inici de sessió amb doble factor. A la pestanya **Environment** del servei `beancount-api`:

1. Estableix `OIDC_ISSUER`, `OIDC_CLIENT_ID` i `OIDC_CLIENT_SECRET`, i registra `https://<adreça del teu tauler>/api-gateway/auth/oidc/callback` com a URI de redirecció del client. La pàgina d'inici de sessió oferirà llavors **Sign in with** seguit de `OIDC_NAME` (per defecte `SSO`).
2. Llista qui pot unir-se a `OIDC_ALLOWED_EMAILS`, separats per comes: una adreça (`alice@example.com`), un domini (`@example.com`), o els seus subdominis (`@*.example.com`). Una adreça verificada i llistada obté un compte i un llibre per defecte la primera vegada que inicia la sessió. Sense la llista, el proveïdor només inicia la sessió dels comptes ja vinculats a ell.

Tothom a qui deixis entrar comparteix el teu disc i la teva clau de model, sense límits de pla. Amb un proveïdor al qual qualsevol pot unir-se, llista adreces en lloc d'un domini com `@gmail.com`.

## Restableix una contrasenya oblidada

Sense `SEND_GRID_API_KEY`, la pàgina de contrasenya oblidada indica a l'usuari que el servidor no pot enviar correu. Emet-los un enllaç de restabliment d'un sol ús des de l'API d'administrador. Copia `ADMIN_TOKEN` de la pestanya **Environment** del servei `beancount-api`, i crida a l'adreça `onbex.co` d'aquell servei, no la del tauler:

```zsh
read -rs ADMIN_TOKEN; export ADMIN_TOKEN
curl -sS -X POST "https://<adreça de la teva API>/api/admin/password-reset-link" \
  -H "x-admin-token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'
```

Envia el `resetUrl` retornat a l'usuari per un canal de confiança. Funciona una vegada i caduca al cap d'una hora.

:::warning
L'API d'administrador és accessible per qualsevol que pugui arribar a l'adreça de l'API, i només la protegeix `ADMIN_TOKEN`. El testimoni pot iniciar la sessió com a qualsevol usuari, així que tracta'l com una contrasenya d'arrel: mantén-lo fora de l'historial de l'intèrpret d'ordres i del xat, i rota'l si pot haver quedat exposat.
:::

## Actualitza a una versió més nova

La pila es manté en la versió que vas desplegar fins que l'actualitzis. Un Blueprint creat des del botó no obté cap webhook de push, així que una actualització requereix dos passos:

1. **Sincronitza el Blueprint** per aplicar canvis a la seva configuració (API de bex: `POST /v1/blueprints/<id>/sync`).
2. **Desplega cada servei al nou commit**, perquè els canvis de codi necessiten una compilació (`POST /v1/services/<id>/deploys` amb `commitId`).

bex compila un servei alhora i l'API es compila l'última, així que un desplegament complet pot trigar gairebé una hora. Abans de sincronitzar un Blueprint més nou en una pila que conté dades, llegeix [Actualitzar una pila que ja s'està executant](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running) i fes una còpia de seguretat primer.

## Fes còpies de seguretat i restaura

Els llibres són repositoris Git al disc de Gitea. Els comptes, els testimonis d'accés personal i les configuracions viuen al Postgres gestionat. Fes una còpia de seguretat de cadascun a la seva manera.

### Llibres

Un clon mirall és una còpia de seguretat completa dels fitxers i l'historial d'un llibre:

```zsh
git clone --mirror https://<adreça de la teva API>/git/<owner>/<ledger>.git
```

Executa'l en una màquina on s'hagi executat `bea cloud git setup`, o amb l'assistent de testimoni de **Git sense bea**. Per restaurar, elimina el llibre al tauler si encara apareix a la llista i crea'n un amb el mateix nom. El servidor rebutja un push forçat a la branca principal d'un llibre, així que fusiona la còpia de seguretat a sobre del primer commit del nou llibre, fent servir un testimoni amb `ledger.write` quan no facis servir `bea`:

```zsh
git clone https://<adreça de la teva API>/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 dades

bex fa còpies de seguretat contínues de `beancount-backend-db` i pot restaurar-la tal com era en un moment anterior. Restaura en una base de dades nova, mai in situ, així que copies aquesta base de dades sobre la pròpia de la pila:

1. A bex, obre `beancount-backend-db`, tria **Recovery**, tria un moment d'almenys deu minuts enrere i restaura. bex crea una base de dades nova amb les dades tal com eren en aquell moment.
2. Suspèn `beancount-api` i `beancount-gitea`, perquè res escrigui mentre restaures.
3. Copia les dades de tornada amb `pg_dump` i `pg_restore` de PostgreSQL 16 (la imatge Docker `postgres:16` té tots dos). Fes servir la cadena de connexió externa de `beancount-backend-db` per a tots dos extrems, i per a la còpia canvia només l'amfitrió pel de la còpia. No facis servir els detalls de connexió que bex mostra per a la còpia; anomenen una base de dades i un usuari que no poden llegir les dades restaurades.

   ```zsh
   read -rs DB_URL; export DB_URL   # cadena de connexió externa de beancount-backend-db
   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` informa que potser no pot eliminar les extensions `vector` i `pg_stat_statements`; aquests errors són esperats. Si el certificat de la còpia encara s'està emetent, afegeix `?sslmode=verify-full` a `COPY_URL` i desa el CA que bex mostra per a la còpia com a `~/.postgresql/root.crt`. Si la connexió es tanca per temps d'espera, torna-ho a provar.
4. Reprèn `beancount-gitea` i `beancount-api`, i després elimina la còpia.

## Què surt del teu espai de treball

La pila no envia cap analítica ni telemetria a Beancount.io, i l'script d'analítica del navegador queda exclòs de la compilació. Les úniques sol·licituds sortints que coneixem són:

- **Comprovacions de filtracions de contrasenyes:** els primers cinc caràcters del hash SHA-1 d'una nova contrasenya, comprovats per k-anonimitat, de manera que no es revela ni la contrasenya ni el compte.
- **Avatars:** el navegador demana una imatge a Gravatar mitjançant un hash de l'adreça de correu electrònic de l'usuari.
- **Feeds:** els feeds del blog i del registre de canvis de Beancount.io, que només reben una preferència d'idioma.
- **Feeds de preus:** sol·licituds a beancount.io només quan un llibre inclou un URL de preus gestionat.
- **Les teves integracions:** tot el que connectis, com un proveïdor de models, SendGrid, S3, Plaid o el teu proveïdor d'identitat.

La [taula de privacitat de PRFAQ006](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) indica quan s'activa cada sol·licitud. Els teus serveis, disc i base de dades s'executen a la infraestructura de bex, sota la [política de privacitat](https://bex.co/privacy-policy) i els [termes del servei](https://bex.co/terms-of-service) de bex. bex el construeix Stargately, Inc., l'empresa darrere de Beancount.io; el servei allotjat de Beancount.io és independent de la teva pila i no conté cap dels seus secrets.

## Elimina la pila

:::warning
Eliminar els recursos atura la factura i n'elimina les teves dades. Clona tots els llibres primer.
:::

Fes una còpia de seguretat com s'ha descrit anteriorment, i després elimina els sis recursos a bex, seguits del Blueprint. Per eliminar només el teu propi compte i conservar la pila, elimina'l a **Settings → General → Danger Zone**, com al [servei allotjat](https://beancount.io/ca/docs/request-to-delete-account); eliminar l'únic compte reobre el registre.

## Executa-la al teu propi servidor en lloc d'això

El [desplegament Docker](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) executa la mateixa pila en qualsevol servidor que controlis. Les [notes de desplegament de bex](https://github.com/bex-co/beancount-io/tree/main/deploy/bex) cobreixen amb més profunditat cada configuració d'aquesta guia.

Has trobat un entrebanc? Obre un [problema a GitHub](https://github.com/bex-co/beancount-io/issues) o pregunta al [xat de Telegram de Beancount](https://t.me/beancount).
