Găzduirea Firefly III pe un Managed VPS: finanțele pe propriul server

Ce face Firefly III

Firefly III este un manager de finanțe personale conceput pentru găzduirea pe propriul server. El urmărește cheltuielile și veniturile dumneavoastră, cu bugete, categorii și etichete, ca să vedeți unde se duc banii. README-ul său îl descrie ca fiind complet găzduit de dumneavoastră și izolat: nu contactează niciun server extern până nu îi cereți explicit acest lucru.

• Contabilitatea: contabilitate în partidă dublă, conturi de active, datorii și orice monedă doriți.
• Automatizarea: tranzacții recurente și reguli pe care le scrieți pentru a clasa fiecare tranzacție.
• Urmărirea: bugete, „pușculițe” pentru a economisi în vederea unui obiectiv, rapoarte de venituri și cheltuieli, grafice.
• Securitatea: autentificare în doi pași pentru fiecare cont.
• Deschiderea: un API REST JSON care acoperă aproape întreaga aplicație, plus webhookuri.

O singură instanță găzduiește oricâți utilizatori doriți, fiecare cu o administrare financiară complet separată de a celorlalți. Documentația descrie un model de partajare a unei administrări comune, aflat în prezent în dezvoltare.

Ce permite licența AGPL

Firefly III este publicat sub GNU Affero General Public License, versiunea 3 sau, la alegerea dumneavoastră, orice versiune ulterioară: este identificatorul SPDX AGPL-3.0-or-later din fișierul său composer.json. Textul afirmă o permisiune nelimitată de a rula programul nemodificat. Puteți deci folosi imaginea publicată de proiect pentru dumneavoastră, familia sau firma dumneavoastră, fără nicio licență de cumpărat.

Articolul 13 adaugă o condiție specifică AGPL: dacă modificați programul, versiunea dumneavoastră trebuie să ofere tuturor celor care o folosesc de la distanță, prin rețea, posibilitatea de a obține gratuit codul sursă. Importatorul de date (Data Importer) este sub aceeași licență.

Instalarea cu Docker Compose

Documentația consideră Docker Compose cel mai simplu mod de a instala Firefly III. Pe un server unde Docker este instalat, creați un director și descărcați în el cele trei fișiere oficiale, în forma lor brută: spațierea lor contează, iar documentația cere să nu le copiați din 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 descrie trei servicii: app, aplicația, db, o bază de date MariaDB, și cron, sarcina programată.
• .env conține setările Firefly III, printre care cheia de criptare și accesul la baza de date.
• .db.env conține setările bazei de date. Păstrați ambele nume: fișierul Compose le apelează prin env_file.

Setările de modificat înainte de prima pornire

Generați două șiruri de 32 de caractere cu comanda indicată în fișierul .env: unul pentru cheie, celălalt pentru parola bazei de date.

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 criptează sesiunile. Are exact 32 de caractere, fără caractere speciale precum =, #, < sau >, iar fișierul cere să o păstrați în deplină siguranță.
• DB_PASSWORD din .env și MYSQL_PASSWORD din .db.env primesc aceeași valoare.
• SITE_OWNER: adresa dumneavoastră, afișată în unele erori utilizatorilor care nu sunt administratori.
• APP_URL: adresa publică a instanței dumneavoastră. Fișierul explică faptul că servește la validarea anumitor cereri și la construirea linkurilor din e-mailuri.
• TZ: fusul dumneavoastră orar, în formatul bazei tz, ca în exemplul din fișier.

Alegeți parola bazei de date înainte de prima pornire. Baza o înregistrează în volumul ei chiar de la creare: dacă o schimbați după aceea, ea nu mai corespunde, iar FAQ-ul Docker oferă o singură ieșire, ștergerea containerelor și a volumelor și reluarea de la zero.

Un port publicat local

Fișierul oficial publică aplicația pe portul 80 al tuturor adreselor serverului. Pentru a o servi în HTTPS în spatele unui proxy invers de pe aceeași mașină, modificați această singură linie din serviciul 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

La prima pornire, containerul creează și migrează singur baza de date. Când instalarea s-a încheiat, Firefly III vă mulțumește în jurnal pentru instalare: treceți la proxy-ul invers.

• Eticheta latest urmărește ultima versiune stabilă. O etichetă precum version-6.7.9 fixează o versiune; proiectul le șterge pe cele vechi după aproximativ șase luni.
• Arhitecturile: imaginile sunt construite pentru linux/amd64 și linux/arm64.
• Volumele: firefly_iii_upload păstrează atașamentele, firefly_iii_db baza de date.

Documentația nu indică nicio cifră pentru memorie; FAQ-ul său Docker sugerează PHP_MEMORY_LIMIT=512M sau mai mult dacă PHP rămâne fără memorie. Dimensiunea depinde de numărul de utilizatori, de volumul tranzacțiilor și de importatorul de date. Pe un Managed VPS, descrieți-ne utilizarea dumneavoastră și vă recomandăm dimensiunea potrivită.

HTTPS și proxy-ul invers

Firefly III servește aplicația în HTTP pe portul 8080 din interiorul containerului, iar HTTPS-ul se află pe proxy-ul invers plasat în față. Aplicația citește antetul X-Forwarded-Proto pentru a ști că vizitatorul a sosit în HTTPS, cu condiția să aibă încredere în proxy:

TRUSTED_PROXIES=*

FAQ-ul Docker este clar în această privință: fără TRUSTED_PROXIES=*, linkurile rămân în http, formularele și graficele nu mai funcționează, iar antetele de securitate CSP eșuează. Cu portul publicat pe 127.0.0.1, doar proxy-ul serverului ajunge la aplicație. Recreați containerul după fiecare modificare a fișierului .env:

docker compose up -d --force-recreate app

Cu Caddy

Caddy obține singur certificatul Let’s Encrypt, iar directiva sa reverse_proxy setează implicit antetele X-Forwarded-For, X-Forwarded-Proto și X-Forwarded-Host:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Cu Nginx și Certbot

Acest bloc preia antetele din FAQ-ul de instalare și bufferele pe care acesta le sugerează împotriva erorilor 502, atunci când aplicația returnează un token într-un antet lung. El ascultă pe portul 80, pentru a lăsa Certbot să instaleze 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 instalează apoi certificatul și se ocupă de reînnoirea lui:

sudo certbot --nginx

• Un nume de domeniu propriu: serviți Firefly III pe un nume dedicat, precum finances.example.com. FAQ-ul notează că Laravel nu interpretează o adresă IPv6 brută în URL.
• Erorile 431: FAQ-ul le atribuie unei limite prea mici a dimensiunii antetelor pe proxy, care face să eșueze unele acțiuni, precum conectarea.

Primul cont și înregistrările

Primul utilizator care se înregistrează devine proprietarul instanței. Ca măsură de securitate, înregistrările se închid apoi singure: majoritatea oamenilor instalează Firefly III doar pentru ei înșiși.

1. Deschideți adresa dumneavoastră HTTPS de îndată ce proxy-ul răspunde și creați-vă contul: el primește rolul de proprietar.
2. Activați autentificarea în doi pași în profilul dumneavoastră și păstrați cele opt coduri de rezervă pe care le afișează.
3. Pentru a deschide instanța altor persoane, mergeți la /settings, deschideți opțiunile de configurare Firefly III, debifați opțiunea care dezactivează înregistrările și salvați.

• Autentificarea în doi pași se sprijină pe ceas: FAQ-ul precizează că o diferență de oră între telefon și server o face să eșueze.
• Conectarea prin furnizorul dumneavoastră de identitate: cu AUTHENTICATION_GUARD=remote_user_guard, Firefly III are încredere într-un proxy de autentificare plasat în față, precum Authelia sau Authentik, care transmite utilizatorul într-un antet.
• Tokenurile de acces: clienții OAuth și tokenurile API personale se creează din profil.

Sarcina cron

Mai multe funcții merg doar cu o sarcină programată: bugetele automate, tranzacțiile recurente, alertele de abonament și cursurile de schimb actualizate. Imaginea Docker nu rulează singură cron; fișierul oficial adaugă în acest scop un mic serviciu cron, care apelează aplicația în fiecare zi la ora 3 dimineața.

El se autentifică printr-un token static. Generați un al treilea șir cu aceeași comandă și puneți-l în .env:

STATIC_CRON_TOKEN=

Acest token are exact 32 de caractere: codul versiunii 6.7.9 nu acceptă altă lungime. Iată serviciul așa cum îl declară fișierul oficial; dublul $$ este intenționat și trimite la liniile TZ și STATIC_CRON_TOKEN din fișierul .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

O singură sarcină este suficientă pentru toți utilizatorii instanței. Pentru a verifica dacă a rulat, citiți jurnalul containerului: fiecare sarcină raportează în JSON, cu job_fired și job_succeeded.

docker logs firefly_iii_cron

Pentru a o rula manual, FAQ-ul Docker cere să treceți prin utilizatorul www-data, nu prin root: FAQ-ul leagă această capcană de erorile de permisiuni pe fișierele de jurnal:

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

MariaDB, PostgreSQL sau SQLite

Fișierul oficial livrează MariaDB, cu imaginea mariadb:lts. Firefly III suportă și PostgreSQL și SQLite, alese prin DB_CONNECTION în .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

Pentru PostgreSQL, documentația îndreaptă și serviciul db spre imaginea postgres, care instalează PostgreSQL 18, și îi montează volumul pe /var/lib/postgresql. În .db.env, variabilele MYSQL_* devin POSTGRES_USER, POSTGRES_DB și POSTGRES_PASSWORD.

Faceți această alegere înainte de a introduce primele tranzacții. FAQ-ul precizează că trecerea de la o bază la alta rămâne posibilă, fără a fi suportată de Firefly III însuși, și că exportul aplicației nu preia toate datele.

Importatorul de date (Data Importer)

Firefly III Data Importer este un instrument separat, cu propria instalare și propriile actualizări; versiunea sa 2.3.5 a apărut la 23 septembrie 2026. El importă fișiere CSV și CAMT.053 și poate prelua și tranzacțiile de la băncile dumneavoastră prin furnizori de date terți, fiecare cu propriile condiții.

Depozitul Docker oficial îl livrează într-un al doilea fișier, docker-compose-importer.yml, care păstrează aceleași servicii și adaugă importer. Setările sale se pun într-un fișier .importer.env, preluat din .env.example al importatorului. Serviți-l pe un nume de domeniu propriu, cu un port publicat local și un al doilea bloc de proxy: FAQ-ul cere să nu îl plasați într-un subdirector.

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

• FIREFLY_III_URL: adresa internă a aplicației, la care importatorul ajunge prin rețeaua Docker.
• VANITY_URL: adresa publică a Firefly III, cea pe care o cunosc utilizatorii dumneavoastră.
• Clientul OAuth: în profilul dumneavoastră Firefly III, creați un client al cărui URL de callback este adresa importatorului urmată de /callback și debifați „Confidential”. Importatorul vă cere apoi ID-ul acestui client.
• Mai mulți utilizatori: lăsați FIREFLY_III_ACCESS_TOKEN gol și păstrați FIREFLY_III_URL; fiecare utilizator se conectează atunci la importator cu propriul cont.

E-mailurile: configurarea SMTP

Implicit, MAIL_MAILER=log scrie mesajele în jurnale în loc să le trimită. Pentru a primi notificările, precum alertele de abonament, configurați trimiterea în .env. Documentația cere să schimbați întotdeauna MAIL_FROM și SITE_OWNER, altfel niciun e-mail nu va pleca.

Pe un VPS Simafri, trimiterea trece printr-un releu SMTP autentificat, pe portul 587: adresa unui cont de e-mail pe care îl aveți deja sau 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 acceptă null, ssl, starttls sau tls, în funcție de furnizorul dumneavoastră; codul versiunii 6.7.9 revine la tls când valoarea este goală.
• Proba: pagina /settings/notifications trimite un e-mail de test, după ce containerul a fost recreat.
• Alte canale: notificările pot merge și spre Slack, precum și spre Discord sau Mattermost prin URL-ul lor de webhook urmat de /slack.

Backupurile

Firefly III nu are o rutină de backup integrată: documentația recomandă instrumentele sistemului și subliniază că funcția de export a aplicației nu este un backup. Cu Docker, iată ce trebuie păstrat:

Baza, cu serviciul în funcțiune

Cu MariaDB, mariadb-dump exportă baza fără oprirea serviciului; opțiunea sa --single-transaction oferă o copie coerentă a tabelelor InnoDB, fără a le bloca. Rulată din directorul fișierului Compose, comanda citește datele de acces din mediul containerului:

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

Cu PostgreSQL, aceeași idee trece prin pg_dump:

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

Programați acest export pe server cel puțin o dată pe zi și faceți ordine printre fișiere, care se acumulează.

Volumele, cu serviciul oprit

Documentația arhivează fiecare volum cu un container de unică folosință. Docker Compose prefixează numele volumelor cu numele proiectului, care este implicit numele directorului: verificați numele exacte înainte de a lansa arhivarea.

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 nume de volum scris greșit nu produce nicio eroare: Docker creează un volum gol cu acest nume și îl arhivează, ceea ce suprascrie backupul precedent. Documentația cere să verificați existența volumului înaintea fiecărei arhivări.

Păstrați o copie a fișierului .env și a acestor arhive în afara serverului, criptată, căci ea conține cheia și datele de acces la baza de date. Puse pe discul serverului, aceste fișiere intră și în backupurile sale de noapte.

Restaurarea

Documentația restaurează un volum cu comanda inversă, cu serviciul oprit; volumul atașamentelor se restaurează în același fel:

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 export SQL se reîncarcă în baza în funcțiune:

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

Restaurați și .env cu APP_KEY, apoi reporniți și deschideți-vă conturile. Documentația o repetă după fiecare metodă: primul lucru de făcut cu un backup este să îl restaurați, ca să verificați că funcționează.

Actualizările și migrările

Firefly III se actualizează singur, chiar și de la versiuni vechi precum 4.7, și își migrează baza de date la pornirea containerului. Documentația avertizează că unele actualizări șterg sau curăță date și cere un backup al bazei și al volumelor înaintea fiecăreia, mai ales între versiuni majore. Din directorul fișierului Compose:

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

• Ritmul: de la 6.7.0, din 14 septembrie 2026, la 6.7.9, din 11 octombrie 2026, au apărut zece versiuni în patru săptămâni. Urmăriți notele de versiune: începând cu 6.7.8, o fereastră din aplicație rezumă principalele schimbări ale versiunii instalate.
• Versiunea 6.7.0 a adus o interfață nouă; motorul său de expresii pentru reguli este dezactivat implicit și se reactivează în /settings.
• Fișierul Compose: dacă îl descărcați din nou, verificați versiunea bazei de date pe care o declară. Documentația avertizează că o nouă versiune majoră de MariaDB poate să nu preia volumul celei vechi.
• O migrare care nu a reușit: începând cu 6.4.19, php artisan correction:rollback-single-migration elimină ultima înregistrare de migrare fără a atinge datele, apoi php artisan migrate o rulează din nou, în container.
• Versiuni semnate: proiectul își semnează versiunile, pe care le puteți verifica cu cheia sa PGP.

Importatorul se actualizează în același fel, cu docker compose rm -f între oprire și descărcarea imaginilor, potrivit documentației sale.

Cine ce face pe un Managed VPS

Găzduirea pe propriul server cere să țineți serverul pe lângă aplicație. Pe un Managed VPS, echipele noastre preiau serverul și vă urmăresc proactiv instanța; Firefly III rămâne software-ul dumneavoastră, cu setările sale și datele dumneavoastră financiare.

Dacă preferați ca echipele noastre să intervină în aplicația însăși, această prestație se facturează la oră sau la preț fix, cu o ofertă comunicată înainte de intervenție.