Naar hoofdinhoud springen

Beancount.io zelf hosten op bex met één klik

Implementeer Beancount.io met één klik in je eigen bex-workspace, verbind daarna bea, MCP-clients, Git en de mobiele app, voeg accounts toe en maak back-ups.

Met één klik wordt de volledige Beancount.io-stack geïmplementeerd — inclusief het webdashboard, de API en MCP-server, de grootboekdienst en je door Git ondersteunde grootboeken — in een bex-workspace die je bezit. Deze handleiding gaat van de knop naar een werkend grootboek. Daarna behandelt het verbinden van je tools, het toevoegen van accounts, bijwerken, back-uppen en het verwijderen van de stack.

De stack heeft een MIT-licentie, kent geen abonnementslimieten en kost ongeveer $33 per maand aan hosting, gefactureerd aan je workspace. Lees de aankondiging in Start je eigen Beancount.io met één klik.

De stack implementeren​

Implementeren op bex.co

  1. Start het. Druk op Deploy to bex.co, kies de workspace die de stack moet bezitten, bekijk het plan en pas het toe. Er wordt niets aangemaakt totdat je de preview goedkeurt, en er hoeft niets te worden ingevuld: elk geheim wordt binnen je workspace gegenereerd.
  2. Wacht op de eerste build. Dit duurde in onze tests 27–30 minuten, en langer wanneer de buildwachtrij van bex druk is. Een dienst waarvan de rollout als mislukt is gemarkeerd, wordt niet opnieuw geprobeerd; implementeer die dienst opnieuw vanuit het bex-dashboard.
  3. Claim je instantie. Open de URL van de beancount-dashboard-dienst en meld je direct aan. Er is geen stap voor e-mailverificatie, en de aanmelding sluit zodra het eerste account bestaat.
  4. Maak een grootboek. Begin met de startersjabloon, of laad het voorbeeldgrootboek om rond te kijken.
waarschuwing

Zolang het eerste account nog niet bestaat, kan iedereen die het adres van het dashboard vindt, het aanmaken. Als iemand zich vóór jou aanmeldt, verwijder dat account dan met het admin-token van de stack om de aanmelding weer te openen.

Aanmelding op een nieuwe self-hosted implementatie. Naast het formulier staat op de pagina dat deze kopie door de eigenaar wordt beheerd en dat de boeken platte tekst in Git zijn.

Elk account op een self-hosted stack krijgt het hoogste niveau: grootboeken, directives, medewerkers en AI-gebruik zijn onbeperkt.

Wat er draait en wat het kost​

De Blueprint maakt zes resources aan in je workspace (prijzen uit de plan-preview van bex op 2026-11-18):

bex-resourceWat het doetMaandelijkse kosten (USD)
beancount-dashboardDe webapp, en het enige openbare adres dat je gebruikt4.90
beancount-apiGraphQL, REST, de MCP-server en de Git-proxy4.90
beancount-ledgerValideert en doorzoekt je boeken (privé, geen openbaar adres)4.90
beancount-giteaSlaat elk grootboek op als Git-repository op een schijf van 10 GB (privé)6.65
beancount-backend-dbPostgres voor accounts, tokens en instellingen4.41
beancount-cacheKey Value voor aanmeldsessies en caches7.21
Totaal32.97

Een modelprovider, maildienst of S3-bucket die je verbindt, wordt apart gefactureerd.

Optionele functies inschakelen​

De stack start zonder enige integratie. Een functie die er een nodig heeft, meldt welke instelling ontbreekt. Om er een toe te voegen, open je de beancount-api-dienst in bex, voeg je de variabelen toe op het tabblad Environment en implementeer je de dienst opnieuw. Een variabele die je daar toevoegt, blijft behouden wanneer je de Blueprint later synchroniseert.

VariabelenWat ze inschakelen
ANTHROPIC_API_KEY of OPENAI_API_KEYBonnetjes scannen, categoriseren en de assistent. bea ask vereist OPENAI_API_KEY.
TEMP_ASSETS_AWS_S3_* en PERM_ASSETS_AWS_S3_* (BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY)Uploads van bonnetjes en bijlagen
SEND_GRID_API_KEYMail, zoals links voor het resetten van wachtwoorden
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRETAanmelden via je eigen identiteitsprovider, en meer accounts (zie Meer accounts toevoegen)

Je tools verbinden​

Gebruik overal het adres van het dashboard, behalve voor Git; dat gebruikt het adres van de API.

De bea CLI​

Installeer of update bea met uv tool install beancount-io of brew install bex-co/tap/bea, en wijs het naar je dashboard:

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

Beide variabelen gebruiken het adres van het dashboard, omdat het dashboard API-verkeer doorstuurt. De Beancount CLI-referentie vermeldt elk ander bea cloud-commando.

Codeeragents via MCP​

Voeg de MCP-server van de implementatie toe aan Claude Code of een andere MCP-client:

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

Meld je aan met /mcp in Claude Code. De toestemmingspagina wordt geserveerd door je eigen instantie; kies het grootboek dat de client mag gebruiken en keur het goed. Voor een client die in plaats daarvan een header verstuurt, maak je een persoonlijk toegangstoken aan (hieronder) en verstuur je dat als Authorization: Bearer <token>.

Git over HTTPS​

Elk grootboek is een Git-repository op https://<your API address>/git/<owner>/<ledger>.git. Kopieer het exacte adres uit het menu Git Clone van het grootboek. bex routeert geen SSH, dus Git werkt via HTTPS. Laat Git op een machine met bea aanmelden via:

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

Daarna vragen git clone, git pull en git push naar die host om niets meer, en bea cloud logout verwijdert ook de Git-aanmelding. bea cloud ledger clone kloont via SSH en drukt op deze stack daarom de bovenstaande commando's af.

Het Git Clone-menu van een grootboek: het HTTPS-adres van de API, met een persoonlijk toegangstoken als wachtwoord.

Git zonder bea​

Op een CI-runner of een machine zonder bea meld je Git aan met een persoonlijk toegangstoken:

  1. Maak een token aan. Open in het dashboard Settings → Personal access tokens → New token. Geef het een naam die past bij waar het draait (laptop, nightly-backup), kies ledger.read om te klonen en pullen, en voeg ledger.write toe als het pusht. Beperk het voor een onbeheerd script tot één grootboek en stel een vervaldatum in. Kopieer nu het bcio_-token; het wordt maar één keer getoond.
  2. Kloon. Git vraagt om een gebruikersnaam en een wachtwoord: voer een willekeurige niet-lege gebruikersnaam in en plak het token als wachtwoord. macOS Keychain en Git Credential Manager op Windows bewaren het voor de volgende keer. Schakel op Linux eerst een credential helper in, bijvoorbeeld git config --global credential.helper 'cache --timeout=86400' (een dag in het geheugen).

Settings, Personal access tokens: een token met ledger.read en ledger.write, het voorvoegsel, en wanneer het is aangemaakt en voor het laatst gebruikt.

Houd het token in een script buiten de remote-URL, waar Git het in .git/config zou opslaan, en buiten de shellgeschiedenis. Geef het aan Git via een eenmalige credential helper:

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

De lege -c credential.helper= voorkomt dat een opgeslagen helper het token bewaart. Geef beide -c-opties mee aan elke latere git fetch of git push in het script.

Als Git blijft vragen om een oud wachtwoord of een ingetrokken token, wis het dan:

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

De mobiele app​

Open op het welkomstscherm van de iOS- of Android-app de instellingen, stel de server-URL in op je dashboardadres en meld je aan.

Je bestaande boeken meenemen​

Maak een grootboek aan in het dashboard, kloon het, voeg je bestanden of je Git-geschiedenis erin samen en push. De stack opent main.bean als het ingangspunt van het grootboek, dus noem je hoofd辣bestand main.bean of gebruik main.bean om je bestaande bestanden te include-en.

Meer accounts toevoegen​

De aanmelding blijft gesloten na het eerste account. Meer mensen sluiten zich aan via een OpenID Connect-provider die je verbindt, die ook hun tweestapsaanmelding afhandelt. Op het tabblad Environment van de beancount-api-dienst:

  1. Stel OIDC_ISSUER, OIDC_CLIENT_ID en OIDC_CLIENT_SECRET in en registreer https://<your dashboard address>/api-gateway/auth/oidc/callback als de redirect-URI van de client. De aanmeldpagina biedt dan Sign in with gevolgd door OIDC_NAME (standaard SSO).
  2. Vermeld wie mag joinen in OIDC_ALLOWED_EMAILS, gescheiden door komma's: een adres ([email protected]), een domein (@example.com) of de subdomeinen ervan (@*.example.com). Een vermeld, geverifieerd adres krijgt bij de eerste aanmelding een account en een standaardgrootboek. Zonder de lijst meldt de provider alleen accounts aan die er al aan gekoppeld zijn.

Iedereen die je toelaat, deelt je schijf en modelsleutel, zonder abonnementslimieten. Met een provider waar iedereen kan joinen, vermeld je adressen in plaats van een domein zoals @gmail.com.

Een vergeten wachtwoord resetten​

Zonder SEND_GRID_API_KEY meldt de pagina voor vergeten wachtwoorden de gebruiker dat de server geen e-mail kan versturen. Geef hun in plaats daarvan een eenmalige resetlink uit de admin-API. Kopieer ADMIN_TOKEN van het tabblad Environment van de beancount-api-dienst en gebruik het eigen onbex.co-adres van die dienst, niet dat van het dashboard:

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

Stuur de teruggegeven resetUrl naar de gebruiker via een kanaal dat je vertrouwt. Deze werkt één keer en verloopt na een uur.

waarschuwing

De admin-API is bereikbaar voor iedereen die het adres van de API kan bereiken, en alleen ADMIN_TOKEN beveiligt hem. Het token kan zich als elke gebruiker aanmelden, dus behandel het als een root-wachtwoord: houd het buiten de shellgeschiedenis en chat, en roteer het als het mogelijk is uitgelekt.

Bijwerken naar een nieuwere release​

De stack blijft op de versie die je hebt geïmplementeerd totdat je hem bijwerkt. Een Blueprint die via de knop is aangemaakt, krijgt geen push-webhook, dus een update kost twee stappen:

  1. Synchroniseer de Blueprint om wijzigingen in de instellingen toe te passen (bex API: POST /v1/blueprints/<id>/sync).
  2. Implementeer elke dienst op de nieuwe commit, omdat codewijzigingen een build vereisen (POST /v1/services/<id>/deploys met commitId).

bex bouwt één dienst tegelijk en de API bouwt als laatste, dus een volledige rollout kan bijna een uur duren. Lees voordat je een nieuwere Blueprint synchroniseert in een stack die gegevens bevat Een al draaiende stack upgraden en maak eerst een back-up.

Back-uppen en herstellen​

Grootboeken zijn Git-repositories op de schijf van Gitea. Accounts, persoonlijke toegangstokens en instellingen staan in de beheerde Postgres. Maak van elk op zijn eigen manier een back-up.

Grootboeken​

Een mirror-clone is een volledige back-up van de bestanden en geschiedenis van een grootboek:

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

Voer dit uit op een machine waar bea cloud git setup is uitgevoerd, of met de token-helper uit Git zonder bea. Om te herstellen, verwijder je het grootboek in het dashboard als het nog in de lijst staat en maak je een nieuw aan met dezelfde naam. De server weigert een geforceerde push naar de hoofdtak van een grootboek, dus voeg je de back-up samen bovenop de eerste commit van het nieuwe grootboek, met een token met ledger.write als je geen bea gebruikt:

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

De database​

bex maakt continu back-ups van beancount-backend-db en kan deze herstellen zoals die er op een eerder tijdstip uitzag. Het herstelt naar een nieuwe database, nooit ter plaatse, dus je kopieert die database terug over die van de stack zelf:

  1. Open in bex beancount-backend-db, kies Recovery, kies een tijdstip van ten minste tien minuten geleden en herstel. bex maakt een nieuwe database aan met de gegevens van dat tijdstip.

  2. Schort beancount-api en beancount-gitea op, zodat er niets schrijft terwijl je herstelt.

  3. Kopieer de gegevens terug met pg_dump en pg_restore van PostgreSQL 16 (de Docker-image postgres:16 heeft beide). Gebruik de externe verbindingsstring van beancount-backend-db voor beide kanten, en wijzig voor de kopie alleen de host naar die van de kopie. Gebruik niet de verbindingsgegevens die bex voor de kopie toont; die noemen een database en een gebruiker die de herstelde gegevens niet kunnen lezen.

    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 meldt dat het de extensies vector en pg_stat_statements mogelijk niet kan verwijderen; die fouten zijn te verwachten. Als het certificaat van de kopie nog wordt uitgegeven, voeg dan ?sslmode=verify-full toe aan COPY_URL en sla de CA die bex voor de kopie toont op als ~/.postgresql/root.crt. Als de verbinding een time-out geeft, probeer het dan opnieuw.

  4. Hervat beancount-gitea en beancount-api en verwijder daarna de kopie.

Wat je workspace verlaat​

De stack verstuurt geen analytics of telemetrie naar Beancount.io, en het analytics-script van de browser wordt niet in de build opgenomen. De enige uitgaande verzoeken die we kennen, zijn:

  • Controles op gecompromitteerde wachtwoorden: de eerste vijf tekens van de SHA-1-hash van een nieuw wachtwoord, gecontroleerd via k-anonimiteit, zodat noch het wachtwoord noch het account wordt onthuld.
  • Avatars: de browser vraagt Gravatar om een afbeelding op basis van een hash van het e-mailadres van de gebruiker.
  • Feeds: de blog- en changelog-feeds van Beancount.io, die alleen een taalvoorkeur ontvangen.
  • Prijsfeeds: verzoeken aan beancount.io, alleen wanneer een grootboek een beheerde prijs-URL bevat.
  • Je integraties: alles wat je verbindt, zoals een modelprovider, SendGrid, S3, Plaid of je identiteitsprovider.

De privacytabel in PRFAQ006 vermeldt wanneer elk verzoek plaatsvindt. Je diensten, schijf en database draaien op de infrastructuur van bex, onder het privacybeleid en de servicevoorwaarden van bex. bex is gebouwd door Stargately, Inc., het bedrijf achter Beancount.io; de gehoste Beancount.io-dienst staat los van je stack en bevat geen van zijn geheimen.

De stack verwijderen​

waarschuwing

Het verwijderen van de resources stopt de factuur en verwijdert je gegevens mee. Kloon eerst elk grootboek.

Maak een back-up zoals hierboven beschreven en verwijder daarna de zes resources in bex, gevolgd door de Blueprint. Om alleen je eigen account te verwijderen en de stack te behouden, verwijder je het onder Settings → General → Danger Zone, zoals op de gehoste dienst; door het enige account te verwijderen, wordt de aanmelding weer geopend.

In plaats daarvan op je eigen server draaien​

De Docker-implementatie draait dezelfde stack op elke server die je beheert. De bex-implementatienotities behandelen elke instelling in deze handleiding dieper.

Loop je ergens tegenaan? Open een GitHub-issue of vraag het in de Beancount Telegram-chat.

Bron: https://beancount.io/nl/docs/self-host-beancount-io