# Self-hosting di Beancount.io su bex con un clic

Un clic distribuisce l'intero stack di Beancount.io, inclusi la dashboard web, l'API e il server MCP, il servizio ledger e i tuoi ledger su Git, in un workspace bex di tua proprietà. Questa guida va dal pulsante a un ledger funzionante. Poi copre il collegamento dei tuoi strumenti, l'aggiunta di account, l'aggiornamento, il backup e la rimozione dello stack.

Lo stack è distribuito con licenza MIT, non applica limiti di piano e costa circa \$33 al mese di hosting, addebitati al tuo workspace. Per l'annuncio, leggi [Esegui il tuo Beancount.io con un solo clic](/blog/2026/11/18/run-your-own-beancount-io-from-one-button).

## Distribuisci lo stack

[![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. **Avvialo.** Premi **Deploy to bex.co**, scegli il workspace a cui deve appartenere lo stack, rivedi il piano e applica. Nulla viene creato finché non approvi l'anteprima, e non c'è nulla da compilare: ogni secret viene generato all'interno del tuo workspace.
2. **Attendi la prima build.** Nei nostri test ha richiesto 27–30 minuti, e di più quando la coda di build di bex è occupata. Un servizio il cui rollout è contrassegnato come fallito non viene ritentato; distribuisci di nuovo quel servizio dalla dashboard di bex.
3. **Rivendica la tua istanza.** Apri l'URL del servizio `beancount-dashboard` e registrati subito. Non c'è alcun passaggio di verifica via email, e la registrazione si chiude dietro il primo account.
4. **Crea un ledger.** Parti dal template iniziale, oppure carica il ledger di esempio per dare un'occhiata.

:::warning
Finché il primo account non esiste, chiunque trovi l'indirizzo della dashboard può crearlo. Se qualcuno si registra prima di te, [rimuovi quell'account con il token admin dello stack](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 riaprire la registrazione.
:::

![Registrazione su una nuova distribuzione self-hosted. Accanto al modulo, la pagina indica che questa copia è gestita dal suo proprietario e che i libri contabili sono testo semplice in Git.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

Ogni account su uno stack self-hosted ottiene il livello massimo: ledger, direttive, collaboratori e utilizzo dell'AI sono illimitati.

## Cosa viene eseguito e quanto costa

Il Blueprint crea sei risorse nel tuo workspace (prezzi dall'anteprima del piano di bex del 2026-11-18):

| Risorsa bex | Cosa fa | Costo mensile (USD) |
| --- | --- | --- |
| `beancount-dashboard` | L'app web, e l'unico indirizzo pubblico che usi | 4.90 |
| `beancount-api` | GraphQL, REST, il server MCP e il proxy Git | 4.90 |
| `beancount-ledger` | Convalida ed esegue query sui tuoi libri (privato, nessun indirizzo pubblico) | 4.90 |
| `beancount-gitea` | Memorizza ogni ledger come repository Git su un disco da 10 GB (privato) | 6.65 |
| `beancount-backend-db` | Postgres per account, token e impostazioni | 4.41 |
| `beancount-cache` | Key Value per sessioni di accesso e cache | 7.21 |
| **Totale** | | **32.97** |

Un provider di modelli, un servizio di posta o un bucket S3 che colleghi vengono addebitati separatamente.

## Attiva le funzionalità opzionali

Lo stack si avvia senza alcuna integrazione. Una funzionalità che ne richiede una indica quale impostazione manca. Per aggiungerne una, apri il servizio `beancount-api` in bex, aggiungi le variabili nella sua scheda **Environment** e distribuisci di nuovo il servizio. Una variabile che aggiungi lì viene mantenuta quando successivamente sincronizzi il Blueprint.

| Variabili | Cosa attivano |
| --- | --- |
| `ANTHROPIC_API_KEY` o `OPENAI_API_KEY` | Scansione delle ricevute, categorizzazione e l'assistente. `bea ask` richiede `OPENAI_API_KEY`. |
| `TEMP_ASSETS_AWS_S3_*` e `PERM_ASSETS_AWS_S3_*` (`BUCKET`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`) | Caricamento di ricevute e allegati |
| `SEND_GRID_API_KEY` | Posta, come i link di reimpostazione della password |
| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` | Accesso tramite il tuo provider di identità, e più account (vedi **Aggiungi altri account**) |

## Collega i tuoi strumenti

Usa l'indirizzo della dashboard ovunque, tranne per Git, che usa l'indirizzo dell'API.

### La CLI bea

Installa o aggiorna [`bea`](https://beancount.io/it/docs/Basics/bea-cli) con `uv tool install beancount-io` o `brew install bex-co/tap/bea`, poi puntalo alla tua dashboard:

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

Entrambe le variabili prendono l'indirizzo della dashboard, perché la dashboard inoltra il traffico dell'API. Il [riferimento della CLI di Beancount](https://beancount.io/it/docs/bea-cli-reference) elenca ogni altro comando `bea cloud`.

### Agenti di coding tramite MCP

Aggiungi il server MCP della distribuzione a Claude Code o a qualsiasi client MCP:

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

Accedi con `/mcp` in Claude Code. La pagina di consenso è servita dalla tua istanza; scegli il ledger che il client può usare e approva. Per un client che invia invece un header, crea un personal access token (sotto) e invialo come `Authorization: Bearer <token>`.

### Git su HTTPS

Ogni ledger è un repository Git su `https://<your API address>/git/<owner>/<ledger>.git`. Copia l'indirizzo esatto dal menu **Git Clone** del ledger. bex non instrada SSH, quindi Git funziona su HTTPS. Su una macchina con `bea`, lascia che sia bea ad autenticare 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
```

Dopo di che, `git clone`, `git pull` e `git push` verso quell'host non chiedono nulla, e `bea cloud logout` rimuove anche l'accesso di Git. `bea cloud ledger clone` clona via SSH, quindi su questo stack stampa invece i comandi qui sopra.

![Il menu Git Clone di un ledger: l'indirizzo HTTPS dell'API, con un personal access token come password.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### Git senza bea

Su un runner CI o su una macchina senza `bea`, autentica Git con un personal access token:

1. **Crea un token.** Nella dashboard, apri **Settings → Personal access tokens → New token**. Assegnagli un nome in base a dove viene eseguito (`laptop`, `nightly-backup`), scegli `ledger.read` per clonare e fare pull, e aggiungi `ledger.write` se effettua push. Per uno script non presidiato, limitarlo a un solo ledger e imposta una scadenza. Copia subito il token `bcio_`; viene mostrato solo una volta.
2. **Clona.** Git chiede un nome utente e una password: inserisci un nome utente qualsiasi non vuoto e incolla il token come password. Il Keychain di macOS e Git Credential Manager su Windows lo conservano per la volta successiva. Su Linux, abilita prima un credential helper, ad esempio `git config --global credential.helper 'cache --timeout=86400'` (in memoria per un giorno).

![Impostazioni, Personal access tokens: un token con ledger.read e ledger.write, il suo prefisso, e quando è stato creato e usato l'ultima volta.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

In uno script, tieni il token fuori dall'URL del remote, dove Git lo salverebbe in `.git/config`, e fuori dalla cronologia della shell. Passalo a Git tramite un credential helper temporaneo:

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

Il `-c credential.helper=` vuoto impedisce a un helper memorizzato di salvare il token. Passa entrambe le opzioni `-c` a ogni successivo `git fetch` o `git push` nello script.

Se Git continua a proporre una vecchia password o un token revocato, cancellalo:

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

### L'app mobile

Nella schermata di benvenuto dell'app [iOS](/beancount-ios) o [Android](/beancount-android), apri le impostazioni, imposta l'URL del server all'indirizzo della tua dashboard e accedi.

## Importa i tuoi libri esistenti

Crea un ledger nella dashboard, clonalo, unisci i tuoi file o la tua cronologia Git al suo interno, e fai push. Lo stack apre `main.bean` come punto di ingresso del ledger, quindi chiama il tuo file radice `main.bean` oppure usa `main.bean` per fare `include` dei tuoi file esistenti.

## Aggiungi altri account

La registrazione resta chiusa dopo il primo account. Altre persone si uniscono tramite un provider OpenID Connect che colleghi, che gestisce anche il loro accesso a due fattori. Nella scheda **Environment** del servizio `beancount-api`:

1. Imposta `OIDC_ISSUER`, `OIDC_CLIENT_ID` e `OIDC_CLIENT_SECRET`, e registra `https://<your dashboard address>/api-gateway/auth/oidc/callback` come redirect URI del client. La pagina di accesso offre quindi **Sign in with** seguito da `OIDC_NAME` (predefinito `SSO`).
2. Elenca chi può unirsi in `OIDC_ALLOWED_EMAILS`, separati da virgole: un indirizzo (`alice@example.com`), un dominio (`@example.com`), o i suoi sottodomini (`@*.example.com`). Un indirizzo verificato e presente nell'elenco ottiene un account e un ledger predefinito la prima volta che accede. Senza l'elenco, il provider autentica solo gli account già collegati ad esso.

Chiunque tu lasci entrare condivide il tuo disco e la chiave del modello, senza limiti di piano. Con un provider a cui chiunque può unirsi, elenca indirizzi anziché un dominio come `@gmail.com`.

## Reimposta una password dimenticata

Senza `SEND_GRID_API_KEY`, la pagina di password dimenticata comunica all'utente che il server non può inviare email. Emetti invece per loro un link di reimpostazione monouso dall'API admin. Copia `ADMIN_TOKEN` dalla scheda **Environment** del servizio `beancount-api`, e chiama l'indirizzo `onbex.co` di quel servizio, non quello della dashboard:

```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"}'
```

Invia il `resetUrl` restituito all'utente tramite un canale di cui ti fidi. Funziona una sola volta e scade dopo un'ora.

:::warning
L'API admin è raggiungibile da chiunque possa raggiungere l'indirizzo dell'API, ed è protetta solo da `ADMIN_TOKEN`. Il token può accedere come qualsiasi utente, quindi trattalo come una password di root: tienilo fuori dalla cronologia della shell e dalle chat, e ruotalo se potrebbe essere trapelato.
:::

## Aggiorna a una versione più recente

Lo stack resta alla versione che hai distribuito finché non lo aggiorni. Un Blueprint creato dal pulsante non riceve un webhook di push, quindi un aggiornamento richiede due passaggi:

1. **Sincronizza il Blueprint** per applicare le modifiche alle sue impostazioni (API di bex: `POST /v1/blueprints/<id>/sync`).
2. **Distribuisci ogni servizio al nuovo commit**, perché le modifiche al codice richiedono una build (`POST /v1/services/<id>/deploys` con `commitId`).

bex costruisce un servizio alla volta e l'API per ultima, quindi un rollout completo può richiedere quasi un'ora. Prima di sincronizzare un Blueprint più recente in uno stack che contiene dati, leggi [Aggiornare uno stack già in esecuzione](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running) ed esegui prima il backup.

## Backup e ripristino

I ledger sono repository Git sul disco di Gitea. Account, personal access token e impostazioni risiedono nel Postgres gestito. Esegui il backup di ciascuno a modo suo.

### I ledger

Un clone mirror è un backup completo dei file e della cronologia di un ledger:

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

Eseguilo su una macchina dove è stato eseguito `bea cloud git setup`, oppure con l'helper dei token di **Git senza bea**. Per ripristinare, elimina il ledger nella dashboard se è ancora elencato e creane uno con lo stesso nome. Il server rifiuta un push forzato al branch principale di un ledger, quindi unisci il backup sopra il primo commit del nuovo ledger, usando un token con `ledger.write` quando non usi `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
```

### Il database

bex esegue il backup di `beancount-backend-db` in modo continuo e può ripristinarlo com'era in un momento precedente. Il ripristino avviene in un nuovo database, mai sul posto, quindi copi quel database sopra quello dello stack:

1. In bex, apri `beancount-backend-db`, scegli **Recovery**, seleziona un momento di almeno dieci minuti fa e ripristina. bex crea un nuovo database con i dati a quel momento.
2. Sospendi `beancount-api` e `beancount-gitea`, così nulla scrive durante il ripristino.
3. Copia i dati indietro con `pg_dump` e `pg_restore` di PostgreSQL 16 (l'immagine Docker `postgres:16` li contiene entrambi). Usa la stringa di connessione esterna di `beancount-backend-db` per entrambe le estremità, e per la copia cambia solo l'host con quello della copia. Non usare i dettagli di connessione che bex mostra per la copia; indicano un database e un utente che non possono leggere i dati ripristinati.

   ```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` segnala che potrebbe non riuscire a eliminare le estensioni `vector` e `pg_stat_statements`; quegli errori sono previsti. Se il certificato della copia è ancora in fase di emissione, aggiungi `?sslmode=verify-full` a `COPY_URL` e salva la CA che bex mostra per la copia come `~/.postgresql/root.crt`. Se la connessione va in timeout, riprova.
4. Riprendi `beancount-gitea` e `beancount-api`, poi elimina la copia.

## Cosa esce dal tuo workspace

Lo stack non invia analytics o telemetria a Beancount.io, e lo script di analytics del browser è escluso dalla build. Le uniche richieste in uscita di cui siamo a conoscenza sono:

- **Controllo delle password violate:** i primi cinque caratteri dell'hash SHA-1 della nuova password, verificati tramite k-anonymity, così né la password né l'account vengono rivelati.
- **Avatar:** il browser chiede a Gravatar un'immagine tramite un hash dell'indirizzo email dell'utente.
- **Feed:** i feed del blog e del changelog di Beancount.io, che ricevono solo una preferenza di lingua.
- **Feed dei prezzi:** richieste a beancount.io solo quando un ledger include un URL di prezzi gestito.
- **Le tue integrazioni:** qualunque cosa tu colleghi, come un provider di modelli, SendGrid, S3, Plaid o il tuo provider di identità.

La [tabella sulla privacy in PRFAQ006](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) indica quando viene effettuata ciascuna richiesta. I tuoi servizi, il disco e il database vengono eseguiti sull'infrastruttura di bex, secondo la [politica sulla privacy](https://bex.co/privacy-policy) e i [termini di servizio](https://bex.co/terms-of-service) di bex. bex è sviluppato da Stargately, Inc., l'azienda dietro Beancount.io; il servizio Beancount.io ospitato è separato dal tuo stack e non custodisce nessuno dei suoi secret.

## Rimuovi lo stack

:::warning
Eliminare le risorse ferma la fatturazione e cancella i tuoi dati insieme ad esse. Clona prima ogni ledger.
:::

Esegui il backup come descritto sopra, poi elimina le sei risorse in bex, seguite dal Blueprint. Per rimuovere solo il tuo account e mantenere lo stack, eliminalo in **Settings → General → Danger Zone**, come sul [servizio ospitato](https://beancount.io/it/docs/request-to-delete-account); eliminare l'unico account riapre la registrazione.

## Eseguilo invece sul tuo server

La [distribuzione Docker](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) esegue lo stesso stack su qualsiasi server tu controlli. Le [note sulla distribuzione bex](https://github.com/bex-co/beancount-io/tree/main/deploy/bex) trattano in modo più approfondito ogni impostazione di questa guida.

Hai incontrato un problema? Apri una [issue su GitHub](https://github.com/bex-co/beancount-io/issues) o chiedi nella [chat Telegram di Beancount](https://t.me/beancount).
