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 isto não é uma formalidade. Os navegadores só disponibilizam a Web Crypto API, a interface que o Actual usa para a encriptação de ponta a ponta, no que a especificação chama de contexto seguro. Um contexto seguro é https:// ou http://localhost. Se carregar a aplicação a partir de http://203.0.113.10:5006 num navegador de outra máquina, essas funcionalidades simplesmente não estarão disponíveis, porque o navegador nunca as disponibilizou para a página. As versões móveis oficiais também recusam um URL de servidor http:// simples.

Existem, portanto, duas configurações funcionais. Coloque um certificado válido num nome real à frente do contentor, que é o que este guia faz. Ou atribua 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 demora cinco minutos a obter, por isso escolha a primeira opção.

Instalar o Actual Budget com Docker Compose

Instale primeiro o Docker se o servidor for novo. Se a sintaxe do ficheiro Compose for nova para si, o guia princípios 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, server-files contém account.sqlite, com os seus tokens de início de sessão e de sessão, e user-files contém os próprios ficheiros do orçamento. Monte esse caminho; caso contrário, 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 em todas as interfaces, e o Docker escreve as suas próprias regras antes das regras do ufw. Assim, a aplicação ficaria exposta à Internet mesmo com uma firewall que negasse todo o tráfego. Essa situação é explicada em por que motivo as portas publicadas pelo Docker ignoram o ufw. A associação ao loopback significa que apenas o reverse proxy no mesmo servidor pode aceder à aplicação.

Inicie-a:

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

O log estabiliza quando o servidor indicar que está a escutar 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 a aplicação está a responder. curl: (7) Failed to connect significa que o contentor não está em execução, e docker compose ps mostra que terminou. 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 na frente

Aponte um registo A para o VPS, budget.example.com, e aguarde até que a resolução funcione. Depois, 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. O ficheiro de orçamento é carregado por inteiro durante uma sincronização completa. O nginx usa, por predefinição, um corpo de pedido de 1 MB. Quando o ficheiro ultrapassa esse limite, a sincronização falha com 413 Request Entity Too Large no log de acesso do nginx, enquanto a aplicação apresenta apenas um erro genérico de sincronização. O servidor tem limites próprios separados: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB usa 20 por predefinição e ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB usa 50. Por isso, 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 seu 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 consiga encontrar novamente, como num gestor de palavras-passe Vaultwarden autoalojado. Não existem contas de utilizador para criar. O servidor do Actual foi concebido para usar uma única palavra-passe, por isso partilhar um orçamento significa partilhar essa palavra-passe.

Em seguida, crie um ficheiro de orçamento. O Actual pergunta se pretende ativar a encriptação ponto a ponto. Responda que sim. O servidor armazenará apenas texto cifrado, que é a opção correta para dados financeiros numa máquina alugada. O custo é real: a palavra-passe de encriptação nunca chega ao servidor. Se a perder, o ficheiro fica perdido e não existe 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 parte do dinheiro que tem agora e avança a partir daí, por isso um histórico vazio não lhe causa qualquer prejuízo.

Importar transações

Aqui, a honestidade é mais importante do que o entusiasmo, porque a importação é o principal motivo pelo qual as pessoas abandonam as aplicações de orçamentação autoalojadas.

O lançamento manual é a base e funciona sempre. Num método de envelopes, é discutivelmente o objetivo, porque escrever uma compra é o que faz com que repare nela.

A importação de ficheiros trata da maior parte do trabalho. O Actual lê CSV, QIF, OFX e QFX, e todos os bancos exportam pelo menos um desses formatos. Importe cada conta a partir do ecrã da conta, associe as colunas uma vez e o Actual memoriza esse esquema para a conta.

A sincronização bancária automática existe, mas precisa de um serviço de terceiros porque o servidor não consegue comunicar diretamente com os bancos. O Actual suporta o SimpleFIN Bridge para bancos da América do Norte, o Enable Banking para a Europa, o Akahu para a Nova Zelândia e o Pluggy.ai para o Brasil. O GoCardless continua a ser suportado, mas não aceita contas novas. Tem de criar a conta diretamente no fornecedor, gerar as credenciais e adicioná-las ao servidor. Em julho de 2026, o SimpleFIN Bridge cobra 15 US dollars por ano por até 25 instituições, e os outros serviços têm preços diferentes.

Aceite estes dois limites antes de depender desta funcionalidade. As credenciais da API ficam no servidor e não são protegidas por encriptação de ponta a ponta, porque o servidor tem de as utilizar. Além disso, o Actual não faz sondagem periódica: a sincronização é um botão que se prime, não uma tarefa em segundo plano.

Backups, porque são apenas ficheiros

Tudo o que é importante está em /opt/actual/data. Não existe uma etapa de exportação nem um dump da base de dados para automatizar.

A única armadilha é o SQLite. Copiar account.sqlite enquanto o servidor está a escrever nele pode capturar uma transação incompleta. Só descobrirá isso quando tentar restaurar. Pare o contentor 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 seguindo a abordagem de backups restic num VPS, que explica 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 do lado do cliente do Actual são uma funcionalidade separada e também são importantes. O navegador mantém cópias recentes do ficheiro de orçamento, acessíveis através do menu de ficheiros. Isso resolve o caso de apagar uma categoria por engano sem tocar no servidor.

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. As versões do servidor e da aplicação devem manter-se próximas. Um cliente muito mais antigo do que o servidor pode recusar a sincronização e apresentar uma mensagem de incompatibilidade de versões. Faça uma cópia de segurança antes de avançar para uma versão principal diferente, porque as migrações são executadas no primeiro arranque e não existe um caminho de downgrade. O Actual tolera uma tag latest flutuante porque o seu estado é um diretório de ficheiros. Uma aplicação que utilize uma base de dados real não oferece a mesma margem. O guia para alojar o Chatwoot descreve as tags fixas e o dump anterior à atualização que este 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 indica, em vez disso, que o nginx está ativo e que o contentor não está.

As opções de encriptação não aparecem ou a aplicação móvel recusa o URL. A página não está num contexto seguro. A barra de endereços mostrará http:// com um endereço IP ou um nome de anfitrião 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. As versões do cliente e do servidor divergiram. Atualize ambos para a mesma release e recarregue.

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 uso significa que outro processo já está a usar 5006 no loopback.

O primeiro carregamento parece lento. O ficheiro de orçamento completo é transferido para o browser quando o abre. Isso é uma transferência única de grande dimensão, seguida de leituras locais. Não é um problema de dimensionamento do servidor, e adicionar RAM não altera esse comportamento.

FAQ

O Actual Budget precisa de HTTPS para funcionar?

Sim, na prática. A encriptação de ponta a ponta do Actual usa a Web Crypto API do browser, que só é disponibilizada num contexto seguro, ou seja, https:// ou http://localhost. Através de HTTP simples a partir de outra máquina, essas funcionalidades não estão disponíveis, e as aplicações móveis oficiais recusam um URL de servidor HTTP simples. Use um certificado Let's Encrypt num hostname real, ou um certificado autoassinado com ACTUAL_HTTPS_KEY e ACTUAL_HTTPS_CERT se utilizar exclusivamente um browser de desktop.

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

Apenas através de um serviço de terceiros no qual se registe diretamente: SimpleFIN Bridge na América do Norte, Enable Banking na Europa, Akahu na Nova Zelândia ou Pluggy.ai no Brasil. O GoCardless é suportado, mas não está a aceitar novas contas. Essas credenciais de API ficam no seu servidor e não são abrangidas pela encriptação de ponta a ponta. A sincronização também é manual: tem de premir um botão e não existe nenhuma consulta em segundo plano. A importação de CSV, QIF, OFX e QFX não requer qualquer serviço de terceiros.

O que tenho exatamente de incluir nas cópias de segurança?

O diretório de dados montado, que neste guia é /opt/actual/data. Contém server-files/account.sqlite, com logins e sessões, e user-files, com os ficheiros dos orçamentos. Pare o container antes de copiar, porque copiar uma base de dados SQLite em utilização pode capturar uma escrita incompleta. Não existe mais nenhum estado guardado no servidor.

O que acontece se eu perder a palavra-passe de encriptação?

O ficheiro não pode ser recuperado. A palavra-passe nunca chega ao servidor, que é precisamente o objetivo da encriptação de ponta a ponta, por isso não existe reposição nem suporte que possa recuperar o acesso. Guarde-a num gestor de palavras-passe assim que criar o ficheiro e mantenha uma cópia num local que não dependa deste mesmo servidor.

De que recursos de servidor precisa o Actual Budget?

De muito poucos. O container serve ficheiros e recursos estáticos, e os cálculos do orçamento são executados no browser. Um vCPU partilhado com 1 GB de RAM executa-o sem problemas, e o diretório de dados de um orçamento doméstico com vários anos de histórico mantém-se na ordem das dezenas de megabytes. O consumo de disco vem das suas cópias de segurança e dos outros containers, não do Actual. Se estiver a dimensionar uma máquina que também tenha de executar algo mais exigente, um servidor de fotografias é normalmente o que define o requisito mínimo; por isso, consulte quanta RAM o PhotoPrism e o Immich realmente precisam antes de escolher um plano. A mesma lógica aplica-se a uma stack multimédia: a transcodificação é que determina o plano, enquanto um frontend de browser como o Halcyon, que transforma uma biblioteca Jellyfin numa videolocadora navegável dos anos 90 custa aproximadamente o mesmo que o Actual.