Pular para o conteúdo principal

Hospede o Beancount.io no bex com um clique

Implante o Beancount.io no seu próprio espaço de trabalho bex com um clique, conecte bea, clientes MCP, Git e o aplicativo móvel, adicione contas e faça backup.

Um único clique implanta toda a pilha do Beancount.io, incluindo o painel web, a API e o servidor MCP, o serviço de livro-razão (ledger) e seus livros-razão baseados em Git, em um espaço de trabalho bex de sua propriedade. Este guia vai do botão a um livro-razão funcional. Em seguida, ele cobre a conexão de suas ferramentas, adição de contas, atualização, backup e remoção da pilha.

A pilha tem licença MIT, não aplica limites de plano e custa cerca de US$ 33 por mês em hospedagem, faturado no seu espaço de trabalho. Para o anúncio, leia Execute seu próprio Beancount.io com um clique.

Implante a pilha​

Implantar no bex.co

  1. Lance-o. Pressione Deploy to bex.co (Implantar no bex.co), escolha o espaço de trabalho que deve ser o proprietário da pilha, revise o plano e aplique. Nada é criado até que você aprove a prévia, e não há nada para preencher: todos os segredos são gerados dentro do seu espaço de trabalho.
  2. Aguardar a primeira compilação. Levou de 27 a 30 minutos em nossos testes, e mais tempo quando a fila de compilação do bex está ocupada. Um serviço cujo lançamento esteja marcado como falhou não é retentado; implante esse serviço novamente a partir do painel do bex.
  3. Reivindique sua instância. Abra a URL do serviço beancount-dashboard e cadastre-se imediatamente. Não há etapa de verificação de e-mail, e o registro fecha após a primeira conta.
  4. Crie um livro-razão. Comece pelo modelo inicial ou carregue o livro-razão de exemplo para dar uma olhada.
aviso

Até que a primeira conta exista, qualquer pessoa que encontre o endereço do painel pode criá-la. Se alguém se cadastrar antes de você, remova essa conta usando o token de administrador da pilha para reabrir o cadastro.

Registro em um novo deployment auto-hospedado. Ao lado do formulário, a página diz que esta cópia é executada por seu proprietário e os livros são texto simples no Git.

Toda conta em uma pilha auto-hospedada recebe o nível superior: livros-razão, diretivas, colaboradores e uso de IA são ilimitados.

O que funciona e qual o custo​

O Blueprint cria seis recursos em seu espaço de trabalho (preços da prévia do plano do bex em 2026-11-18):

recurso bexO que fazCusto mensal (USD)
beancount-dashboardO aplicativo web e o endereço público que você usa4.90
beancount-apiGraphQL, REST, o servidor MCP e o proxy Git4.90
beancount-ledgerValida e consulta seus livros (privado, sem endereço público)4.90
beancount-giteaArmazena cada livro-razão como um repositório Git em um disco de 10 GB (privado)6.65
beancount-backend-dbPostgres para contas, tokens e configurações4.41
beancount-cacheKey Value para sessões de login e caches7.21
Total32.97

Um provedor de modelos, serviço de e-mail ou bucket S3 que você conectar cobrará separadamente.

Ative recursos opcionais​

A pilha inicia sem nenhuma integração. Um recurso que precisa de algo indica qual configuração está faltando. Para adicionar um, abra o serviço beancount-api no bex, adicione as variáveis na aba Environment (Ambiente) e implante o serviço novamente. Uma variável que você adiciona lá é mantida quando sincroniza o Blueprint mais tarde.

VariáveisO que elas ativam
ANTHROPIC_API_KEY ou OPENAI_API_KEYDigitalização de recibos, categorização e o assistente. O bea ask precisa de OPENAI_API_KEY.
TEMP_ASSETS_AWS_S3_* e PERM_ASSETS_AWS_S3_* (BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY)Upload de recibos e anexos
SEND_GRID_API_KEYE-mail, como links de redefinição de senha
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRETLogin através do seu próprio provedor de identidade e mais contas (veja Adicionar mais contas)

Conecte suas ferramentas​

Use o endereço do painel em todos os lugares, exceto para o Git, que usa o endereço da API.

A CLI do bea​

Instale ou atualize bea com uv tool install beancount-io ou brew install bex-co/tap/bea, depois aponte-o para o seu painel:

export BEA_API_URL=https://<seu endereço do dashboard>
export BEA_DASHBOARD_URL=https://<seu endereço do dashboard>
bea cloud login            # faz login através do seu navegador
bea cloud ledger list

Ambas as variáveis usam o endereço do dashboard, porque o dashboard encaminha o tráfego da API. A referência da CLI Beancount lista todos os outros comandos bea cloud.

Agentes de codificação via MCP​

Adicione o servidor MCP da implantação ao Claude Code ou a qualquer cliente MCP:

claude mcp add --transport http beancount \
  https://<seu endereço do dashboard>/api-gateway/mcp

Faça login com /mcp no Claude Code. A página de consentimento é servida pela sua própria instância; escolha o livro-razão que o cliente pode usar e aprove. Para um cliente que envia um cabeçalho em vez disso, crie um token de acesso pessoal (abaixo) e envie-o como Authorization: Bearer <token>.

Git via HTTPS​

Cada livro-razão é um repositório Git em https://<seu endereço da API>/git/<dono>/<ledger>.git. Copie o endereço exato do menu Git Clone do livro-razão. O bex não roteia SSH, então o Git é executado via HTTPS. Em uma máquina com bea, deixe-o fazer login no Git:

bea cloud login            # uma vez, se ainda não o fez
bea cloud git setup        # Agora o Git faz login com sua sessão bea
git clone https://<seu endereço da API>/git/<dono>/<ledger>.git

Depois disso, git clone, git pull e git push para esse host não pedem nada, e bea cloud logout remove o login do Git. O bea cloud ledger clone clona via SSH, então nesta pilha ele imprime os comandos acima em vez disso.

Menu Git Clone de um livro-razão: o endereço HTTPS da API, com um token de acesso pessoal como senha.

Git sem bea​

Em um executor CI ou em uma máquina sem bea, faça login no Git com um token de acesso pessoal:

  1. Crie um token. No painel, abra Settings → Personal access tokens → New token. Dê um nome para onde será executado (laptop, backup-diário), escolha ledger.read para clonar e puxar, e adicione ledger.write se fizer push. Para um script sem acompanhamento, limite a um livro-razão e defina um prazo de validade. Copie o token bcio_ agora; ele é mostrado apenas uma vez.
  2. Clone. O Git solicita um nome de usuário e uma senha: insira qualquer nome de usuário não vazio e cole o token como senha. O macOS Keychain e o Git Credential Manager no Windows guardam-no para a próxima vez. No Linux, ative um helper de credencial primeiro, por exemplo git config --global credential.helper 'cache --timeout=86400' (na memória por um dia).

Configurações, tokens de acesso pessoal: um token com ledger.read e ledger.write, seu prefixo, e quando foi criado e último uso.

Em um script, mantenha o token fora da URL remota, onde o Git o salvaria em .git/config, e fora do histórico do shell. Passe-o ao Git através de um helper de credencial único:

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://<seu endereço da API>/git/<dono>/<ledger>.git

O -c credential.helper= vazio impede que um helper armazenado salve o token. Passe ambos os argumentos -c a cada git fetch ou git push posterior no script.

Se o Git continuar oferecendo uma senha antiga ou um token revogado, limpe-o:

printf 'protocol=https\nhost=<seu endereço da API>\n\n' | git credential reject

O aplicativo móvel​

Na tela de boas-vindas do aplicativo iOS ou Android, abra as configurações, defina a URL do servidor para o endereço do seu painel e faça login.

Trazer seus livros existentes​

Crie um livro-razão no painel, clone-o, mescle seus arquivos ou seu histórico Git nele e envie (push). A pilha abre main.bean como o ponto de entrada do livro-razão, então nomeie seu arquivo raiz como main.bean ou use main.bean para include seus arquivos existentes.

Adicionar mais contas​

O cadastro permanece fechado após a primeira conta. Mais pessoas entram por meio de um provedor OpenID Connect que você conecta, o qual também lida com a autenticação de dois fatores delas. Na aba Environment do serviço beancount-api:

  1. Defina OIDC_ISSUER, OIDC_CLIENT_ID e OIDC_CLIENT_SECRET e registre https://<seu endereço do dashboard>/api-gateway/auth/oidc/callback como a URI de redirecionamento do cliente. A página de login oferece então Sign in with (Entrar com) seguido por OIDC_NAME (padrão SSO).
  2. Liste quem pode entrar em OIDC_ALLOWED_EMAILS, separados por vírgula: um endereço ([email protected]), um domínio (@example.com) ou seus subdomínios (@*.example.com). Um endereço listado e verificado recebe uma conta e um livro-razão padrão na primeira vez que faz login. Sem a lista, o provedor apenas faz login em contas já vinculadas a ele.

Todos os que você deixar entram com seu disco e chave de modelo, sem limites de plano. Com um provedor, qualquer um pode entrar; liste endereços em vez de um domínio como @gmail.com.

Redefinir uma senha esquecida​

Sem a SEND_GRID_API_KEY, a página de "esqueci a senha" informa ao usuário que o servidor não pode enviar e-mail. Forneça a ele um link de redefinição único a partir da API de administração em vez disso. Copie ADMIN_TOKEN da aba Environment do serviço beancount-api e chame o endereço onbex.co desse serviço, e não o do painel:

read -rs ADMIN_TOKEN; export ADMIN_TOKEN
curl -sS -X POST "https://<seu endereço da API>/api/admin/password-reset-link" \
  -H "x-admin-token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Envie o resetUrl retornado para o usuário por um canal em que confia. Funciona uma vez e expira após uma hora.

aviso

A API de administração é acessível por qualquer um que consiga acessar o endereço da API, e apenas o ADMIN_TOKEN a protege. O token pode fazer login como qualquer usuário, portanto, trate-o como uma senha raiz: mantenha-o fora do histórico do shell e de chats, e rotacione-o se houver chance de vazamento.

Atualizar para uma versão mais recente​

A pilha permanece na versão que você implantou até que você a atualize. Um Blueprint criado pelo botão não recebe um webhook de push, então uma atualização leva dois passos:

  1. Sincronize o Blueprint para aplicar mudanças em suas configurações (API bex: POST /v1/blueprints/<id>/sync).
  2. Implante cada serviço no novo commit, porque mudanças no código precisam de uma compilação (POST /v1/services/<id>/deploys com commitId).

O bex constrói um serviço por vez e a API é a última a ser construída, então um lançamento completo pode levar a maior parte de uma hora. Antes de sincronizar um Blueprint mais recente em uma pilha que contém dados, leia Atualizar uma pilha que já está rodando e faça backup primeiro.

Fazer backup e restaurar​

Os livros-razão são repositórios Git no disco do Gitea. Contas, tokens de acesso pessoal e configurações vivem no Postgres gerenciado. Faça backup de cada um da sua maneira.

Livros-razão​

Um clone espelho (mirror clone) é um backup completo dos arquivos e histórico de um livro-razão:

git clone --mirror https://<seu endereço da API>/git/<dono>/<ledger>.git

Execute em uma máquina onde bea cloud git setup foi executado, ou com o helper de token de Git sem bea. Para restaurar, exclua o livro-razão no painel se ainda estiver listado e crie um com o mesmo nome. O servidor se recusa a fazer push forçado para a branch principal de um livro-razão, então mescle o backup sobre o primeiro commit do novo livro-razão, usando um token com ledger.write quando não usar bea:

git clone https://<seu endereço da API>/git/<dono>/<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

O banco de dados​

O bex faz backup contínuo do beancount-backend-db e pode restaurá-lo como estava em um momento anterior. Ele restaura em um novo banco de dados, nunca no lugar, portanto, você copia esse banco de dados sobre o da pilha:

  1. No bex, abra beancount-backend-db, escolha Recovery (Recuperação), sele um momento de pelo menos dez minutos atrás e restaure. O bex cria um novo banco de dados com os dados até aquele momento.

  2. Suspend beancount-api e beancount-gitea, para que nada escreva enquanto você restaura.

  3. Copie os dados com pg_dump e pg_restore do PostgreSQL 16 (a imagem Docker postgres:16 tem ambos). Use a string de conexão externa do beancount-backend-db para ambos os lados, e para a cópia mude apenas o host para o da cópia. Não use os detalhes de conexão que o bex mostra para a cópia; eles nomeiam um banco de dados e um usuário que não conseguem ler os dados restaurados.

    read -rs DB_URL; export DB_URL   # string de conexão externa do beancount-backend-db
    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 relata que pode não remover as extensões vector e pg_stat_statements; esses erros são esperados. Se o certificado da cópia ainda estiver sendo emitido, adicione ?sslmode=verify-full ao COPY_URL e salve o CA que o bex mostra para a cópia como ~/.postgresql/root.crt. Se a conexão expirar, tente novamente.

  4. Retome beancount-gitea e beancount-api, e então exclua a cópia.

O que sai do seu espaço de trabalho​

A pilha não envia análise ou telemetria para o Beancount.io, e o script de análise do navegador está fora da compilação. Os únicos pedidos de saída que conhecemos são:

  • Verificações de violação de senha: os cinco primeiros caracteres do hash SHA-1 de uma nova senha, verificados por k-anônimos, para que nem a senha nem a conta sejam revelados.
  • Avatares: o navegador pede uma imagem ao Gravatar por um hash do endereço de e-mail do usuário.
  • Feeds: os feeds do blog e changelog do Beancount.io, que recebem apenas uma preferência de idioma.
  • Feeds de preços: solicitações ao beancount.io somente quando um livro-razão inclui uma URL de preço gerenciada.
  • Suas integrações: o que quer que você conecte, como um provedor de modelo, SendGrid, S3, Plaid ou seu provedor de identidade.

A tabela de privacidade em PRFAQ006 diz quando cada solicitação é disparada. Seus serviços, disco e banco de dados funcionam na infraestrutura do bex, sob a política de privacidade e termos de serviço do bex. O bex é construído pela Stargately, Inc., a empresa por trás do Beancount.io; o serviço Beancount.io hospedado é separado da sua pilha e não retém nenhum de seus segredos.

Remover a pilha​

aviso

Excluir os recursos interrompe a cobrança e apaga seus dados junto com eles. Clone todos os livros-razão primeiro.

Faça backup conforme descrito acima, então exclua os seis recursos no bex, seguidos pelo Blueprint. Para remover apenas sua própria conta e manter a pilha, exclua-a em Settings → General → Danger Zone (Configurações → Geral → Zona de Perigo), assim como no serviço hospedado; excluir a única conta reabre o cadastro.

Executar em seu próprio servidor em vez disso​

O deployment Docker executa a mesma pilha em qualquer servidor que você controle. As notas de implantação do bex cobrem cada configuração neste guia em mais detalhes.

Encontrou um problema? Abra uma issue no GitHub ou pergunte no chat do Telegram do Beancount.

Fonte: https://beancount.io/pt/docs/self-host-beancount-io