Ospitare Firefly III su un VPS gestito: le vostre finanze sul vostro server

Che cosa fa Firefly III

Firefly III è un gestore di finanze personali pensato per il self-hosting. Tiene traccia delle vostre spese e delle vostre entrate, con budget, categorie ed etichette, per vedere dove vanno i vostri soldi. Il suo README lo descrive come interamente self-hosted e isolato: non contatta alcun server esterno finché non glielo chiedete esplicitamente.

• La contabilità: partita doppia, conti di attività, passività e tutte le valute che desiderate.
• L'automazione: transazioni ricorrenti, e regole scritte da voi per classificare ogni transazione.
• Il monitoraggio: budget, salvadanai per risparmiare in vista di un obiettivo, report su entrate e spese, grafici.
• La sicurezza: l'autenticazione a due fattori per ogni account.
• L'apertura: un'API REST JSON che copre quasi tutta l'applicazione, oltre ai webhook.

Un'istanza ospita tutti gli utenti che desiderate, ognuno con un'amministrazione finanziaria completamente separata da quella degli altri. La documentazione descrive un modello per condividere una stessa amministrazione, attualmente in fase di sviluppo.

Che cosa consente la licenza AGPL

Firefly III è pubblicato con la GNU Affero General Public License, versione 3 o, a vostra scelta, qualsiasi versione successiva: è l'identificatore SPDX AGPL-3.0-or-later del suo file composer.json. Il testo afferma un'autorizzazione illimitata a eseguire il programma non modificato. Potete quindi usare l'immagine pubblicata dal progetto per voi stessi, per la vostra famiglia o per la vostra azienda, senza alcuna licenza da acquistare.

L'articolo 13 aggiunge una condizione propria dell'AGPL: se modificate il programma, la vostra versione deve offrire a tutti coloro che la usano a distanza, tramite la rete, il modo di ottenerne gratuitamente il codice sorgente. Il Data Importer ha la stessa licenza.

L'installazione con Docker Compose

La documentazione indica Docker Compose come il modo più semplice di installare Firefly III. Su un server in cui Docker è installato, create una cartella e scaricatevi i tre file ufficiali, in formato grezzo: la loro spaziatura conta, e la documentazione chiede di non copiarli dal browser.

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 descrive tre servizi: app, l'applicazione, db, un database MariaDB, e cron, l'attività pianificata.
• .env contiene le impostazioni di Firefly III, tra cui la chiave di cifratura e l'accesso al database.
• .db.env contiene le impostazioni del database. Conservate entrambi i nomi: il file Compose li richiama tramite env_file.

Le impostazioni da cambiare prima del primo avvio

Generate due stringhe di 32 caratteri con il comando indicato nel file .env: una per la chiave, una per la password del database.

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 le vostre sessioni. È lunga esattamente 32 caratteri, senza caratteri speciali come =, #, < o >, e il file chiede di custodirla con la massima cura.
• DB_PASSWORD in .env e MYSQL_PASSWORD in .db.env prendono lo stesso valore.
• SITE_OWNER: il vostro indirizzo, mostrato in alcuni errori agli utenti che non sono amministratori.
• APP_URL: l'indirizzo pubblico della vostra istanza. Il file spiega che serve a convalidare alcune richieste e a costruire i link delle e-mail.
• TZ: il vostro fuso orario, nel formato del database tz, come mostra l'esempio del file.

Scegliete la password del database prima del primo avvio. Il database la registra nel suo volume fin dalla creazione: se la cambiate in seguito non corrisponde più, e la FAQ Docker offre una sola via d'uscita, cioè eliminare i container e i volumi e ricominciare da capo.

Una porta pubblicata in locale

Il file ufficiale pubblica l'applicazione sulla porta 80 di tutti gli indirizzi del server. Per servirla in HTTPS dietro un reverse proxy sulla stessa macchina, cambiate questa sola riga nel servizio 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

Al primo avvio, il container crea e migra da solo il database. A installazione terminata, Firefly III vi ringrazia nel log per averlo installato: passate al reverse proxy.

• Il tag latest segue l'ultima versione stabile. Un tag come version-6.7.9 fissa una versione; il progetto elimina quelle vecchie dopo circa sei mesi.
• Le architetture: le immagini sono compilate per linux/amd64 e linux/arm64.
• I volumi: firefly_iii_upload contiene gli allegati, firefly_iii_db il database.

La documentazione non indica alcun valore di memoria; la sua FAQ Docker suggerisce PHP_MEMORY_LIMIT=512M o più se PHP esaurisce la memoria. La taglia dipende dal numero di utenti, dal volume delle transazioni e dall'importatore di dati. Su un VPS gestito, descrivetici il vostro uso e vi raccomandiamo la taglia adatta.

HTTPS e il reverse proxy

Firefly III serve l'applicazione in HTTP sulla porta 8080 all'interno del container, e HTTPS spetta al reverse proxy posto davanti. L'applicazione legge l'intestazione X-Forwarded-Proto per sapere che il visitatore è arrivato in HTTPS, a condizione che si fidi del proxy:

TRUSTED_PROXIES=*

La FAQ Docker è chiara su questo punto: senza TRUSTED_PROXIES=*, i link restano in http, i moduli e i grafici smettono di funzionare e le intestazioni di sicurezza CSP falliscono. Con la porta pubblicata su 127.0.0.1, solo il proxy del server stesso raggiunge l'applicazione. Ricreate il container dopo ogni modifica del file .env:

docker compose up -d --force-recreate app

Con Caddy

Caddy ottiene da solo il certificato Let's Encrypt, e la sua direttiva reverse_proxy imposta per impostazione predefinita le intestazioni X-Forwarded-For, X-Forwarded-Proto e X-Forwarded-Host:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Con Nginx e Certbot

Questo blocco riprende le intestazioni della FAQ di installazione e i buffer che suggerisce contro gli errori 502, quando l'applicazione restituisce un token in un'intestazione lunga. Ascolta sulla porta 80 per lasciare a Certbot l'attivazione di 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;
    }
}

Certbot installa poi il certificato e si occupa di rinnovarlo:

sudo certbot --nginx

• Un nome di dominio dedicato: servite Firefly III con un nome tutto suo, come finances.example.com. La FAQ segnala che Laravel non interpreta un indirizzo IPv6 grezzo nell'URL.
• Gli errori 431: la FAQ li riconduce a un limite di dimensione delle intestazioni troppo basso sul proxy, che fa fallire alcune azioni, come l'accesso.

Il primo account e le registrazioni

Il primo utente che si registra diventa il proprietario dell'istanza. Per sicurezza, le registrazioni si chiudono poi da sole: la maggior parte delle persone installa Firefly III solo per sé.

1. Aprite il vostro indirizzo HTTPS non appena il proxy risponde, e create il vostro account: assume il ruolo di proprietario.
2. Attivate l'autenticazione a due fattori nel vostro profilo, e conservate gli otto codici di emergenza che mostra.
3. Per aprire l'istanza ad altre persone, andate su /settings, aprite le opzioni di configurazione di Firefly III, togliete la spunta all'opzione che disattiva le registrazioni e salvate.

• L'autenticazione a due fattori si basa sull'orologio: la FAQ indica che uno scarto di orario tra il telefono e il server la fa fallire.
• L'accesso tramite il vostro provider di identità: con AUTHENTICATION_GUARD=remote_user_guard, Firefly III si fida di un proxy di autenticazione posto davanti, come Authelia o Authentik, che trasmette l'utente in un'intestazione.
• I token di accesso: i client OAuth e i token API personali si creano dal profilo.

L'attività cron

Diverse funzioni funzionano solo con un'attività pianificata: i budget automatici, le transazioni ricorrenti, gli avvisi sugli abbonamenti e i tassi di cambio aggiornati. L'immagine Docker non esegue cron da sola; il file ufficiale aggiunge a questo scopo un piccolo servizio cron, che chiama l'applicazione ogni giorno alle 3 del mattino.

Si autentica con un token statico. Generate una terza stringa con lo stesso comando, e inseritela in .env:

STATIC_CRON_TOKEN=

Questo token è lungo esattamente 32 caratteri: il codice della versione 6.7.9 non accetta altre lunghezze. Ecco il servizio come lo dichiara il file ufficiale; il doppio $$ è voluto e rimanda alle righe TZ e STATIC_CRON_TOKEN del file .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

Un'unica attività basta per tutti gli utenti dell'istanza. Per verificare che sia stata eseguita, leggete il log del container: ogni attività rende conto in JSON, con job_fired e job_succeeded.

docker logs firefly_iii_cron

Per lanciarla a mano, la FAQ Docker chiede di passare dall'utente www-data anziché da root: la FAQ collega questa trappola a errori di permessi sui file di log:

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

MariaDB, PostgreSQL o SQLite

Il file ufficiale fornisce MariaDB, con l'immagine mariadb:lts. Firefly III supporta anche PostgreSQL e SQLite, da scegliere con DB_CONNECTION in .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

Per PostgreSQL, la documentazione fa anche puntare il servizio db all'immagine postgres, che installa PostgreSQL 18, e monta il suo volume su /var/lib/postgresql. In .db.env, le variabili MYSQL_* diventano POSTGRES_USER, POSTGRES_DB e POSTGRES_PASSWORD.

Fate questa scelta prima di inserire le prime transazioni. La FAQ indica che passare da un database all'altro resta possibile, senza essere supportato da Firefly III stesso, e che l'esportazione dell'applicazione non porta con sé tutti i dati.

Il Data Importer

Il Data Importer di Firefly III è uno strumento separato, con una propria installazione e propri aggiornamenti; la sua versione 2.3.5 è uscita il 23 settembre 2026. Importa file CSV e CAMT.053, e può anche recuperare le transazioni dalle vostre banche tramite fornitori di dati terzi, ognuno con le proprie condizioni.

Il repository Docker ufficiale lo fornisce in un secondo file, docker-compose-importer.yml, che mantiene gli stessi servizi e aggiunge importer. Le sue impostazioni vanno in un file .importer.env, ricavato dal .env.example dell'importatore. Servitelo con un nome di dominio dedicato, con una porta pubblicata in locale e un secondo blocco nel proxy: la FAQ chiede di non collocarlo in una sottocartella.

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

• FIREFLY_III_URL: l'indirizzo interno dell'applicazione, che l'importatore raggiunge tramite la rete Docker.
• VANITY_URL: l'indirizzo pubblico di Firefly III, quello che conoscono i vostri utenti.
• Il client OAuth: nel vostro profilo Firefly III, create un client il cui URL di callback è l'indirizzo dell'importatore seguito da /callback, e togliete la spunta a «Confidential». L'importatore chiede poi il suo ID client.
• Più utenti: lasciate vuoto FIREFLY_III_ACCESS_TOKEN e conservate FIREFLY_III_URL; ogni utente accede allora all'importatore con il proprio account.

Le e-mail: la configurazione SMTP

Per impostazione predefinita, MAIL_MAILER=log scrive i messaggi nei log anziché inviarli. Per ricevere le notifiche, come gli avvisi sugli abbonamenti, configurate l'invio in .env. La documentazione chiede di cambiare sempre MAIL_FROM e SITE_OWNER, altrimenti nessuna e-mail partirà mai.

Su un VPS Simafri, l'invio passa da un relay SMTP autenticato, sulla porta 587: l'indirizzo di un account di posta che avete già, oppure 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 accetta null, ssl, starttls o tls, a seconda del vostro fornitore; il codice della versione 6.7.9 ripiega su tls quando il valore è vuoto.
• La prova: la pagina /settings/notifications invia un'e-mail di prova, una volta ricreato il container.
• Gli altri canali: le notifiche possono andare anche su Slack, e su Discord o Mattermost tramite il loro URL di webhook seguito da /slack.

I backup

Firefly III non ha una procedura di backup integrata: la documentazione raccomanda gli strumenti del sistema, e precisa che la funzione di esportazione dell'applicazione non è un backup. Con Docker, ecco che cosa conservare:

Il database, a servizio attivo

Con MariaDB, mariadb-dump esporta il database senza fermare il servizio; la sua opzione --single-transaction fornisce una copia coerente delle tabelle InnoDB senza bloccarle. Lanciato dalla cartella del file Compose, il comando legge le credenziali dall'ambiente del container:

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

Con PostgreSQL, lo stesso principio passa da pg_dump:

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

Pianificate questa esportazione sul server almeno una volta al giorno, e fate pulizia tra i file, che si accumulano.

I volumi, a servizio fermo

La documentazione archivia ogni volume con un container usa e getta. Docker Compose antepone ai nomi dei volumi il nome del progetto, che per impostazione predefinita è quello della cartella: verificate i nomi esatti prima di lanciare l'archiviazione.

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

Un nome di volume scritto male non solleva alcun errore: Docker crea un volume vuoto con quel nome e lo archivia, sovrascrivendo il backup precedente. La documentazione chiede di verificare che il volume esista prima di ogni archiviazione.

Conservate una copia di .env e di questi archivi fuori dal server, cifrata, perché contiene la chiave e le credenziali del database. Collocati sul disco del server, questi file rientrano anche nei suoi backup notturni.

Ripristinare

La documentazione ripristina un volume con il comando inverso, a servizio fermo; il volume degli allegati si ripristina allo stesso modo:

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

Un'esportazione SQL si ricarica nel database in funzione:

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

Ripristinate anche .env con la sua APP_KEY, poi rilanciate e aprite i vostri conti. La documentazione lo ripete dopo ogni metodo: la prima cosa da fare con un backup è ripristinarlo, per verificare che funzioni.

Aggiornamenti e migrazioni

Firefly III si aggiorna da solo, anche da versioni vecchie come la 4.7, e migra il proprio database all'avvio del container. La documentazione avverte che alcuni aggiornamenti eliminano o ripuliscono dei dati, e chiede un backup del database e dei volumi prima di ciascuno, soprattutto tra versioni principali. Dalla cartella del file Compose:

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

• Il ritmo: dalla 6.7.0 del 14 settembre 2026 alla 6.7.9 dell'11 ottobre 2026, sono uscite dieci versioni in quattro settimane. Seguite le note di rilascio: dalla 6.7.8, una finestra nell'applicazione riassume le principali novità della versione installata.
• La versione 6.7.0 ha introdotto una nuova interfaccia; il suo motore di espressioni per le regole è disattivato per impostazione predefinita e si riattiva in /settings.
• Il file Compose: se lo scaricate di nuovo, verificate la versione del database che dichiara. La documentazione avverte che una nuova versione principale di MariaDB potrebbe non riprendere il volume della precedente.
• Una migrazione non riuscita: dalla 6.4.19, php artisan correction:rollback-single-migration elimina l'ultima voce di migrazione senza toccare i dati, poi php artisan migrate la esegue di nuovo, all'interno del container.
• Le versioni firmate: il progetto firma le proprie versioni, cosa che potete verificare con la sua chiave PGP.

L'importatore si aggiorna allo stesso modo, con docker compose rm -f tra l'arresto e il download delle immagini, secondo la sua documentazione.

Chi fa che cosa su un VPS gestito

Il self-hosting richiede di occuparsi del server oltre che dell'applicazione. Su un VPS gestito, i nostri team prendono in carico il server e seguono la vostra istanza in modo proattivo; Firefly III resta il vostro software, con le sue impostazioni e i vostri dati finanziari.

Se preferite che i nostri team intervengano nell'applicazione stessa, questa prestazione si fattura a ore o a forfait, con un preventivo comunicato prima dell'intervento.