Hospedar Firefly III em um VPS gerenciado: suas finanças em seu servidor

O que o Firefly III faz

O Firefly III é um gerenciador de finanças pessoais concebido para a auto-hospedagem. Ele acompanha suas despesas e receitas, com orçamentos, categorias e tags, para você ver para onde vai seu dinheiro. O README dele o descreve como totalmente auto-hospedado e isolado: ele não contata nenhum servidor externo até que você o peça explicitamente.

• A contabilidade: partidas dobradas, contas de ativo, passivos e todas as moedas que você quiser.
• A automação: transações recorrentes e regras que você escreve para classificar cada transação.
• O acompanhamento: orçamentos, cofrinhos para poupar rumo a um objetivo, relatórios de receitas e despesas, gráficos.
• A segurança: autenticação em duas etapas para cada conta.
• A abertura: uma API REST em JSON que cobre quase toda a aplicação, além de webhooks.

Uma instância recebe quantos usuários você quiser, cada um com uma administração financeira totalmente separada das outras. A documentação descreve um modelo para compartilhar uma mesma administração, atualmente em desenvolvimento.

O que a licença AGPL permite

O Firefly III é publicado sob a GNU Affero General Public License, versão 3 ou, a seu critério, qualquer versão posterior: é o identificador SPDX AGPL-3.0-or-later do arquivo composer.json dele. O texto afirma uma permissão irrestrita de rodar o programa não modificado. Você pode, portanto, usar a imagem publicada pelo projeto para você, sua família ou sua empresa, sem licença a comprar.

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

A instalação com Docker Compose

A documentação apresenta o Docker Compose como a maneira mais simples de instalar o Firefly III. Em um servidor com o Docker instalado, crie uma pasta e baixe nela os três arquivos oficiais, em formato bruto: o espaçamento deles importa, e a documentação pede para não copiá-los 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, um banco MariaDB, e cron, a tarefa agendada.
• .env reúne as configurações do Firefly III, entre elas a chave de criptografia e o acesso ao banco.
• .db.env reúne as configurações do banco. Mantenha os dois nomes: o arquivo Compose se refere a eles por env_file.

As configurações a mudar antes da primeira inicialização

Gere duas cadeias de 32 caracteres com o comando indicado no arquivo .env: uma para a chave, outra para a senha do banco.

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 criptografa suas sessões. Ela tem exatamente 32 caracteres, sem caracteres especiais como =, #, < ou >, e o arquivo pede para guardá-la em grande segurança.
• DB_PASSWORD no .env e MYSQL_PASSWORD no .db.env recebem o mesmo valor.
• SITE_OWNER: seu endereço, exibido em alguns erros aos usuários que não são administradores.
• APP_URL: o endereço público de sua instância. O arquivo explica que ele serve para validar certas requisições e para montar os links dos e-mails.
• TZ: seu fuso horário, no formato da base tz, como mostra o exemplo do arquivo.

Escolha a senha do banco antes da primeira inicialização. O banco a grava no volume dele assim que é criado: mude-a depois e ela deixa de corresponder, e o FAQ Docker oferece uma única saída, remover os contêineres e os volumes e recomeçar.

Uma porta publicada localmente

O arquivo oficial publica a aplicação na porta 80 de todos os endereços do servidor. Para servi-la em HTTPS atrás de um proxy reverso na mesma máquina, mude apenas esta 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

Na primeira inicialização, o contêiner cria e migra o banco sozinho. Quando a instalação termina, o Firefly III agradece no log por tê-lo instalado: passe ao proxy reverso.

• A tag latest acompanha a última versão estável. Uma tag como version-6.7.9 fixa uma versão; o projeto remove as antigas após cerca de seis meses.
• As arquiteturas: as imagens são geradas para linux/amd64 e linux/arm64.
• Os volumes: firefly_iii_upload guarda os anexos, firefly_iii_db o banco.

A documentação não informa números de memória; o FAQ Docker dela sugere PHP_MEMORY_LIMIT=512M ou mais se o PHP ficar sem memória. O tamanho depende do número de usuários, do volume de transações e do importador de dados. Em um VPS gerenciado, descreva-nos o uso e recomendamos o tamanho adequado.

HTTPS e o proxy reverso

O Firefly III serve a aplicação em HTTP na porta 8080 dentro do contêiner, e o HTTPS fica no proxy reverso colocado na 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=*

O FAQ Docker é claro nesse ponto: sem TRUSTED_PROXIES=*, os links continuam 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 alcança a aplicação. Recrie o contêiner após cada mudança no arquivo .env:

docker compose up -d --force-recreate app

Com o Caddy

O Caddy obtém sozinho o certificado Let's Encrypt, e a diretiva reverse_proxy dele define por padrã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 do FAQ de instalação e os buffers que ele sugere contra os erros 502, quando a aplicação devolve um token em um cabeçalho longo. Ele 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;
    }
}

Em seguida, o Certbot instala o certificado e cuida de renová-lo:

sudo certbot --nginx

• Um nome de domínio próprio: sirva o Firefly III em um nome só dele, como finances.example.com. O FAQ observa que o Laravel não interpreta um endereço IPv6 bruto na URL.
• Os erros 431: o FAQ os atribui a um limite de tamanho de cabeçalho pequeno demais no proxy, o que faz falhar algumas ações, como o login.

A primeira conta e os cadastros

O primeiro usuário cadastrado se torna o proprietário da instância. Por segurança, os cadastros se fecham então sozinhos: a maioria das pessoas instala o Firefly III só para si.

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

• A autenticação em duas etapas depende do relógio: o FAQ indica que uma diferença de horário entre o celular e o servidor a faz falhar.
• O login por seu provedor de identidade: com AUTHENTICATION_GUARD=remote_user_guard, o Firefly III confia em um proxy de autenticação colocado na frente, como o Authelia ou o Authentik, que repassa o usuário em um cabeçalho.
• Os tokens de acesso: os clientes OAuth e os tokens de API pessoais são criados a partir do perfil.

A tarefa cron

Vários recursos só funcionam com uma tarefa agendada: os orçamentos automáticos, as transações recorrentes, os avisos de assinatura e as taxas de câmbio atualizadas. A imagem Docker não executa o cron sozinha; o arquivo oficial acrescenta para isso um pequeno serviço cron, que chama a aplicação todos os dias às 3 horas.

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

STATIC_CRON_TOKEN=

Esse token tem exatamente 32 caracteres: o código da versão 6.7.9 não aceita outro comprimento. Veja o serviço como o arquivo oficial o declara; o $$ duplo é proposital e remete às linhas TZ e STATIC_CRON_TOKEN do arquivo .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 usuários da instância. Para verificar se ela rodou, leia o log do contêiner: cada tarefa presta contas em JSON, com job_fired e job_succeeded.

docker logs firefly_iii_cron

Para executá-la à mão, o FAQ Docker pede para passar pelo usuário www-data em vez de root: o FAQ liga essa armadilha a erros de permissão nos arquivos de log:

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 arquivo oficial traz o MariaDB, com a imagem mariadb:lts. O Firefly III também suporta o PostgreSQL e o SQLite, escolhidos por DB_CONNECTION no .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

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

Faça essa escolha antes de lançar suas primeiras transações. O FAQ indica que passar de um banco a outro continua 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 instalação e atualizações próprias; a versão 2.3.5 dele saiu em 23 de setembro de 2026. Ele importa arquivos CSV e CAMT.053 e também sabe buscar as transações de seus bancos por meio de provedores de dados terceiros, cada um com as próprias condições.

O repositório Docker oficial o fornece em um segundo arquivo, docker-compose-importer.yml, que retoma os mesmos serviços e acrescenta importer. As configurações dele vão em um arquivo .importer.env, tirado do .env.example do importador. Sirva-o em um nome de domínio próprio, com uma porta publicada localmente e um segundo bloco de proxy: o FAQ pede para não colocá-lo em um subdiretório.

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

• FIREFLY_III_URL: o endereço interno da aplicação, que o importador alcança pela rede Docker.
• VANITY_URL: o endereço público do Firefly III, aquele que seus usuários conhecem.
• O cliente OAuth: em seu perfil do Firefly III, crie um cliente cuja URL de retorno seja o endereço do importador seguido de /callback e desmarque “Confidential”. O importador pede então o ID desse cliente.
• Vários usuários: deixe FIREFLY_III_ACCESS_TOKEN vazio e mantenha FIREFLY_III_URL; cada usuário se conecta então ao importador com a própria conta.

Os e-mails: a configuração SMTP

Por padrão, MAIL_MAILER=log grava as mensagens nos logs em vez de enviá-las. Para receber as notificações, como os avisos de assinatura, configure o envio no .env. A documentação pede para sempre mudar MAIL_FROM e SITE_OWNER, sem o que nenhum e-mail jamais sairá.

Em um VPS Simafri, o envio passa por um relay SMTP autenticado, na porta 587: o endereço de uma conta de e-mail que você já tem, 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, conforme seu provedor; 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 que o contêiner é recriado.
• Outros canais: as notificações também podem ir para o Slack, e para o Discord ou o Mattermost pela URL de webhook deles seguida de /slack.

Os backups

O Firefly III não tem rotina de backup integrada: a documentação recomenda as ferramentas do sistema e esclarece que a função de exportação da aplicação não é um backup. Com o Docker, veja o que guardar:

O banco, com o serviço em funcionamento

Com o MariaDB, mariadb-dump exporta o banco sem parar o serviço; a opção --single-transaction dele dá uma cópia coerente das tabelas InnoDB sem bloqueá-las. Executado a partir da pasta do arquivo Compose, o comando lê os acessos no ambiente do contêiner:

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, a mesma ideia passa por pg_dump:

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

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

Os volumes, com o serviço parado

A documentação arquiva cada volume com um contêiner descartável. O Docker Compose prefixa os nomes dos volumes com o nome do projeto, que por padrão é o nome da pasta: confira os nomes exatos antes de executar o arquivamento.

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 digitado errado não gera nenhum erro: o Docker cria um volume vazio com esse nome e o arquiva, o que sobrescreve o backup anterior. A documentação pede para verificar se o volume existe antes de cada arquivamento.

Guarde uma cópia do .env e desses arquivos fora do servidor, criptografada, pois ela leva a chave e os acessos ao banco. Colocados no disco do servidor, esses arquivos também entram nos backups noturnos dele.

Restaurar

A documentação restaura um volume com o comando inverso, com o serviço parado; o volume de anexos é restaurado 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 é recarregada no banco 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 APP_KEY dele, depois reinicie e abra suas contas. A documentação repete isso após cada método: a primeira coisa a fazer com um backup é restaurá-lo, para verificar se ele funciona.

As atualizações e as migrações

O Firefly III se atualiza sozinho, mesmo a partir de versões tão antigas quanto a 4.7, e migra o banco quando o contêiner inicia. A documentação avisa que algumas atualizações removem ou limpam dados e pede um backup do banco e dos volumes antes de cada uma, sobretudo entre versões principais. A partir da pasta do arquivo 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, dez versões saíram em quatro semanas. Acompanhe as notas de versão: desde a 6.7.8, uma janela na aplicação resume as principais mudanças da versão instalada.
• A versão 6.7.0 trouxe uma nova interface; o motor de expressões das regras vem desativado por padrão e é reativado em /settings.
• O arquivo Compose: se você o baixar de novo, confira a versão do banco que ele declara. A documentação avisa que uma nova versão principal do MariaDB pode não aproveitar o volume da anterior.
• Uma migração que não passou: desde a 6.4.19, php artisan correction:rollback-single-migration remove o último registro de migração sem tocar nos dados, e depois php artisan migrate a executa de novo, dentro do contêiner.
• As versões assinadas: o projeto assina as versões que publica, o que você verifica com a chave PGP dele.

O importador se atualiza da mesma forma, com docker compose rm -f entre a parada e o download das imagens, segundo a documentação dele.

Quem faz o quê em um VPS gerenciado

A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o Firefly III continua sendo seu software, com as configurações dele e seus dados financeiros.

Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.