Alojar Firefly III num VPS gerido: as suas finanças no seu servidor

O que faz o Firefly III

O Firefly III é um gestor de finanças pessoais concebido para o autoalojamento. Acompanha as suas despesas e as suas receitas, com orçamentos, categorias e etiquetas, para que veja para onde vai o seu dinheiro. O seu README descreve-o como totalmente autoalojado e isolado: não contacta nenhum servidor externo enquanto não lho pedir expressamente.

• A contabilidade: contabilidade em partidas dobradas, contas de ativos, passivos e todas as moedas que quiser.
• A automatização: transações recorrentes e regras escritas por si para classificar cada transação.
• O acompanhamento: orçamentos, mealheiros para poupar com vista a um objetivo, relatórios de receitas e despesas, gráficos.
• A segurança: autenticação de dois fatores para cada conta.
• A abertura: uma API REST JSON que cobre quase toda a aplicação, além de webhooks.

Uma instância acolhe tantos utilizadores quantos quiser, cada um com uma administração financeira totalmente separada das outras. A documentação descreve um modelo de partilha de uma mesma administração, atualmente em desenvolvimento.

O que permite a licença AGPL

O Firefly III é publicado sob a GNU Affero General Public License, versão 3 ou, à sua escolha, qualquer versão posterior: é o identificador SPDX AGPL-3.0-or-later do seu ficheiro composer.json. O texto afirma uma permissão ilimitada de fazer correr o programa não modificado. Pode, portanto, utilizar a imagem publicada pelo projeto para si, para a sua família ou para a sua empresa, sem licença para comprar.

O artigo 13 acrescenta uma condição própria da AGPL: se modificar o programa, a sua versão tem de oferecer a todos os que a utilizam à distância, pela rede, o meio de obter gratuitamente o seu código-fonte. O importador de dados está sob a mesma licença.

A instalação com o Docker Compose

A documentação apresenta o Docker Compose como a forma mais simples de instalar o Firefly III. Num servidor com o Docker instalado, crie uma pasta e transfira para ela os três ficheiros oficiais, em bruto: os espaços contam, e a documentação pede que não os copie a partir do navegador.

mkdir firefly-iii && cd firefly-iii
curl -o docker-compose.yml https://raw.githubusercontent.com/firefly-iii/docker/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example
curl -o .db.env https://raw.githubusercontent.com/firefly-iii/docker/main/database.env

• docker-compose.yml descreve três serviços: app, a aplicação, db, uma base de dados MariaDB, e cron, a tarefa agendada.
• .env contém as definições do Firefly III, entre as quais a chave de cifragem e os acessos à base de dados.
• .db.env contém as definições da base de dados. Mantenha os dois nomes: o ficheiro Compose refere-se a eles através de env_file.

As definições a mudar antes do primeiro arranque

Gere duas cadeias de 32 caracteres com o comando indicado no ficheiro .env: uma para a chave, outra para a palavra-passe da base de dados.

head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo

SITE_OWNER=you@example.com
APP_KEY=
DB_PASSWORD=
APP_URL=https://finances.example.com

MYSQL_PASSWORD=

• APP_KEY cifra as suas sessões. Tem exatamente 32 caracteres, sem caracteres especiais como =, #, < ou >, e o ficheiro pede que a guarde em total segurança.
• DB_PASSWORD no .env e MYSQL_PASSWORD no .db.env recebem o mesmo valor.
• SITE_OWNER: o seu endereço, apresentado em certos erros aos utilizadores que não são administradores.
• APP_URL: o endereço público da sua instância. O ficheiro explica que serve para validar certos pedidos e para construir as ligações dos e-mails.
• TZ: o seu fuso horário, no formato da base de dados tz, como mostra o exemplo do ficheiro.

Escolha a palavra-passe da base de dados antes do primeiro arranque. A base de dados guarda-a no seu volume logo que é criada: se a mudar depois, deixa de corresponder, e a FAQ Docker só indica uma saída, eliminar os contentores e os volumes e recomeçar.

Uma porta publicada em local

O ficheiro oficial publica a aplicação na porta 80 de todos os endereços do servidor. Para a servir em HTTPS atrás de um proxy inverso na mesma máquina, mude esta única linha no serviço app:

ports:
  - 127.0.0.1:8080:8080

docker compose -f docker-compose.yml up -d --pull=always
docker compose -f docker-compose.yml logs -f

No primeiro arranque, o contentor cria e migra a base de dados por si próprio. Quando a instalação termina, o Firefly III agradece-lhe no registo por o ter instalado: passe ao proxy inverso.

• A etiqueta latest acompanha a última versão estável. Uma etiqueta como version-6.7.9 fixa uma versão; o projeto retira as antigas ao fim de cerca de seis meses.
• As arquiteturas: as imagens são construídas para linux/amd64 e linux/arm64.
• Os volumes: firefly_iii_upload guarda os anexos, firefly_iii_db a base de dados.

A documentação não indica nenhum valor de memória; a sua FAQ Docker sugere PHP_MEMORY_LIMIT=512M ou mais se o PHP ficar sem memória. O tamanho depende do número de utilizadores, do volume de transações e do importador de dados. Num VPS gerido, descreva-nos a sua utilização e recomendamos-lhe o tamanho adequado.

O HTTPS e o proxy inverso

O Firefly III serve a aplicação em HTTP na porta 8080 dentro do contentor, e o HTTPS fica a cargo do proxy inverso colocado à frente. A aplicação lê o cabeçalho X-Forwarded-Proto para saber que o visitante chegou em HTTPS, desde que confie no proxy:

TRUSTED_PROXIES=*

A FAQ Docker é clara neste ponto: sem TRUSTED_PROXIES=*, as ligações ficam em http, os formulários e os gráficos deixam de funcionar e os cabeçalhos de segurança CSP falham. Com a porta publicada em 127.0.0.1, só o proxy do próprio servidor chega à aplicação. Recrie o contentor depois de cada alteração ao ficheiro .env:

docker compose up -d --force-recreate app

Com o Caddy

O Caddy obtém por si próprio o certificado Let's Encrypt, e a sua diretiva reverse_proxy define por predefinição os cabeçalhos X-Forwarded-For, X-Forwarded-Proto e X-Forwarded-Host:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Com o Nginx e o Certbot

Este bloco retoma os cabeçalhos da FAQ de instalação, bem como os buffers que ela sugere contra os erros 502 quando a aplicação devolve um token num cabeçalho longo. Escuta na porta 80 para deixar o Certbot instalar o HTTPS:

server {
    listen 80;
    listen [::]:80;
    server_name finances.example.com;

    client_max_body_size 64M;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 300s;
    }
}

O Certbot instala depois o certificado e encarrega-se de o renovar:

sudo certbot --nginx

• Um nome de domínio próprio: sirva o Firefly III com o seu próprio nome, como finances.example.com. A FAQ assinala que o Laravel não interpreta um endereço IPv6 em bruto no URL.
• Os erros 431: a FAQ atribui-os a um limite de tamanho dos cabeçalhos demasiado baixo no proxy, que faz falhar certas ações, como o início de sessão.

A primeira conta e as inscrições

O primeiro utilizador a inscrever-se torna-se o proprietário da instância. Por segurança, as inscrições fecham-se então sozinhas: a maioria das pessoas instala o Firefly III só para si.

1. Abra o seu endereço HTTPS assim que o proxy responder e crie a sua conta: ela recebe a função de proprietário.
2. Ative a autenticação de dois fatores no seu perfil e guarde os oito códigos de recuperação que ela apresenta.
3. Para abrir a instância a outras pessoas, vá a /settings, abra as opções de configuração do Firefly III, desmarque a opção que desativa as inscrições e guarde.

• A autenticação de dois fatores depende da hora: a FAQ indica que uma diferença de hora entre o telemóvel e o servidor a faz falhar.
• O início de sessão pelo seu fornecedor de identidade: com AUTHENTICATION_GUARD=remote_user_guard, o Firefly III confia num proxy de autenticação colocado à frente, como o Authelia ou o Authentik, que lhe transmite o utilizador num cabeçalho.
• Os tokens de acesso: os clientes OAuth e os tokens de API pessoais criam-se a partir do perfil.

A tarefa cron

Várias funcionalidades só funcionam com uma tarefa agendada: os orçamentos automáticos, as transações recorrentes, os avisos de subscrição e as taxas de câmbio atualizadas. A imagem Docker não executa o cron por si própria; o ficheiro oficial acrescenta para isso um pequeno serviço cron, que chama a aplicação todos os dias às 3h00.

Autentica-se com um token estático. Gere uma terceira cadeia com o mesmo comando e coloque-a no .env:

STATIC_CRON_TOKEN=

Este token tem exatamente 32 caracteres: o código da versão 6.7.9 não aceita nenhum outro comprimento. Eis o serviço tal como o ficheiro oficial o declara; o $$ duplo é intencional e remete para as linhas TZ e STATIC_CRON_TOKEN do ficheiro .env:

cron:
  image: alpine
  restart: always
  container_name: firefly_iii_cron
  env_file: .env
  init: true
  command: ["sh", "-c", "apk add tzdata && \
    (ln -s /usr/share/zoneinfo/$$TZ /etc/localtime || true) && \
    echo \"0 3 * * * wget -qO- http://app:8080/api/v1/cron/$$STATIC_CRON_TOKEN;echo\" \
    | crontab - && \
    exec crond -f -L /dev/stdout"]
  networks:
    - firefly_iii
  depends_on:
    - app

Uma única tarefa basta para todos os utilizadores da instância. Para verificar que correu, leia o registo do contentor: cada tarefa dá conta do resultado em JSON, com job_fired e job_succeeded.

docker logs firefly_iii_cron

Para a executar manualmente, a FAQ Docker pede que passe pelo utilizador www-data e não por root: a FAQ associa esta armadilha a erros de permissões nos ficheiros de registo:

docker exec --user www-data firefly_iii_core /usr/local/bin/php /var/www/html/artisan firefly-iii:cron --force

MariaDB, PostgreSQL ou SQLite

O ficheiro oficial traz o MariaDB, com a imagem mariadb:lts. O Firefly III suporta também o PostgreSQL e o SQLite, escolhidos com DB_CONNECTION no .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

Para o PostgreSQL, a documentação aponta também o serviço db para a imagem postgres, que instala o PostgreSQL 18, e monta o seu volume em /var/lib/postgresql. No .db.env, as variáveis MYSQL_* passam a POSTGRES_USER, POSTGRES_DB e POSTGRES_PASSWORD.

Faça esta escolha antes de introduzir as suas primeiras transações. A FAQ indica que passar de uma base de dados para outra continua a ser possível, sem ser suportado pelo próprio Firefly III, e que a exportação da aplicação não leva todos os dados.

O importador de dados

O Firefly III Data Importer é uma ferramenta à parte, com a sua própria instalação e as suas próprias atualizações; a sua versão 2.3.5 saiu a 23 de setembro de 2026. Importa ficheiros CSV e CAMT.053, e pode também ir buscar as transações dos seus bancos através de fornecedores de dados terceiros, cada um com as suas próprias condições.

O repositório Docker oficial disponibiliza-o num segundo ficheiro, docker-compose-importer.yml, que mantém os mesmos serviços e acrescenta importer. As suas definições ficam num ficheiro .importer.env, tirado do .env.example do importador. Sirva-o com o seu próprio nome de domínio, com uma porta publicada em local e um segundo bloco de proxy: a FAQ pede que não o coloque numa subpasta.

FIREFLY_III_URL=http://app:8080
VANITY_URL=https://finances.example.com
TRUSTED_PROXIES=*

• FIREFLY_III_URL: o endereço interno da aplicação, a que o importador chega pela rede Docker.
• VANITY_URL: o endereço público do Firefly III, o que os seus utilizadores conhecem.
• O cliente OAuth: no seu perfil Firefly III, crie um cliente cujo URL de retorno seja o endereço do importador seguido de /callback, e desmarque «Confidential». O importador pede-lhe depois o identificador desse cliente.
• Vários utilizadores: deixe FIREFLY_III_ACCESS_TOKEN vazio e mantenha FIREFLY_III_URL; cada utilizador inicia então sessão no importador com a sua própria conta.

Os e-mails: a configuração SMTP

Por predefinição, MAIL_MAILER=log escreve as mensagens nos registos em vez de as enviar. Para receber as notificações, como os avisos de subscrição, configure o envio no .env. A documentação pede que mude sempre MAIL_FROM e SITE_OWNER, sem o que nenhum e-mail chega a partir.

Num VPS Simafri, o envio passa por uma retransmissão SMTP autenticada, na porta 587: o endereço de uma conta de correio que já tenha, ou o Simafri Suite.

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_FROM=finances@example.com
MAIL_USERNAME=finances@example.com
MAIL_PASSWORD=account_password
MAIL_ENCRYPTION=tls

• MAIL_ENCRYPTION aceita null, ssl, starttls ou tls, consoante o seu fornecedor; o código da versão 6.7.9 recorre a tls quando o valor está vazio.
• O teste: a página /settings/notifications envia um e-mail de teste, depois de o contentor ter sido recriado.
• Outros canais: as notificações podem também ir para o Slack, e para o Discord ou o Mattermost através do respetivo URL de webhook seguido de /slack.

As cópias de segurança

O Firefly III não tem uma rotina de cópia de segurança integrada: a documentação recomenda as ferramentas do próprio sistema e lembra que a função de exportação da aplicação não é uma cópia de segurança. Com o Docker, eis o que guardar:

A base de dados, com o serviço a funcionar

Com o MariaDB, o mariadb-dump exporta a base de dados sem parar o serviço; a sua opção --single-transaction dá uma cópia coerente das tabelas InnoDB sem as bloquear. Executado a partir da pasta do ficheiro Compose, o comando lê os acessos no ambiente do contentor:

docker exec firefly_iii_db sh -c 'mariadb-dump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > firefly-$(date +%F).sql

Com o PostgreSQL, o mesmo princípio passa pelo pg_dump:

docker exec firefly_iii_db sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > firefly-$(date +%F).sql

Agende esta exportação no servidor, pelo menos uma vez por dia, e faça a triagem dos ficheiros, que se acumulam.

Os volumes, com o serviço parado

A documentação arquiva cada volume com um contentor descartável. O Docker Compose prefixa os nomes dos volumes com o nome do projeto, que por predefinição é o nome da pasta: verifique os nomes exatos antes de lançar o arquivo.

docker volume ls
docker compose stop
docker run --rm -v "firefly-iii_firefly_iii_db:/tmp" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -czvf /backup/firefly_db.tar /tmp
docker run --rm -v "firefly-iii_firefly_iii_upload:/tmp" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -czvf /backup/firefly_upload.tar /tmp
docker compose start

Um nome de volume mal escrito não provoca nenhum erro: o Docker cria um volume vazio com esse nome e arquiva-o, o que substitui a cópia de segurança anterior. A documentação pede que verifique a existência do volume antes de cada arquivo.

Guarde uma cópia do .env e destes arquivos fora do servidor, cifrada, porque contém a chave e os acessos à base de dados. Colocados no disco do servidor, estes ficheiros entram também nas suas cópias de segurança noturnas.

Restaurar

A documentação restaura um volume com o comando inverso, com o serviço parado; o volume dos anexos restaura-se da mesma forma:

docker run --rm -v "firefly-iii_firefly_iii_db:/recover" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -xvf /backup/firefly_db.tar -C /recover --strip 1

Uma exportação SQL volta a carregar-se na base de dados em funcionamento:

docker exec -i firefly_iii_db sh -c 'mariadb -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < firefly-YYYY-MM-DD.sql

Restaure também o .env com a sua APP_KEY, reinicie e depois abra as suas contas. A documentação repete-o depois de cada método: a primeira coisa a fazer com uma cópia de segurança é restaurá-la, para verificar que funciona.

As atualizações e as migrações

O Firefly III atualiza-se por si próprio, mesmo a partir de versões tão antigas como a 4.7, e migra a sua base de dados no arranque do contentor. A documentação avisa que algumas atualizações eliminam ou limpam dados, e pede uma cópia de segurança da base de dados e dos volumes antes de cada uma, sobretudo entre versões principais. A partir da pasta do ficheiro Compose:

docker compose stop
docker compose pull
docker compose -f docker-compose.yml up -d --remove-orphans

• O ritmo: da 6.7.0, de 14 de setembro de 2026, à 6.7.9, de 11 de outubro de 2026, saíram dez versões em quatro semanas. Acompanhe as notas de versão: desde a 6.7.8, uma janela na aplicação resume as principais novidades da versão instalada.
• A versão 6.7.0 trouxe uma nova interface; o seu motor de expressões para as regras vem desativado por predefinição e volta a ativar-se em /settings.
• O ficheiro Compose: se o transferir de novo, verifique a versão da base de dados que ele declara. A documentação avisa que uma nova versão principal do MariaDB pode não retomar o volume da anterior.
• Uma migração que não passou: desde a 6.4.19, php artisan correction:rollback-single-migration retira a última entrada de migração sem tocar nos dados, e depois php artisan migrate executa-a de novo, dentro do contentor.
• As versões assinadas: o projeto assina as suas versões, que pode verificar com a sua chave PGP.

O importador atualiza-se da mesma forma, com docker compose rm -f entre a paragem e a transferência das imagens, segundo a sua documentação.

Quem faz o quê num VPS gerido

O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o Firefly III continua a ser o seu software, com as suas definições e os seus dados financeiros.

Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.