Como hospedar o Actual Budget no seu VPS

O que você vai criar

O Actual Budget é um aplicativo de orçamento por envelopes hospedado por você. Ele costuma ser a resposta quando as pessoas procuram uma alternativa ao YNAB que possam hospedar por conta própria. O servidor é um container, um volume de dados e um nome HTTPS. Tudo o que um orçamento comum precisa funciona tranquilamente no menor VPS que você puder alugar, porque o servidor principalmente armazena arquivos e os sincroniza.

Vale entender a arquitetura antes de executar qualquer comando. O orçamento em si é um banco de dados SQLite que fica no navegador e em cada aplicativo móvel. O servidor que você está prestes a instalar é um endpoint de sincronização. Ele mantém a lista de contas, os arquivos de orçamento e o log de alterações que permite que um telefone e um laptop mantenham os mesmos dados. Por isso, o aplicativo continua funcionando quando o servidor está indisponível. Também é por isso que perder o servidor não causa a perda do orçamento, desde que um cliente ainda mantenha uma cópia.

Por que o servidor precisa de HTTPS

O Actual exige HTTPS, e isso não é uma formalidade. Os navegadores só disponibilizam a Web Crypto API, a interface que o Actual usa para a criptografia de ponta a ponta, em um contexto seguro, como definido pela especificação. Um contexto seguro é https:// ou http://localhost. Carregue o aplicativo de http://203.0.113.10:5006 em um navegador de outra máquina, e esses recursos simplesmente não estarão disponíveis, porque o navegador nunca os forneceu à página. As versões móveis oficiais também recusam uma URL de servidor http:// simples.

Há duas configurações viáveis. Coloque um certificado válido para um nome real na frente do container, como este guia faz. Ou forneça ao servidor um certificado autoassinado com ACTUAL_HTTPS_KEY e ACTUAL_HTTPS_CERT, conforme documentado pelo projeto, e aceite um aviso do navegador em cada dispositivo. Um certificado gratuito do Let's Encrypt leva cinco minutos para ser obtido, portanto, escolha a primeira opção.

Instalar o Actual Budget com Docker Compose

Instale o Docker primeiro se o servidor for novo. Se a sintaxe do arquivo Compose for nova para você, o guia conceitos básicos do Docker Compose para um VPS explica os campos usados abaixo.

sudo install -d -m 755 /opt/actual
sudo install -d -m 700 /opt/actual/data

Escreva /opt/actual/docker-compose.yml:

services:
  actual:
    image: actualbudget/actual-server:latest
    container_name: actual
    restart: unless-stopped
    ports:
      - '127.0.0.1:5006:5006'
    volumes:
      - ./data:/data

Três detalhes desse arquivo são importantes.

A imagem é actualbudget/actual-server:latest, publicada pelo projeto no Docker Hub e espelhada em ghcr.io/actualbudget/actual. Existe uma tag latest-alpine para máquinas de baixo consumo.

O contêiner grava tudo em /data. Dentro dele, você encontra server-files, que contém account.sqlite com seus dados de login e tokens de sessão, e user-files, que contém os próprios arquivos de orçamento. Monte esse caminho, ou o próximo docker compose pull descartará seu orçamento. ACTUAL_DATA_DIR pode alterá-lo, mas o valor padrão é adequado.

A porta é publicada somente em 127.0.0.1. Um 5006:5006 sem endereço publica a porta em todas as interfaces, e o Docker aplica suas próprias regras antes do ufw. Assim, o aplicativo ficaria aberto à internet mesmo com um firewall que bloqueia tudo. Essa situação é explicada em por que as portas publicadas pelo Docker ignoram o ufw. Associar a porta ao loopback significa que somente o proxy reverso no mesmo servidor pode acessá-la.

Inicie o serviço:

cd /opt/actual
docker compose up --detach
docker compose logs -f actual

O log se estabiliza quando o servidor informa que está escutando na porta 5006. Verifique localmente antes de alterar o DNS:

curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5006/

Um 200 significa que o aplicativo está atendendo. Um curl: (7) Failed to connect significa que o contêiner não está em execução, e docker compose ps mostrará que ele foi encerrado. A causa comum é um problema de permissões no volume montado, visível como uma linha EACCES no log.

Coloque um certificado e um nome real na frente

Aponte um registro A para o VPS, budget.example.com, e aguarde a resolução. Em seguida, instale o nginx e emita o certificado. O guia Certbot no Ubuntu 24.04 com nginx explica detalhadamente a emissão e o temporizador de renovação.

O bloco de proxy:

server {
    listen 443 ssl;
    http2 on;
    server_name budget.example.com;

    ssl_certificate     /etc/letsencrypt/live/budget.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/budget.example.com/privkey.pem;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:5006;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

client_max_body_size é a linha que as pessoas esquecem. O arquivo de orçamento é enviado integralmente durante uma sincronização completa. O nginx usa como padrão um corpo de requisição de 1 MB. Quando o arquivo ultrapassa esse limite, a sincronização falha com 413 Request Entity Too Large no log de acesso do nginx, enquanto o aplicativo exibe apenas um erro genérico de sincronização. O servidor tem limites separados: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB usa 20 por padrão e ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB usa 50. Portanto, defina o limite do nginx acima do limite aplicável ao seu caso.

Recarregue e teste:

sudo nginx -t && sudo systemctl reload nginx
curl -fsS -o /dev/null -w '%{http_code}\n' https://budget.example.com/

Primeira execução: a senha e seu primeiro arquivo de orçamento

Abra https://budget.example.com em um navegador. A primeira tela solicita a definição de uma senha para o servidor. Essa senha protege o servidor inteiro, portanto gere uma senha longa e aleatória e guarde-a em um local que você consiga encontrar novamente, como um gerenciador de senhas Vaultwarden auto-hospedado. Não há contas de usuário para criar. O servidor do Actual usa uma única senha por padrão, portanto compartilhar um orçamento significa compartilhar essa senha.

Em seguida, crie um arquivo de orçamento. O Actual pergunta se você deseja ativar a criptografia de ponta a ponta. Responda sim. Assim, o servidor armazena somente o texto cifrado, que é a opção adequada para dados financeiros em uma máquina alugada. Há um custo real: a senha de criptografia nunca chega ao servidor. Se você perdê-la, o arquivo será perdido e não haverá uma opção de redefinição. Anote-a antes de avançar nessa tela.

Defina os saldos iniciais usando os valores atuais do seu banco, em vez de importar anos de histórico. O orçamento por envelopes começa com o dinheiro que você tem agora, portanto não ter um histórico não causa nenhum problema.

Importando transações

É aqui que a honestidade importa mais do que o entusiasmo, porque a importação é o principal motivo pelo qual as pessoas abandonam aplicativos de orçamento auto-hospedados.

A inserção manual é a opção básica e sempre funciona. Para um método de envelopes, ela é possivelmente o objetivo, pois digitar uma compra faz você prestar atenção nela.

A importação de arquivos processa a maior parte dos dados. O Actual lê CSV, QIF, OFX e QFX, e todos os bancos exportam pelo menos um desses formatos. Importe cada conta na tela da conta, mapeie as colunas uma vez, e o Actual memoriza esse layout para a conta.

Existe sincronização bancária automática, mas ela precisa de um serviço de terceiros porque o servidor não consegue se comunicar diretamente com os bancos. O Actual oferece suporte ao SimpleFIN Bridge para bancos da América do Norte, ao Enable Banking para a Europa, ao Akahu para a Nova Zelândia e ao Pluggy.ai para o Brasil. O GoCardless ainda é compatível, mas não aceita novas contas. Você se cadastra diretamente com o provedor, gera as credenciais e as adiciona ao servidor. Em julho de 2026, o SimpleFIN Bridge cobra 15 dólares americanos por ano para até 25 instituições. Os outros serviços têm preços diferentes.

Aceite dois limites antes de depender desse recurso. As credenciais da API ficam no servidor e não são protegidas por criptografia de ponta a ponta, porque o servidor precisa usá-las. Além disso, o Actual não faz consultas periódicas: a sincronização é iniciada por um botão, não por uma tarefa em segundo plano.

Backups, porque são apenas arquivos

Tudo o que é importante está em /opt/actual/data. Não há etapa de exportação nem dump de banco de dados para automatizar.

A única armadilha é o SQLite. Copiar account.sqlite enquanto o servidor está gravando nele pode capturar uma transação incompleta. Você só descobrirá isso ao tentar restaurar. Pare o container durante os poucos segundos necessários para a cópia:

cd /opt/actual
docker compose stop
restic -r sftp:backup@backup.example.com:/srv/restic backup /opt/actual/data
docker compose start

Agende isso usando a abordagem descrita em backups do restic em um VPS, que aborda a configuração do repositório, a retenção e o teste de restauração. Execute o teste de restauração. Um backup que nunca foi restaurado é apenas uma suposição.

Os backups no lado do cliente do próprio Actual são outra coisa e também são úteis. O navegador mantém cópias recentes do arquivo de orçamento, acessíveis pelo menu de arquivos. Isso resolve o caso de "excluí uma categoria por engano" sem tocar no servidor.

Atualizando o servidor

cd /opt/actual
docker compose pull
docker compose up --detach

O Compose recria o contêiner usando a nova imagem e reconecta o mesmo volume, portanto os dados são preservados. Atualize os clientes também. As versões do servidor e do aplicativo devem permanecer próximas, e um cliente muito mais antigo que o servidor pode recusar a sincronização e exibir uma mensagem de incompatibilidade de versão. Faça um backup antes de uma atualização para uma versão principal mais recente, porque as migrações são executadas na primeira inicialização e não há caminho de downgrade.

O que falha e o que você verá

O aplicativo carrega, mas a sincronização nunca termina. Verifique o log de acesso do nginx em busca de 413. Isso significa que client_max_body_size está definido com um valor muito baixo. Já 502 significa que o nginx está ativo e o container não está.

As opções de criptografia estão ausentes ou o aplicativo móvel recusa a URL. A página não está em um contexto seguro. A barra de endereço exibirá http:// com um endereço IP ou um nome de host que não é localhost. Corrija o certificado em vez de contornar o problema.

É exibida uma mensagem informando que o arquivo de orçamento não é compatível com esta versão. As versões do cliente e do servidor estão diferentes. Atualize ambos para a mesma versão e recarregue.

O container reinicia continuamente. Leia docker compose logs actual. Um erro de permissão em /data significa que o diretório montado não pode ser gravado pelo usuário do container. Um erro de endereço em uso significa que outro processo já está usando 5006 no loopback.

O primeiro carregamento parece lento. O arquivo de orçamento inteiro é baixado para o navegador quando você o abre. Primeiro ocorre uma grande transferência; depois, as leituras são locais. Isso não é um problema de dimensionamento do servidor, e adicionar RAM não mudará o comportamento.

FAQ

O Actual Budget precisa de HTTPS para funcionar?

Sim, na prática. A criptografia de ponta a ponta do Actual usa a Web Crypto API do navegador, e os navegadores só disponibilizam essa API em um contexto seguro, ou seja, https:// ou http://localhost. Por HTTP simples a partir de outra máquina, esses recursos ficam indisponíveis, e os aplicativos móveis oficiais recusam uma URL de servidor HTTP simples. Use um certificado Let's Encrypt em um nome de host real ou um certificado autoassinado com ACTUAL_HTTPS_KEY e ACTUAL_HTTPS_CERT se você usar apenas um navegador em um computador desktop.

O Actual pode importar automaticamente as transações do meu banco?

Somente por meio de um serviço de terceiros que você mesmo deve contratar: SimpleFIN Bridge na América do Norte, Enable Banking na Europa, Akahu na Nova Zelândia ou Pluggy.ai no Brasil. O GoCardless é compatível, mas não está aceitando novas contas. Essas credenciais de API ficam no seu servidor e não são protegidas pela criptografia de ponta a ponta. A sincronização também é manual: você pressiona um botão, e nada consulta o serviço em segundo plano. A importação de CSV, QIF, OFX e QFX não precisa de terceiros.

O que exatamente preciso incluir no backup?

O diretório de dados montado, que é /opt/actual/data neste guia. Ele contém server-files/account.sqlite, com logins e sessões, e user-files, com os arquivos de orçamento. Pare o contêiner antes de copiar, porque copiar um banco de dados SQLite em uso pode capturar uma gravação parcial. Nenhum outro arquivo no servidor contém estado.

O que acontece se eu perder a senha de criptografia?

O arquivo não poderá ser recuperado. A senha nunca chega ao servidor, que é justamente o objetivo da criptografia de ponta a ponta. Portanto, não há redefinição nem suporte para recuperação. Armazene a senha em um gerenciador de senhas assim que criar o arquivo e mantenha uma cópia em um local que não dependa desse mesmo servidor.

De quantos recursos de servidor o Actual Budget precisa?

Muito poucos. O contêiner fornece arquivos estáticos e arquivos de dados, e os cálculos do orçamento ocorrem no navegador. Um vCPU compartilhado com 1 GB de RAM executa o serviço sem problemas, e o diretório de dados de um orçamento doméstico com vários anos de histórico permanece na faixa de dezenas de megabytes. O consumo de disco vem dos seus backups e dos outros contêineres, não do Actual.