Como hospedar o Actual Budget no seu VPS

O que você vai criar

O Actual Budget é uma aplicação de gestão orçamental por envelopes, auto-hospedada, e é a resposta habitual quando alguém procura uma alternativa ao YNAB que possa alojar no seu próprio servidor. O servidor é composto por um contentor, um volume de dados e um nome HTTPS. Tudo o que um orçamento normal precisa funciona confortavelmente no VPS mais pequeno que possa alugar, porque o servidor armazena sobretudo ficheiros e sincroniza-os.

Vale a pena compreender a arquitetura antes de introduzir qualquer comando. O orçamento propriamente dito é uma base de dados SQLite que fica no navegador e em cada aplicação móvel. O servidor que vai instalar é um endpoint de sincronização: mantém a lista de contas, os ficheiros do orçamento e o registo de alterações que permite a um telemóvel e a um portátil manterem os dados alinhados. É por isso que a aplicação continua a funcionar quando o servidor está indisponível e que perder o servidor não implica perder o orçamento, desde que um cliente ainda tenha uma cópia.

Por que o servidor precisa de HTTPS

O Actual exige HTTPS, e isso não é uma formalidade. O Actual precisa de um recurso do navegador chamado SharedArrayBuffer para funcionar, e os navegadores só o habilitam quando a página está isolada entre origens em um contexto seguro, como definido pela especificação. Um contexto seguro é https:// ou http://localhost. Carregue o aplicativo a partir de http://203.0.113.10:5006 em um navegador de outra máquina, e o navegador nunca disponibilizará esse recurso para a página, portanto o orçamento não será carregado. Os telefones não são uma exceção. A FAQ do Actual informa que um aplicativo oficial para iOS está em testes beta e se conecta ao seu próprio servidor. Também informa que ainda não existe um aplicativo oficial para Android. Portanto, na maioria dos telefones, você usa o mesmo aplicativo web, instalado na tela inicial como um Progressive Web App, e a mesma regra de contexto seguro se aplica.

Há duas configurações viáveis. Coloque um certificado real em um nome real na frente do contêiner, 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 da Let's Encrypt leva cinco minutos para ser obtido, portanto escolha a primeira opção.

Instalar o Actual Budget com Docker Compose

Instale primeiro o Docker se o servidor for novo. Se a sintaxe dos ficheiros Compose for nova para si, 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

Há três detalhes importantes nesse ficheiro.

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 contentor grava tudo em /data. Dentro dele, encontra server-files, que contém account.sqlite com os seus tokens de início de sessão e de sessão, e user-files, que contém os próprios ficheiros do orçamento. Monte esse caminho ou o próximo docker compose pull elimina o seu orçamento. ACTUAL_DATA_DIR pode alterá-lo, mas o valor predefinido é adequado.

A porta é publicada apenas em 127.0.0.1. Um 5006:5006 sem endereço publica a porta em todas as interfaces, e o Docker escreve as suas próprias regras antes das regras do ufw. Assim, a aplicação ficaria acessível à Internet mesmo com uma firewall que negasse todo o tráfego. Essa situação é explicada em por que as portas publicadas pelo Docker ignoram o ufw. Associar a porta ao loopback significa que apenas o reverse proxy no mesmo servidor pode aceder a ela.

Inicie o serviço:

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

O log estabiliza quando o servidor indica que está a escutar na porta 5006. Verifique-o 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 a aplicação está a responder. curl: (7) Failed to connect significa que nenhum processo aceitou a ligação em 127.0.0.1:5006. Execute docker compose ps --all, porque um docker compose ps simples lista apenas os contentores em execução. Se o contentor aparecer como encerrado, a causa habitual é um problema de permissões no volume montado, visível como uma linha EACCES no log.

Coloque um certificado e um nome real à frente

Aponte um registo A para o VPS, budget.example.com, e aguarde até a resolução estar concluída. 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 muitas pessoas esquecem. A sincronização diária envia apenas as suas alterações, mas o ficheiro de orçamento completo é carregado quando regista um orçamento no servidor pela primeira vez e novamente sempre que repõe a sincronização. Por predefinição, o nginx limita o corpo dos pedidos a 1 MB. Quando o ficheiro ultrapassa esse tamanho, esses carregamentos completos falham com 413 Request Entity Too Large no log de acesso do nginx, enquanto a aplicação mostra apenas um erro genérico de sincronização. O servidor tem os seus próprios limites independentes: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB tem 20 como valor predefinido e ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB tem 50. Defina o limite do nginx acima do valor 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 palavra-passe e o primeiro ficheiro de orçamento

Abra https://budget.example.com num navegador. O primeiro ecrã pede-lhe que defina uma palavra-passe para o servidor. Essa palavra-passe protege todo o servidor, por isso gere uma palavra-passe longa e aleatória e guarde-a num local onde a possa encontrar novamente, como um gestor de palavras-passe Vaultwarden autoalojado. Por predefinição, não existem contas de utilizador para criar: o servidor tem uma única palavra-passe, por isso partilhar um orçamento significa partilhar essa palavra-passe. Inícios de sessão separados só são possíveis se ligar um fornecedor OpenID, que o Actual suporta em configurações com vários utilizadores.

Em seguida, crie um ficheiro de orçamento. O Actual pergunta se pretende ativar a encriptação ponta a ponta. Responda que sim. Nesse caso, o servidor armazena apenas texto cifrado, o que é a opção correta para dados financeiros numa máquina arrendada. O custo é real: a palavra-passe de encriptação nunca chega ao servidor. Se a perder, o ficheiro desaparece e não existe qualquer mecanismo de reposição. Anote-a antes de avançar nesse ecrã.

Defina os saldos iniciais com base nos valores atuais do seu banco, em vez de importar anos de histórico. O orçamento por envelopes funciona a partir do dinheiro que tem agora, por isso um histórico vazio não lhe custa nada.

Importação de transações

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

A inserção manual é a base e sempre funciona. Para um método de envelopes, ela é provavelmente o objetivo, porque digitar uma compra faz você prestar atenção nela.

A importação de arquivos processa a maior parte do volume. O Actual lê CSV, QIF, OFX, QFX e CAMT, e todos os bancos exportam pelo menos um desses formatos. Importe por conta na tela da conta e mapeie as colunas quando o arquivo estiver em CSV.

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

Há dois limites que você precisa aceitar 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, nada é sincronizado enquanto o Actual está fechado: a sincronização automática vem desativada por padrão e, depois de ativada, funciona somente enquanto o aplicativo está aberto. Portanto, o servidor nunca consulta os bancos por conta própria.

Backups, porque são apenas ficheiros

Tudo aquilo de que precisa está em /opt/actual/data. Não existe nenhum passo de exportação nem nenhum dump da base de dados para automatizar.

A única armadilha é o SQLite. Copiar account.sqlite enquanto o servidor está a escrever nele pode guardar uma transação incompleta, e só descobrirá isso quando tentar restaurar. Pare o contentor durante os poucos segundos necessários para efetuar 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 essa tarefa seguindo a abordagem em backups restic num VPS, que inclui 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 automáticos do próprio Actual são uma funcionalidade separada e convém conhecê-la, mas só existem na aplicação desktop. A aplicação mantém até 10 cópias recentes do ficheiro de orçamento, acessíveis em File > Load Backup, o que resolve o caso de “apaguei uma categoria por engano” sem tocar no servidor. A aplicação web no browser não mantém cópias desse tipo. Portanto, se toda a gente em casa usar o browser, o backup do servidor acima é o único que terá.

Atualizar o servidor

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

O Compose recria o contentor a partir da nova imagem e volta a associar o mesmo volume, por isso os dados são preservados. Atualize também os clientes. Um cliente mais antigo do que os dados que recebe deixa de aplicar alterações e apresenta a mensagem Update Required. Faça uma cópia de segurança antes de saltar para uma versão principal, porque as migrações são executadas no primeiro arranque e não existe um caminho de downgrade. O Actual tolera um pouco melhor uma tag latest flutuante porque o seu estado é um diretório de ficheiros. Uma aplicação que utiliza uma base de dados real não oferece essa margem. O guia para alojar o Chatwoot por conta própria explica as tags fixas e a exportação da base de dados antes da atualização que esse procedimento exige.

O que falha e o que verá

A aplicação carrega, mas a sincronização nunca termina. Verifique o log de acesso do nginx em 413. Isso significa que client_max_body_size está definido com um valor demasiado baixo. Um 502, por outro lado, significa que o nginx não recebeu uma resposta utilizável do upstream. Na maioria dos casos, isso acontece porque o contentor está parado ou não está a escutar na porta 5006. Por isso, verifique docker compose ps --all e o log do contentor antes de qualquer outra coisa.

A aplicação não carrega noutro dispositivo ou indica que SharedArrayBuffer está em falta. A página não está num contexto seguro. A barra de endereço mostrará http:// com um endereço IP ou um nome de host que não é localhost. Corrija o certificado em vez de contornar o problema.

É apresentada uma mensagem a indicar que o ficheiro de orçamento não é compatível com esta versão. O ficheiro foi aberto numa versão mais recente do Actual do que a versão do cliente que está a utilizar. Atualize o cliente para essa versão, no mínimo, ou restaure uma cópia de segurança criada antes de a versão mais recente ter alterado o ficheiro. Em seguida, carregue-o novamente.

O contentor reinicia continuamente. Leia docker compose logs actual. Um erro de permissões em /data significa que o diretório montado não pode ser escrito pelo utilizador do contentor. Um erro de endereço já em utilização significa que outro processo já está a utilizar a porta 5006 no loopback.

O primeiro carregamento parece lento. Todo o ficheiro de orçamento é transferido para o navegador quando o abre. Trata-se de uma única transferência grande, seguida de leituras locais. Não é um problema de dimensionamento do servidor, e adicionar RAM não irá alterar esse comportamento.

FAQ

O Actual Budget precisa de HTTPS para funcionar?

Sim, na prática. O Actual precisa do recurso SharedArrayBuffer do navegador para funcionar, e os navegadores só o ativam num contexto seguro, isto é, https:// ou http://localhost. Em HTTP simples, a partir de outra máquina, a aplicação não será carregada. Um aplicativo oficial para iOS está em testes beta e ainda não existe um aplicativo oficial para Android. Portanto, a maioria dos telefones usa a mesma aplicação web e está sujeita à mesma regra. (FAQ) Use um certificado Let's Encrypt num hostname real ou um certificado autoassinado com ACTUAL_HTTPS_KEY e ACTUAL_HTTPS_CERT, se aceitar o aviso de certificado em todos os dispositivos.

O Actual pode importar automaticamente as minhas transações bancárias?

Somente por meio de um serviço de terceiros no qual você mesmo se cadastra: 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 por criptografia de ponta a ponta. A sincronização automática vem desativada por padrão e, quando ativada, funciona somente enquanto o Actual está aberto. Portanto, nada consulta o serviço em segundo plano no servidor. A importação de CSV, QIF, OFX, QFX e CAMT não precisa de nenhum terceiro.

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 container antes de copiar, porque copiar um banco de dados SQLite em uso pode capturar uma gravação parcial. Nenhum outro componente do servidor manté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 existe redefinição nem suporte para recuperá-la. Armazene a senha num gerenciador de senhas assim que criar o arquivo e mantenha uma cópia num local que não dependa desse mesmo servidor.

De quantos recursos de servidor o Actual Budget precisa?

Muito poucos. O container serve arquivos estáticos e outros arquivos, e os cálculos do orçamento acontecem no navegador. Uma vCPU compartilhada 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 casa das dezenas de megabytes. O uso de disco vem dos seus backups e dos outros containers, não do Actual. Se você estiver dimensionando uma máquina que também precise executar algo mais exigente, um servidor de fotos normalmente define o mínimo. Consulte quanta RAM o PhotoPrism e o Immich realmente precisam antes de escolher um plano. A mesma lógica vale para uma stack de mídia: a transcodificação define o plano, enquanto uma interface web como o Halcyon, que transforma uma biblioteca do Jellyfin numa locadora de vídeos dos anos 90 que você pode percorrer custa aproximadamente tão pouco quanto o Actual.