# bex에서 클릭 한 번으로 Beancount.io 셀프 호스팅하기

클릭 한 번이면 웹 대시보드, API 및 MCP 서버, 원장 서비스, 그리고 Git으로 관리되는 원장을 포함한 Beancount.io 스택 전체가 여러분이 소유한 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. **인스턴스를 확보하세요.** `beancount-dashboard` 서비스의 URL을 열고 즉시 가입하세요. 이메일 인증 단계가 없으며, 첫 번째 계정이 생성되면 가입이 닫힙니다.
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)하여 가입을 다시 열 수 있습니다.
:::

![새로 셀프 호스팅한 배포에서의 가입 화면. 양식 옆에 이 페이지는 소유자가 운영하며 장부는 Git에 있는 평문이라고 적혀 있습니다.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

셀프 호스팅 스택의 모든 계정은 최상위 등급을 받습니다. 원장, 지시문, 협업자, AI 사용량이 무제한입니다.

## 실행되는 항목과 비용

Blueprint는 워크스페이스에 여섯 개의 리소스를 생성합니다 (가격은 2026-11-18 기준 bex 요금제 미리보기에서 가져옴):

| bex 리소스 | 역할 | 월 비용 (USD) |
| --- | --- | --- |
| `beancount-dashboard` | 웹 앱이자 사용하는 유일한 공개 주소 | 4.90 |
| `beancount-api` | GraphQL, REST, MCP 서버, Git 프록시 | 4.90 |
| `beancount-ledger` | 장부 검증 및 쿼리 (비공개, 공개 주소 없음) | 4.90 |
| `beancount-gitea` | 각 원장을 10 GB 디스크의 Git 저장소로 저장 (비공개) | 6.65 |
| `beancount-backend-db` | 계정, 토큰, 설정용 Postgres | 4.41 |
| `beancount-cache` | 로그인 세션 및 캐시용 Key Value | 7.21 |
| **합계** | | **32.97** |

연결하는 모델 제공자, 메일 서비스, S3 버킷은 별도로 청구됩니다.

## 선택 기능 켜기

스택은 어떤 통합 없이도 부팅됩니다. 통합이 필요한 기능은 어떤 설정이 빠졌는지 알려줍니다. 통합을 추가하려면 bex에서 `beancount-api` 서비스를 열고 **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` | 직접 운영하는 ID 제공자를 통한 로그인 및 추가 계정 (추가 계정 추가 참고) |

## 도구 연결하기

Git을 제외한 모든 곳에는 대시보드의 주소를 사용하세요. Git은 API의 주소를 사용합니다.

### bea CLI

`uv tool install beancount-io` 또는 `brew install bex-co/tap/bea`로 [`bea`](https://beancount.io/ko/docs/Basics/bea-cli)를 설치하거나 업데이트한 뒤, 대시보드를 가리키도록 설정하세요:

```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 트래픽을 전달하기 때문입니다. 다른 모든 `bea cloud` 명령은 [Beancount CLI 레퍼런스](https://beancount.io/ko/docs/bea-cli-reference)에 정리되어 있습니다.

### MCP를 통한 코딩 에이전트

Claude Code 또는 임의의 MCP 클라이언트에 배포된 MCP 서버를 추가하세요:

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

Claude Code에서 `/mcp`로 로그인하세요. 동의 페이지는 여러분의 인스턴스가 제공하며, 클라이언트가 사용할 원장을 선택하고 승인하세요. 대신 헤더를 보내는 클라이언트의 경우, 개인 액세스 토큰(아래 참고)을 만들어 `Authorization: Bearer <token>`으로 전송하세요.

### HTTPS를 통한 Git

모든 원장은 `https://<your API address>/git/<owner>/<ledger>.git`의 Git 저장소입니다. 원장의 **Git Clone** 메뉴에서 정확한 주소를 복사하세요. bex는 SSH를 라우팅하지 않으므로 Git은 HTTPS로 작동합니다. `bea`가 설치된 머신에서는 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 메뉴: 비밀번호로 개인 액세스 토큰을 사용하는 API의 HTTPS 주소.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### bea 없이 Git 사용하기

CI 러너나 `bea`가 없는 머신에서는 개인 액세스 토큰으로 Git에 로그인하세요:

1. **토큰을 만드세요.** 대시보드에서 **Settings → Personal access tokens → New token**을 여세요. 실행되는 위치에 맞춰 이름을 짓고(`laptop`, `nightly-backup`), clone 및 pull에는 `ledger.read`를 선택하고, push도 한다면 `ledger.write`를 추가하세요. 무인 스크립트라면 하나의 원장으로 제한하고 만료일을 설정하세요. 지금 `bcio_` 토큰을 복사하세요. 한 번만 표시됩니다.
2. **복제하세요.** Git이 사용자 이름과 비밀번호를 요청하면 임의의 비어 있지 않은 사용자 이름과 비밀번호로 토큰을 붙여넣으세요. macOS Keychain과 Windows의 Git Credential Manager는 다음 번을 위해 이를 저장합니다. 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)

스크립트에서는 토큰을 Git이 `.git/config`에 저장해버릴 원격 URL이나 셸 기록에 남기지 마세요. 일회성 자격 증명 헬퍼를 통해 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=`는 저장된 헬퍼가 토큰을 저장하지 못하도록 막습니다. 스크립트의 이후 모든 `git fetch` 또는 `git push`에도 두 `-c` 옵션을 전달하세요.

Git이 이전 비밀번호나 폐기된 토큰을 계속 제시한다면 삭제하세요:

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

### 모바일 앱

[iOS](/beancount-ios) 또는 [Android](/beancount-android) 앱의 환영 화면에서 설정을 열고, 서버 URL을 대시보드 주소로 설정한 뒤 로그인하세요.

## 기존 장부 가져오기

대시보드에서 원장을 만들고 복제한 뒤, 여러분의 파일이나 Git 이력을 병합하고 push하세요. 이 스택은 `main.bean`을 원장의 진입점으로 열므로, 루트 파일의 이름을 `main.bean`으로 짓거나 `main.bean`에서 기존 파일을 `include`하세요.

## 추가 계정 추가하기

첫 계정 이후로는 가입이 계속 닫혀 있습니다. 추가 인원은 여러분이 연결하는 OpenID Connect 제공자를 통해 참여하며, 이 제공자가 2단계 로그인도 처리합니다. `beancount-api` 서비스의 **Environment** 탭에서:

1. `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`을 설정하고, 클라이언트의 리디렉션 URI로 `https://<your dashboard address>/api-gateway/auth/oidc/callback`을 등록하세요. 그러면 로그인 페이지에 **Sign in with** 뒤에 `OIDC_NAME`(기본값 `SSO`)이 표시됩니다.
2. 누가 참여할 수 있는지 `OIDC_ALLOWED_EMAILS`에 쉼표로 구분하여 나열하세요: 주소(`alice@example.com`), 도메인(`@example.com`), 또는 그 하위 도메인(`@*.example.com`). 목록에 있는 검증된 주소는 처음 로그인할 때 계정과 기본 원장을 받습니다. 목록이 없으면 제공자는 이미 연결된 계정만 로그인시킵니다.

허용된 모든 사람이 여러분의 디스크와 모델 키를 공유하며, 요금제 제한은 없습니다. 누구나 가입할 수 있는 제공자라면 `@gmail.com`과 같은 도메인 대신 주소를 나열하세요.

## 잊어버린 비밀번호 재설정

`SEND_GRID_API_KEY`가 없으면 비밀번호 찾기 페이지는 서버가 이메일을 보낼 수 없다고 사용자에게 알려줍니다. 대신 관리자 API에서 일회성 재설정 링크를 발급하세요. `beancount-api` 서비스의 **Environment** 탭에서 `ADMIN_TOKEN`을 복사하고, 대시보드의 주소가 아닌 해당 서비스 자체의 `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`만이 이를 보호합니다. 이 토큰은 어떤 사용자로든 로그인할 수 있으므로 루트 비밀번호처럼 취급하세요: 셸 기록과 채팅에 남기지 말고, 유출 가능성이 있다면 교체하세요.
:::

## 최신 릴리스로 업데이트하기

스택은 여러분이 업데이트할 때까지 배포한 버전에 머뭅니다. 버튼으로 만든 Blueprint는 push 웹훅을 받지 않으므로, 업데이트에는 두 단계가 필요합니다:

1. **Blueprint를 동기화**하여 설정 변경을 적용하세요 (bex API: `POST /v1/blueprints/<id>/sync`).
2. **각 서비스를 새 커밋에서 배포**하세요. 코드 변경에는 빌드가 필요하기 때문입니다 (`commitId`와 함께 `POST /v1/services/<id>/deploys`).

bex는 한 번에 하나의 서비스를 빌드하고 API는 마지막에 빌드하므로, 전체 롤아웃은 거의 한 시간이 걸릴 수 있습니다. 데이터가 있는 스택에 최신 Blueprint를 동기화하기 전에 [이미 실행 중인 스택 업그레이드](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running)를 읽고 먼저 백업하세요.

## 백업 및 복원

원장은 Gitea 디스크의 Git 저장소입니다. 계정, 개인 액세스 토큰, 설정은 관리형 Postgres에 있습니다. 각각 방식에 맞게 백업하세요.

### 원장

미러 복제는 원장의 파일과 이력을 완전히 백업합니다:

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

`bea cloud git setup`을 실행한 머신에서, 또는 **bea 없이 Git 사용하기**의 토큰 헬퍼를 사용하여 실행하세요. 복원하려면 원장이 목록에 아직 남아 있는 경우 대시보드에서 삭제하고 같은 이름으로 새로 만드세요. 서버는 원장의 main 브랜치로의 강제 push를 거부하므로, `bea`를 사용하지 않는 경우 `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
```

### 데이터베이스

bex는 `beancount-backend-db`를 지속적으로 백업하며, 이전 시점의 상태로 복원할 수 있습니다. 복원은 항상 새 데이터베이스로 이루어지고 제자리에서는 절대 이루어지지 않으므로, 해당 데이터베이스를 스택 자체의 데이터베이스로 다시 복사합니다:

1. bex에서 `beancount-backend-db`를 열고 **Recovery**를 선택한 뒤, 최소 10분 전의 시점을 골라 복원하세요. bex는 해당 시점 기준 데이터를 담은 새 데이터베이스를 만듭니다.
2. 복원하는 동안 아무것도 쓰지 않도록 `beancount-api`와 `beancount-gitea`를 일시 중지하세요.
3. PostgreSQL 16의 `pg_dump`와 `pg_restore`로 데이터를 다시 복사하세요 (`postgres:16` Docker 이미지에 둘 다 있습니다). 양쪽 끝 모두에 `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` 확장을 삭제하지 못할 수 있다고 보고합니다. 이 오류는 예상된 것입니다. 복사본의 인증서가 아직 발급 중이라면 `COPY_URL`에 `?sslmode=verify-full`을 추가하고 bex가 복사본용으로 보여주는 CA를 `~/.postgresql/root.crt`로 저장하세요. 연결이 시간 초과되면 다시 시도하세요.
4. `beancount-gitea`와 `beancount-api`를 재개한 뒤 복사본을 삭제하세요.

## 워크스페이스 밖으로 나가는 것

이 스택은 Beancount.io로 애널리틱스나 텔레메트리를 전혀 보내지 않으며, 브라우저 애널리틱스 스크립트는 빌드에서 제외됩니다. 저희가 아는 유일한 외부 요청은 다음과 같습니다:

- **비밀번호 유출 확인:** k-익명성을 통해 확인되는, 새 비밀번호 SHA-1 해시의 처음 다섯 글자. 따라서 비밀번호와 계정 모두 노출되지 않습니다.
- **아바타:** 브라우저가 사용자 이메일 주소의 해시로 Gravatar에 이미지를 요청합니다.
- **피드:** Beancount.io 블로그와 변경 로그 피드로, 언어 설정만 전달됩니다.
- **가격 피드:** 원장에 관리형 가격 URL이 포함된 경우에만 beancount.io로 요청합니다.
- **여러분의 통합:** 모델 제공자, SendGrid, S3, Plaid, ID 제공자 등 연결하는 모든 것.

각 요청이 언제 발생하는지는 [PRFAQ006의 개인정보 표](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private)에 나와 있습니다. 여러분의 서비스, 디스크, 데이터베이스는 bex의 인프라에서 bex의 [개인정보 정책](https://bex.co/privacy-policy) 및 [서비스 약관](https://bex.co/terms-of-service)에 따라 실행됩니다. bex는 Beancount.io를 만든 회사인 Stargately, Inc.가 만들었습니다. 호스팅되는 Beancount.io 서비스는 여러분의 스택과 별개이며 스택의 시크릿을 하나도 보유하지 않습니다.

## 스택 제거하기

:::warning
리소스를 삭제하면 요금이 중단되는 동시에 데이터도 삭제됩니다. 먼저 모든 원장을 복제하세요.
:::

위에서 설명한 대로 백업한 뒤, bex에서 여섯 개의 리소스를 삭제하고 마지막으로 Blueprint를 삭제하세요. 스택은 유지하고 본인 계정만 제거하려면 [호스팅 서비스](https://beancount.io/ko/docs/request-to-delete-account)에서처럼 **Settings → General → Danger Zone**에서 삭제하세요. 유일한 계정을 삭제하면 가입이 다시 열립니다.

## 대신 직접 서버에서 실행하기

[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 이슈](https://github.com/bex-co/beancount-io/issues)를 열거나 [Beancount Telegram 채팅](https://t.me/beancount)에서 질문하세요.
