# Власний хостинг Beancount.io на bex одним кліком

Один клік розгортає весь стек Beancount.io, включно з вебпанеллю, API та MCP-сервером, сервісом реєстру та вашими реєстрами на основі Git, у робочий простір bex, яким ви володієте. Цей посібник проведе вас від натискання кнопки до робочого реєстру. Далі він охоплює підключення інструментів, додавання рахунків, оновлення, резервне копіювання та видалення стеку.

Стек поширюється за ліцензією MIT, не застосовує обмежень тарифних планів і коштує близько \$33 на місяць за хостинг, що виставляється вашому робочому простору. Щоб прочитати анонс, перейдіть до [Запустіть власний Beancount.io одним кліком](/blog/2026/11/18/run-your-own-beancount-io-from-one-button).

## Розгортання стеку

[![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. **Запустіть.** Натисніть **Deploy to bex.co**, виберіть робочий простір, який має володіти стеком, перегляньте план і застосуйте. Нічого не створюється, доки ви не схвалите попередній перегляд, і заповнювати нічого не потрібно: усі секрети генеруються всередині вашого робочого простору.
2. **Зачекайте на першу збірку.** У наших запусках вона тривала 27–30 хвилин, а довше — коли черга збірок bex завантажена. Сервіс, чиє розгортання позначене як невдале, не повторюється; розгорніть цей сервіс знову з панелі bex.
3. **Заявіть свій екземпляр.** Відкрийте URL сервісу `beancount-dashboard` і одразу зареєструйтеся. Кроку підтвердження електронної пошти немає, а реєстрація закривається після першого акаунта.
4. **Створіть реєстр.** Почніть із шаблону для початківців або завантажте зразковий реєстр, щоб роздивитися.

:::warning
Доки не існує першого акаунта, будь-хто, хто знайде адресу панелі, може його створити. Якщо хтось зареєструється раніше за вас, [видаліть цей акаунт за допомогою адміністративного токена стеку](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), щоб знову відкрити реєстрацію.
:::

![Реєстрація в новому розгортанні self-host. Поруч із формою сторінка повідомляє, що цей екземпляр керується його власником, а книги — це звичайний текст у Git.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

Кожен акаунт на self-host стеку отримує найвищий рівень: реєстри, директиви, співробітники та використання ШІ необмежені.

## Що працює і скільки це коштує

Blueprint створює шість ресурсів у вашому робочому просторі (ціни з попереднього перегляду плану bex на 2026-11-18):

| Ресурс bex | Що він робить | Місячна вартість (USD) |
| --- | --- | --- |
| `beancount-dashboard` | Вебзастосунок і єдина публічна адреса, яку ви використовуєте | 4.90 |
| `beancount-api` | GraphQL, REST, MCP-сервер і Git-проксі | 4.90 |
| `beancount-ledger` | Перевіряє та виконує запити до ваших книг (приватний, без публічної адреси) | 4.90 |
| `beancount-gitea` | Зберігає кожен реєстр як Git-репозиторій на диску 10 ГБ (приватний) | 6.65 |
| `beancount-backend-db` | Postgres для акаунтів, токенів і налаштувань | 4.41 |
| `beancount-cache` | Key Value для сесій входу та кешів | 7.21 |
| **Разом** | | **32.97** |

Постачальник моделі, поштовий сервіс або S3-бакет, які ви підключите, виставляються вам окремо.

## Увімкнення додаткових функцій

Стек запускається без жодної інтеграції. Функція, якій потрібна інтеграція, повідомляє, яке налаштування відсутнє. Щоб додати її, відкрийте сервіс `beancount-api` у bex, додайте змінні на його вкладці **Environment** і розгорніть сервіс знову. Змінна, яку ви додасте там, зберігається, коли пізніше ви синхронізуєте Blueprint.

| Змінні | Що вони вмикають |
| --- | --- |
| `ANTHROPIC_API_KEY` або `OPENAI_API_KEY` | Сканування квитанцій, категоризацію та асистента. `bea ask` потребує `OPENAI_API_KEY`. |
| `TEMP_ASSETS_AWS_S3_*` і `PERM_ASSETS_AWS_S3_*` (`BUCKET`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`) | Завантаження квитанцій і вкладень |
| `SEND_GRID_API_KEY` | Пошту, зокрема посилання для скидання пароля |
| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` | Вхід через ваш власний постачальник ідентифікації та більше акаунтів (див. **Додавання більшої кількості акаунтів**) |

## Підключення інструментів

Використовуйте адресу панелі всюди, крім Git, який використовує адресу API.

### CLI bea

Встановіть або оновіть [`bea`](https://beancount.io/uk/docs/Basics/bea-cli) за допомогою `uv tool install beancount-io` або `brew install bex-co/tap/bea`, потім налаштуйте його на вашу панель:

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

Обидві змінні приймають адресу панелі, оскільки панель пересилає трафік API. [Довідник Beancount CLI](https://beancount.io/uk/docs/bea-cli-reference) містить усі інші команди `bea cloud`.

### Агенти програмування через MCP

Додайте MCP-сервер розгортання до Claude Code або будь-якого MCP-клієнта:

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

Увійдіть за допомогою `/mcp` у Claude Code. Сторінку згоди надає ваш власний екземпляр; виберіть реєстр, який клієнт може використовувати, і схваліть. Для клієнта, який надсилає заголовок, створіть персональний токен доступу (нижче) і надішліть його як `Authorization: Bearer <token>`.

### Git через HTTPS

Кожен реєстр — це Git-репозиторій за адресою `https://<your API address>/git/<owner>/<ledger>.git`. Скопіюйте точну адресу з меню **Git Clone** реєстру. bex не маршрутизує SSH, тому Git працює через HTTPS. На машині з `bea` дозвольте йому виконувати вхід для 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
```

Після цього `git clone`, `git pull` і `git push` до цього хоста нічого не запитують, а `bea cloud logout` також видаляє вхід Git. `bea cloud ledger clone` клонує через SSH, тому в цьому стеку він натомість виводить команди вище.

![Меню Git Clone реєстру: HTTPS-адреса API з персональним токеном доступу як паролем.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### Git без bea

На CI-раннері або машині без `bea` виконайте вхід для Git за допомогою персонального токена доступу:

1. **Створіть токен.** У панелі відкрийте **Settings → Personal access tokens → New token**. Назвіть його за місцем роботи (`laptop`, `nightly-backup`), виберіть `ledger.read` для клонування та отримання змін, і додайте `ledger.write`, якщо він надсилає зміни. Для автоматизованого скрипта обмежте його одним реєстром і встановіть термін дії. Скопіюйте токен `bcio_` зараз; він показується лише один раз.
2. **Клонуйте.** Git запитає ім'я користувача та пароль: введіть будь-яке непорожнє ім'я користувача та вставте токен як пароль. macOS Keychain і Git Credential Manager у Windows збережуть його на наступний раз. У Linux спершу увімкніть помічник облікових даних, наприклад `git config --global credential.helper 'cache --timeout=86400'` (у пам'яті на добу).

![Settings, Personal access tokens: токен з ledger.read і ledger.write, його префікс, а також коли його створено й востаннє використано.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

У скрипті тримайте токен подалі від віддаленого URL, де Git зберіг би його в `.git/config`, і подалі від історії оболонки. Передайте його Git через одноразовий помічник облікових даних:

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

Порожній `-c credential.helper=` не дає збереженому помічникові зберегти токен. Передавайте обидва параметри `-c` кожному наступному `git fetch` або `git push` у скрипті.

Якщо Git продовжує пропонувати старий пароль або відкликаний токен, очистіть його:

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

### Мобільний застосунок

На екрані привітання застосунку [iOS](/beancount-ios) або [Android](/beancount-android) відкрийте налаштування, встановіть URL сервера на адресу вашої панелі та увійдіть.

## Перенесення наявних книг

Створіть реєстр у панелі, клонуйте його, злийте свої файли або свою історію Git у нього та надішліть зміни. Стек відкриває `main.bean` як точку входу реєстру, тому назвіть свій кореневий файл `main.bean` або використайте `main.bean`, щоб через `include` підключити ваші наявні файли.

## Додавання більшої кількості акаунтів

Реєстрація залишається закритою після першого акаунта. Інші люди приєднуються через постачальника OpenID Connect, який ви підключите, і який також обробляє їхній двофакторний вхід. На вкладці **Environment** сервісу `beancount-api`:

1. Встановіть `OIDC_ISSUER`, `OIDC_CLIENT_ID` і `OIDC_CLIENT_SECRET`, а також зареєструйте `https://<your dashboard address>/api-gateway/auth/oidc/callback` як URI перенаправлення клієнта. Потім сторінка входу пропонує **Sign in with** з наступним `OIDC_NAME` (за замовчуванням `SSO`).
2. Перелічіть, кому дозволено приєднатися, у `OIDC_ALLOWED_EMAILS` через коми: адреса (`alice@example.com`), домен (`@example.com`) або його піддомени (`@*.example.com`). Адреса зі списку, підтверджена, отримує акаунт і реєстр за замовчуванням під час першого входу. Без списку постачальник виконує вхід лише для акаунтів, уже пов'язаних з ним.

Кожен, кого ви впустите, ділить ваш диск і ключ моделі, без обмежень тарифних планів. З постачальником, до якого може приєднатися будь-хто, перелічуйте адреси, а не домен на кшталт `@gmail.com`.

## Скидання забутого пароля

Без `SEND_GRID_API_KEY` сторінка забутого пароля повідомляє користувачеві, що сервер не може надіслати електронний лист. Натомість видайте йому одноразове посилання для скидання через адміністративний API. Скопіюйте `ADMIN_TOKEN` з вкладки **Environment** сервісу `beancount-api` і звертайтеся до власної адреси `onbex.co` цього сервісу, а не до адреси панелі:

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

Надішліть повернутий `resetUrl` користувачеві через канал, якому ви довіряєте. Він працює один раз і втрачає чинність через годину.

:::warning
Адміністративний API доступний кожному, хто може дістатися до адреси API, і його захищає лише `ADMIN_TOKEN`. Токен може увійти як будь-який користувач, тому поводьтеся з ним як із паролем root: тримайте його подалі від історії оболонки та чатів і змініть його, якщо він міг витекти.
:::

## Оновлення до новішого випуску

Стек залишається на версії, яку ви розгорнули, доки ви його не оновите. Blueprint, створений кнопкою, не отримує push-вебхук, тому оновлення складається з двох кроків:

1. **Синхронізуйте Blueprint**, щоб застосувати зміни до його налаштувань (API bex: `POST /v1/blueprints/<id>/sync`).
2. **Розгорніть кожен сервіс на новому коміті**, оскільки зміни коду потребують збірки (`POST /v1/services/<id>/deploys` з `commitId`).

bex збирає по одному сервісу за раз, а API збирається останнім, тому повне розгортання може тривати більшу частину години. Перш ніж синхронізувати новіший Blueprint у стек, що містить дані, прочитайте [Оновлення стеку, який уже працює](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running) і спершу створіть резервну копію.

## Резервне копіювання та відновлення

Реєстри — це Git-репозиторії на диску Gitea. Акаунти, персональні токени доступу та налаштування зберігаються в керованому Postgres. Робіть резервну копію кожного своїм способом.

### Реєстри

Дзеркальний клон — це повна резервна копія файлів і історії реєстру:

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

Запускайте його на машині, де виконано `bea cloud git setup`, або з помічником токена з **Git без bea**. Щоб відновити, видаліть реєстр у панелі, якщо він усе ще в списку, і створіть реєстр із тією самою назвою. Сервер відхиляє примусове надсилання до основної гілки реєстру, тому злийте резервну копію поверх першого коміту нового реєстру, використовуючи токен із `ledger.write`, коли ви не використовуєте `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
```

### База даних

bex безперервно створює резервні копії `beancount-backend-db` і може відновити її в стані на попередній момент. Вона відновлюється в нову базу даних, ніколи не на місці, тому ви копіюєте цю базу даних назад поверх власної бази стеку:

1. У bex відкрийте `beancount-backend-db`, виберіть **Recovery**, виберіть час щонайменше десять хвилин тому та відновіть. bex створює нову базу даних із даними станом на цей час.
2. Призупиніть `beancount-api` і `beancount-gitea`, щоб нічого не писало під час відновлення.
3. Скопіюйте дані назад за допомогою `pg_dump` і `pg_restore` з PostgreSQL 16 (образ Docker `postgres:16` містить обидва). Використовуйте зовнішній рядок підключення `beancount-backend-db` для обох кінців, а для копії змініть лише хост на хост копії. Не використовуйте дані підключення, які bex показує для копії; вони вказують базу даних і користувача, які не можуть читати відновлені дані.

   ```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` повідомляє, що не може видалити розширення `vector` і `pg_stat_statements`; ці помилки очікувані. Якщо сертифікат копії ще видається, додайте `?sslmode=verify-full` до `COPY_URL` і збережіть CA, який bex показує для копії, як `~/.postgresql/root.crt`. Якщо підключення перевищує час очікування, повторіть спробу.
4. Відновіть `beancount-gitea` і `beancount-api`, потім видаліть копію.

## Що залишає ваш робочий простір

Стек не надсилає жодної аналітики чи телеметрії до Beancount.io, а скрипт браузерної аналітики виключено зі збірки. Єдині вихідні запити, про які нам відомо:

- **Перевірка витоків паролів:** перші п'ять символів SHA-1-хешу нового пароля, перевірені за допомогою k-анонімності, тож не розкривається ні пароль, ні акаунт.
- **Аватари:** браузер запитує зображення в Gravatar за хешем адреси електронної пошти користувача.
- **Стрічки:** стрічки блогу Beancount.io та журналу змін, які отримують лише мовне налаштування.
- **Стрічки цін:** запити до beancount.io лише тоді, коли реєстр містить керований URL цін.
- **Ваші інтеграції:** усе, що ви підключите, наприклад постачальник моделі, SendGrid, S3, Plaid або ваш постачальник ідентифікації.

[Таблиця конфіденційності в PRFAQ006](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) вказує, коли спрацьовує кожен запит. Ваші сервіси, диск і база даних працюють на інфраструктурі bex, згідно з [політикою конфіденційності](https://bex.co/privacy-policy) та [умовами надання послуг](https://bex.co/terms-of-service) bex. bex створено компанією Stargately, Inc., компанією, що стоїть за Beancount.io; хостинговий сервіс Beancount.io відокремлений від вашого стеку й не містить жодного з його секретів.

## Видалення стеку

:::warning
Видалення ресурсів зупиняє рахунок і разом з ними видаляє ваші дані. Спершу клонуйте кожен реєстр.
:::

Створіть резервну копію, як описано вище, потім видаліть шість ресурсів у bex, а згодом — Blueprint. Щоб видалити лише власний акаунт і залишити стек, видаліть його в розділі **Settings → General → Danger Zone**, як у [хостинговому сервісі](https://beancount.io/uk/docs/request-to-delete-account); видалення єдиного акаунта знову відкриває реєстрацію.

## Запуск на власному сервері натомість

[Розгортання Docker](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) запускає той самий стек на будь-якому сервері, яким ви керуєте. [Примітки до розгортання bex](https://github.com/bex-co/beancount-io/tree/main/deploy/bex) докладніше описують кожне налаштування з цього посібника.

Натрапили на проблему? Відкрийте [GitHub issue](https://github.com/bex-co/beancount-io/issues) або запитайте в [Telegram-чаті Beancount](https://t.me/beancount).
