# Vlastné hostovanie Beancount.io na bex jedným kliknutím

Jediné kliknutie nasadí celý balík Beancount.io vrátane webového dashboardu, API a MCP servera, služby pre knihy a vašich kníh uložených v Git, do bex priestoru, ktorý vlastníte. Tento návod vás prevedie od stlačenia tlačidla až k funkčnej knihe. Ďalej sa venuje pripojeniu vašich nástrojov, pridávaniu účtov, aktualizácii, zálohovaniu a odstráneniu balíka.

Balík má licenciu MIT, neuplatňuje žiadne limity plánov a stojí približne \$33 mesačne za hosting, účtovaných vášmu priestoru. Oznámenie si prečítate v článku [Spustite si vlastné Beancount.io jedným kliknutím](/blog/2026/11/18/run-your-own-beancount-io-from-one-button).

## Nasaďte balík

[![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. **Spustite ho.** Stlačte **Deploy to bex.co**, vyberte priestor, ktorý má balík vlastniť, skontrolujte plán a potvrďte. Nič sa nevytvorí, kým neschválite náhľad, a netreba nič vypĺňať: každé tajomstvo sa vygeneruje vo vašom priestore.
2. **Počkajte na prvé zostavenie.** V našich beh m to trvalo 27–30 minút a dlhšie, keď je fronta zostavení v bex zaneprázdnená. Služba, ktorej nasadenie je označené ako zlyhané, sa neopakuje; nasaďte ju znova z bex dashboardu.
3. **Získajte svoju inštanciu.** Otvorte URL služby `beancount-dashboard` a hneď sa zaregistrujte. Neexistuje krok overovania e-mailom a registrácia sa po prvom účte uzavrie.
4. **Vytvorte knihu.** Začnite zo štartovacej šablóny alebo načítajte vzorovú knihu, aby ste sa rozhliadli.

:::warning
Kým neexistuje prvý účet, ktokoľvek, kto nájde adresu dashboardu, ho môže vytvoriť. Ak sa niekto zaregistruje pred vami, [odstráňte ten účet pomocou admin tokenu balíka](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), aby sa registrácia znova otvorila.
:::

![Registrácia na novom self-hosted nasadení. Vedľa formulára stránka uvádza, že túto kópiu prevádzkuje jej vlastník a knihy sú v Gite ako čistý text.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

Každý účet na self-hosted balíku získa najvyššiu úroveň: knihy, direktívy, spolupracujúce osoby a využitie AI sú neobmedzené.

## Čo beží a koľko to stojí

Blueprint vytvorí vo vašom priestore šesť zdrojov (ceny z náhľadu plánu v bex k 2026-11-18):

| Zdroj bex | Čo robí | Mesačný náklad (USD) |
| --- | --- | --- |
| `beancount-dashboard` | Webová aplikácia a jediná verejná adresa, ktorú použijete | 4,90 |
| `beancount-api` | GraphQL, REST, MCP server a Git proxy | 4,90 |
| `beancount-ledger` | Overuje a dopytuje vaše knihy (súkromná, bez verejnej adresy) | 4,90 |
| `beancount-gitea` | Ukladá každú knihu ako Git repozitár na 10 GB disku (súkromná) | 6,65 |
| `beancount-backend-db` | Postgres pre účty, tokeny a nastavenia | 4,41 |
| `beancount-cache` | Key Value pre prihlasovacie relácie a cache | 7,21 |
| **Spolu** | | **32,97** |

Poskytovateľ modelu, e-mailová služba alebo S3 bucket, ktoré pripojíte, sa účtujú zvlášť.

## Zapnite voliteľné funkcie

Balík sa spustí bez akékoľvek integrácie. Funkcia, ktorá nejakú potrebuje, uvedie, ktoré nastavenie chýba. Ak ju chcete pridať, otvorte službu `beancount-api` v bex, pridajte premenné na jej karte **Environment** a službu znova nasaďte. Premenná, ktorú tam pridáte, zostane zachovaná, keď neskôr synchronizujete Blueprint.

| Premenné | Čo zapnú |
| --- | --- |
| `ANTHROPIC_API_KEY` alebo `OPENAI_API_KEY` | Skenovanie dokladov, kategorizácia a asistent. `bea ask` potrebuje `OPENAI_API_KEY`. |
| `TEMP_ASSETS_AWS_S3_*` a `PERM_ASSETS_AWS_S3_*` (`BUCKET`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`) | Nahrávanie dokladov a príloh |
| `SEND_GRID_API_KEY` | E-mail, napríklad odkazy na obnovenie hesla |
| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` | Prihlásenie cez vášho vlastného poskytovateľa identity a viac účtov (pozri **Pridanie viacerých účtov**) |

## Pripojte svoje nástroje

Všade používajte adresu dashboardu okrem Gitu, ktorý používa adresu API.

### CLI nástroj bea

Nainštalujte alebo aktualizujte [`bea`](https://beancount.io/sk/docs/Basics/bea-cli) pomocou `uv tool install beancount-io` alebo `brew install bex-co/tap/bea` a potom ho nasmerujte na svoj 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
```

Obe premenné používajú adresu dashboardu, pretože dashboard preposiela prevádzku API. [Referencia Beancount CLI](https://beancount.io/sk/docs/bea-cli-reference) uvádza všetky ostatné príkazy `bea cloud`.

### Kódovací agenti cez MCP

Pridajte MCP server nasadenia do Claude Code alebo akéhokoľvek MCP klienta:

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

Prihláste sa pomocou `/mcp` v Claude Code. Stránku súhlasu poskytuje vaša vlastná inštancia; vyberte knihu, ktorú môže klient používať, a schváľte. Pre klienta, ktorý posiela hlavičku, vytvorte osobný prístupový token (nižšie) a pošlite ho ako `Authorization: Bearer <token>`.

### Git cez HTTPS

Každá kniha je Git repozitár na adrese `https://<your API address>/git/<owner>/<ledger>.git`. Skopírujte presnú adresu z ponuky **Git Clone** danej knihy. bex nesmeruje SSH, preto Git beží cez HTTPS. Na počítači s `bea` ho nechajte prihlásiť 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
```

Potom sa `git clone`, `git pull` a `git push` na tento hostiteľ nič nepýtajú a `bea cloud logout` odstráni aj prihlásenie Gitu. `bea cloud ledger clone` klonuje cez SSH, preto na tomto balíku vypíše vyššie uvedené príkazy.

![Ponuka Git Clone knihy: HTTPS adresa API s osobným prístupovým tokenom ako heslom.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### Git bez bea

Na CI runneri alebo počítači bez `bea` prihláste Git osobným prístupovým tokenom:

1. **Vytvorte token.** V dashboarde otvorte **Settings → Personal access tokens → New token**. Pomenujte ho podľa miesta, kde beží (`laptop`, `nightly-backup`), vyberte `ledger.read` na klonovanie a sťahovanie a ak nahráva, pridajte `ledger.write`. Pre automatizovaný skript ho obmedzte na jednu knihu a nastavte expiráciu. Skopírujte si token `bcio_` teraz; zobrazí sa len raz.
2. **Klonujte.** Git sa spýta na používateľské meno a heslo: zadajte akékoľvek neprázdne používateľské meno a vložte token ako heslo. macOS Keychain a Git Credential Manager vo Windows si ho ponechajú na nabudúce. V Linuxe najprv zapnite credential helper, napríklad `git config --global credential.helper 'cache --timeout=86400'` (v pamäti na jeden deň).

![Settings, Personal access tokens: token s ledger.read a ledger.write, jeho prefix a kedy bol vytvorený a naposledy použitý.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

V skripte držte token mimo URL vzdialeného repozitára, kde by ho Git uložil do `.git/config`, a mimo histórie shellu. Odovzdajte ho Gitu cez jednorazový credential helper:

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

Prázdny `-c credential.helper=` zabráni uloženému helperu uložiť token. Obe možnosti `-c` pridávajte ku každému ďalšiemu `git fetch` alebo `git push` v skripte.

Ak Git stále ponúka staré heslo alebo odvolaný token, vymažte ho:

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

### Mobilná aplikácia

Na uvítacej obrazovke aplikácie pre [iOS](/beancount-ios) alebo [Android](/beancount-android) otvorte nastavenia, nastavte URL servera na adresu svojho dashboardu a prihláste sa.

## Preneste svoje existujúce knihy

Vytvorte knihu v dashboarde, naklonujte ju, zlúčte do nej svoje súbory alebo svoju Git históriu a odošlite. Balík otvára `main.bean` ako vstupný bod knihy, preto svoj koreňový súbor pomenujte `main.bean` alebo cez `main.bean` zahrňte (`include`) svoje existujúce súbory.

## Pridanie viacerých účtov

Registrácia zostáva po prvom účte uzavretá. Ďalší ľudia sa pripájajú cez poskytovateľa OpenID Connect, ktorého pripojíte, a ten zabezpečuje aj ich dvojfaktorové prihlásenie. Na karte **Environment** služby `beancount-api`:

1. Nastavte `OIDC_ISSUER`, `OIDC_CLIENT_ID` a `OIDC_CLIENT_SECRET` a zaregistrujte `https://<your dashboard address>/api-gateway/auth/oidc/callback` ako redirect URI klienta. Prihlasovacia stránka potom ponúkne **Sign in with** nasledované `OIDC_NAME` (predvolene `SSO`).
2. Uveďte, kto sa môže pripojiť, v `OIDC_ALLOWED_EMAILS`, oddelené čiarkami: adresa (`alice@example.com`), doména (`@example.com`) alebo jej subdomény (`@*.example.com`). Uvedená overená adresa získa pri prvom prihlásení účet a predvolenú knihu. Bez zoznamu poskytovateľ prihlási len účty už prepojené s ním.

Každý, koho pustíte dnu, zdieľa váš disk a kľúč modelu bez limitov plánov. Pri poskytovateľovi, ku ktorému sa môže pripojiť ktokoľvek, uvádzajte adresy namiesto domény, ako napríklad `@gmail.com`.

## Obnovenie zabudnutého hesla

Bez `SEND_GRID_API_KEY` stránka pre zabudnuté heslo používateľovi oznámi, že server nemôže poslať e-mail. Vydajte mu namiesto toho jednorazový odkaz na obnovenie cez admin API. Skopírujte `ADMIN_TOKEN` z karty **Environment** služby `beancount-api` a volajte vlastnú adresu tejto služby v `onbex.co`, nie adresu dashboardu:

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

Vrátený `resetUrl` pošlite používateľovi cez kanál, ktorému dôverujete. Platí len raz a vyprší po hodine.

:::warning
Admin API je dostupné komukoľvek, kto sa dostane na adresu API, a chráni ho samotný `ADMIN_TOKEN`. Token sa môže prihlásiť ako ktorýkoľvek používateľ, preto s ním zaobchádzajte ako s root heslom: držte ho mimo histórie shellu a chatu a ak mohol uniknúť, vymeňte ho.
:::

## Aktualizácia na novšie vydanie

Balík zostáva na verzii, ktorú ste nasadili, kým ho neaktualizujete. Blueprint vytvorený tlačidlom nedostane push webhook, preto má aktualizácia dva kroky:

1. **Synchronizujte Blueprint**, aby sa zmeny jeho nastavení prejavili (bex API: `POST /v1/blueprints/<id>/sync`).
2. **Nasaďte každú službu na novom commite**, pretože zmeny kódu vyžadujú zostavenie (`POST /v1/services/<id>/deploys` s `commitId`).

bex zostavuje jednu službu naraz a API sa zostavuje ako posledné, preto celé nasadenie môže trvať takmer hodinu. Skôr než synchronizujete novší Blueprint do balíka, ktorý obsahuje dáta, prečítajte si [Aktualizácia už bežiaceho balíka](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running) a najprv zálohujte.

## Zálohovanie a obnova

Knihy sú Git repozitáre na disku Gitea. Účty, osobné prístupové tokeny a nastavenia žijú v spravovanom Postgres. Každé zálohujte vlastným spôsobom.

### Knihy

Mirror klon je úplná záloha súborov a histórie knihy:

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

Spustite ho na počítači, kde prebehol `bea cloud git setup`, alebo s tokenovým helperom z časti **Git bez bea**. Na obnovenie vymažte knihu v dashboarde, ak je stále uvedená, a vytvorte knihu s rovnakým názvom. Server odmietne vynútený push do hlavnej vetvy knihy, preto zálohu zlúčte navrch prvého commitu novej knihy a ak nepoužívate `bea`, použite token s `ledger.write`:

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

### Databáza

bex zálohuje `beancount-backend-db` priebežne a dokáže ju obnoviť do stavu z určitého skoršieho času. Obnovuje do novej databázy, nikdy na mieste, preto túto databázu skopírujete späť cez vlastnú databázu balíka:

1. V bex otvorte `beancount-backend-db`, zvoľte **Recovery**, vyberte čas aspoň pred desiatimi minútami a obnovte. bex vytvorí novú databázu s dátami k tomu času.
2. Pozastavte `beancount-api` a `beancount-gitea`, aby počas obnovy nič nezapisovalo.
3. Skopírujte dáta späť pomocou `pg_dump` a `pg_restore` z PostgreSQL 16 (Docker obraz `postgres:16` má oba). Pre oba konce použite externý reťazec pripojenia `beancount-backend-db` a pri kopírovaní zmeňte len hostiteľa na hostiteľa kópie. Nepoužívajte údaje pripojenia, ktoré bex zobrazuje pre kópiu; označujú databázu a používateľa, ktorí nedokážu čítať obnovené dáta.

   ```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` hlási, že nemusí vedieť odstrániť rozšírenia `vector` a `pg_stat_statements`; tieto chyby sú očakávané. Ak sa certifikát kópie ešte vydáva, pridajte `?sslmode=verify-full` k `COPY_URL` a uložte CA, ktoré bex zobrazuje pre kópiu, ako `~/.postgresql/root.crt`. Ak pripojenie vyprší, skúste to znova.
4. Obnovte `beancount-gitea` a `beancount-api` a potom kópiu vymažte.

## Čo opúšťa váš priestor

Balík neposiela Beancount.io žiadnu analytiku ani telemetriu a skript analytiky v prehliadači je zo zostavenia vynechaný. Jediné odchádzajúce požiadavky, o ktorých vieme, sú:

- **Kontroly úniku hesiel:** prvých päť znakov SHA-1 hashu nového hesla, kontrolovaných metódou k-anonymity, takže sa neprezradí ani heslo, ani účet.
- **Avatary:** prehliadač žiada Gravatar o obrázok podľa hashu e-mailovej adresy používateľa.
- **Kanály:** kanály blogu a changelogu Beancount.io, ktoré dostanú len jazykovú preferenciu.
- **Kanály s cenami:** požiadavky na beancount.io len vtedy, keď kniha obsahuje spravovanú URL s cenami.
- **Vaše integrácie:** čokoľvek, čo pripojíte, napríklad poskytovateľa modelu, SendGrid, S3, Plaid alebo poskytovateľa identity.

[Tabuľka súkromia v PRFAQ006](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) uvádza, kedy sa každá požiadavka spustí. Vaše služby, disk a databáza bežia na infraštruktúre bex, podľa [zásad ochrany súkromia](https://bex.co/privacy-policy) a [podmienok služby](https://bex.co/terms-of-service) bex. bex stavia Stargately, Inc., spoločnosť za Beancount.io; hostovaná služba Beancount.io je oddelená od vášho balíka a nedrží žiadne jeho tajomstvá.

## Odstránenie balíka

:::warning
Vymazanie zdrojov zastaví účtovanie a vymaže s ním aj vaše dáta. Najprv naklonujte každú knihu.
:::

Zálohujte podľa vyššie uvedeného postupu a potom vymažte šesť zdrojov v bex a nakoniec Blueprint. Ak chcete odstrániť len svoj vlastný účet a balík zachovať, vymažte ho v časti **Settings → General → Danger Zone**, ako na [hostovanej službe](https://beancount.io/sk/docs/request-to-delete-account); vymazaním jediného účtu sa registrácia znova otvorí.

## Namiesto toho to spustite na vlastnom serveri

[Docker nasadenie](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) spúšťa ten istý balík na akomkoľvek serveri, ktorý ovládate. [Poznámky k nasadeniu na bex](https://github.com/bex-co/beancount-io/tree/main/deploy/bex) podrobnejšie pokrývajú každé nastavenie v tomto návode.

Narazili ste na problém? Otvorte [GitHub issue](https://github.com/bex-co/beancount-io/issues) alebo sa spýtajte v [Beancount Telegram chate](https://t.me/beancount).
