Firefly III hosztolása Managed VPS-en: pénzügyei a saját szerverén

Mit tud a Firefly III

A Firefly III saját üzemeltetésre készült személyes pénzügykezelő. Követi a kiadásait és a bevételeit, költségvetésekkel, kategóriákkal és címkékkel, hogy lássa, hová megy a pénze. A README teljesen saját üzemeltetésűként és elszigeteltként írja le: semmilyen külső szerverrel nem lép kapcsolatba, amíg Ön kifejezetten erre nem utasítja.

• A könyvelés: kettős könyvvitel, eszközszámlák, kötelezettségek és bármilyen pénznem, amelyre szüksége van.
• Az automatizálás: ismétlődő tranzakciók és saját szabályok, amelyekkel minden tranzakciót besorol.
• A követés: költségvetések, malacperselyek egy cél felé való takarékoskodáshoz, bevételi és kiadási jelentések, grafikonok.
• A biztonság: kétlépcsős hitelesítés minden fiókhoz.
• A nyitottság: REST JSON API, amely szinte az egész alkalmazást lefedi, valamint webhookok.

Egy példány annyi felhasználót fogad, amennyit szeretne, mindegyiket a többitől teljesen elkülönített pénzügyi adminisztrációval. A dokumentáció leír egy modellt egyetlen adminisztráció megosztására, amely jelenleg fejlesztés alatt áll.

Mit enged meg az AGPL licenc

A Firefly III a GNU Affero General Public License 3. verziója, vagy választása szerint bármely későbbi verziója alatt jelenik meg: ezt jelzi a composer.json fájlban szereplő AGPL-3.0-or-later SPDX-azonosító. A szöveg korlátlan engedélyt ad a módosítatlan program futtatására. A projekt által közzétett image-et tehát használhatja saját magának, a családjának vagy a vállalkozásának, licenc vásárlása nélkül.

A 13. szakasz az AGPL-re jellemző feltételt tesz hozzá: ha módosítja a programot, a változatának mindenkinek, aki távolról, a hálózaton keresztül használja, lehetőséget kell adnia a forráskód ingyenes megszerzésére. Az adatimportáló ugyanezen licenc alatt áll.

Telepítés Docker Compose-zal

A dokumentáció a Docker Compose-t nevezi a Firefly III telepítésének legegyszerűbb módjaként. Egy olyan szerveren, ahol a Docker telepítve van, hozzon létre egy mappát, és töltse le bele a három hivatalos fájlt, nyers formában: a térközeik számítanak, és a dokumentáció kéri, hogy ne a böngészőből másolja ki őket.

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

• A docker-compose.yml három szolgáltatást ír le: az app az alkalmazás, a db egy MariaDB-adatbázis, a cron pedig az ütemezett feladat.
• Az .env a Firefly III beállításait tartalmazza, köztük a titkosítási kulcsot és az adatbázis-hozzáférést.
• A .db.env az adatbázis beállításait tartalmazza. Tartsa meg mindkét nevet: a Compose-fájl az env_file révén hivatkozik rájuk.

Az első indítás előtt módosítandó beállítások

Állítson elő két 32 karakteres karakterláncot az .env fájlban megadott paranccsal: egyet a kulcshoz, egyet az adatbázis jelszavához.

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=

• Az APP_KEY titkosítja a munkameneteit. Pontosan 32 karakter hosszú, olyan speciális karakterek nélkül, mint a =, a #, a < vagy a >, és a fájl kéri, hogy nagyon gondosan őrizze.
• A DB_PASSWORD az .env fájlban és a MYSQL_PASSWORD a .db.env fájlban ugyanazt az értéket kapja.
• A SITE_OWNER: az Ön címe, amely egyes hibaüzenetekben jelenik meg a nem adminisztrátor felhasználóknak.
• Az APP_URL: a példánya nyilvános címe. A fájl elmagyarázza, hogy bizonyos kérések ellenőrzésére és az e-mailekben lévő linkek felépítésére szolgál.
• A TZ: az Ön időzónája, a tz-adatbázis formátumában, ahogyan a fájlban lévő példa mutatja.

Az adatbázis jelszavát az első indítás előtt válassza meg. Az adatbázis a létrehozásakor eltárolja a kötetében: ha utólag módosítja, már nem egyezik, és a Dockerről szóló GYIK egyetlen megoldást kínál: a konténerek és a kötetek törlését, majd az újrakezdést.

Helyben közzétett port

A hivatalos fájl az alkalmazást a szerver minden címének 80-as portján teszi közzé. Ahhoz, hogy egy ugyanazon a gépen futó fordított proxy mögött HTTPS-en szolgálja ki, módosítsa ezt az egyetlen sort az app szolgáltatásban:

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

Az első indításkor a konténer maga hozza létre és migrálja az adatbázist. Amikor a telepítés kész, a Firefly III a naplóban megköszöni, hogy telepítette: térjen át a fordított proxyra.

• A latest címke a legutóbbi stabil kiadást követi. Egy olyan címke, mint a version-6.7.9, rögzít egy verziót; a projekt nagyjából hat hónap után eltávolítja a régieket.
• Az architektúrák: az image-ek linux/amd64 és linux/arm64 rendszerre készülnek.
• A kötetek: a firefly_iii_upload a csatolmányokat, a firefly_iii_db az adatbázist tárolja.

A dokumentáció nem ad meg memóriaigényt; a Dockerről szóló GYIK PHP_MEMORY_LIMIT=512M vagy nagyobb értéket javasol, ha a PHP-nak elfogy a memóriája. A méret a felhasználók számától, a tranzakciók mennyiségétől és az adatimportálótól függ. Egy Managed VPS esetén írja le nekünk a használatát, és mi azt a méretet javasoljuk, amely megfelel.

HTTPS és a fordított proxy

A Firefly III a konténeren belül a 8080-as porton, HTTP-n szolgálja ki az alkalmazást, a HTTPS pedig az elé helyezett fordított proxyn van. Az alkalmazás az X-Forwarded-Proto fejlécből tudja meg, hogy a látogató HTTPS-en érkezett, feltéve, hogy megbízik a proxyban:

TRUSTED_PROXIES=*

A Dockerről szóló GYIK ebben egyértelmű: TRUSTED_PROXIES=* nélkül a linkek http-n maradnak, az űrlapok és a grafikonok nem működnek, és a CSP biztonsági fejlécek hibát jeleznek. A 127.0.0.1 címen közzétett porttal csak a szerver saját proxyja éri el az alkalmazást. Az .env fájl minden módosítása után hozza létre újra a konténert:

docker compose up -d --force-recreate app

Caddyvel

A Caddy magától megszerzi a Let's Encrypt-tanúsítványt, a reverse_proxy direktívája pedig alapértelmezésként beállítja az X-Forwarded-For, az X-Forwarded-Proto és az X-Forwarded-Host fejlécet:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Nginxszel és Certbottal

Ez a blokk a telepítési GYIK fejléceit követi, valamint azokat a puffereket, amelyeket az 502-es hibák ellen javasol, amikor az alkalmazás egy hosszú fejlécben tokent ad vissza. A 80-as porton figyel, hogy a Certbot beállíthassa a HTTPS-t:

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;
    }
}

A Certbot ezután telepíti a tanúsítványt, és gondoskodik a megújításáról:

sudo certbot --nginx

• Saját domainnév: szolgálja ki a Firefly III-at saját néven, például a finances.example.com címen. A GYIK megjegyzi, hogy a Laravel nem értelmezi az URL-ben szereplő nyers IPv6-címet.
• A 431-es hibák: a GYIK a proxy túl alacsony fejlécméret-korlátjára vezeti vissza őket, amely miatt egyes műveletek, például a bejelentkezés, meghiúsulnak.

Az első fiók és a regisztráció

Az elsőként regisztráló felhasználó lesz a példány tulajdonosa. Biztonsági okból a regisztráció ezután magától lezárul: a legtöbben csak saját maguknak telepítik a Firefly III-at.

1. Nyissa meg a HTTPS-címét, amint a proxy válaszol, és hozza létre a fiókját: ez kapja a tulajdonosi szerepkört.
2. Kapcsolja be a kétlépcsős hitelesítést a profiljában, és őrizze meg a nyolc tartalékkódot, amelyet megjelenít.
3. Ha másoknak is meg szeretné nyitni a példányt, lépjen a /settings oldalra, nyissa meg a Firefly III konfigurációs beállításait, vegye ki a pipát a regisztrációt letiltó opció mellől, és mentsen.

• A kétlépcsős hitelesítés az órára támaszkodik: a GYIK szerint a telefon és a szerver közötti időeltérés miatt meghiúsul.
• Bejelentkezés az identitásszolgáltatóján keresztül: az AUTHENTICATION_GUARD=remote_user_guard beállítással a Firefly III megbízik egy elé helyezett hitelesítési proxyban, például az Autheliában vagy az Authentikban, amely egy fejlécben adja át a felhasználót.
• A hozzáférési tokenek: az OAuth-kliensek és a személyes API-tokenek a profilból hozhatók létre.

A cron-feladat

Több funkció csak ütemezett feladattal működik: az automatikus költségvetések, az ismétlődő tranzakciók, az előfizetésekre vonatkozó figyelmeztetések és a naprakész árfolyamok. A Docker image magától nem futtat cront; a hivatalos fájl ehhez egy kis cron szolgáltatást ad hozzá, amely minden nap hajnali 3 órakor meghívja az alkalmazást.

Egy statikus tokennel hitelesít. Állítson elő egy harmadik karakterláncot ugyanazzal a paranccsal, és helyezze az .env fájlba:

STATIC_CRON_TOKEN=

Ez a token pontosan 32 karakter hosszú: a 6.7.9-es verzió kódja más hosszúságot nem fogad el. Íme a szolgáltatás, ahogyan a hivatalos fájl deklarálja; a dupla $$ szándékos, és az .env fájl TZ és STATIC_CRON_TOKEN sorára hivatkozik:

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

Egyetlen feladat elég a példány összes felhasználójának. Annak ellenőrzéséhez, hogy lefutott-e, olvassa el a konténer naplóját: minden feladat JSON-ban jelent, a job_fired és a job_succeeded mezővel.

docker logs firefly_iii_cron

Kézi futtatáshoz a Dockerről szóló GYIK azt kéri, hogy a root helyett a www-data felhasználóval tegye: a GYIK ehhez a csapdához köti a naplófájlok jogosultsági hibáit:

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

MariaDB, PostgreSQL vagy SQLite

A hivatalos fájl MariaDB-t tartalmaz, a mariadb:lts image-gel. A Firefly III a PostgreSQL-t és az SQLite-ot is támogatja, a választás az .env fájl DB_CONNECTION változójával történik:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

PostgreSQL esetén a dokumentáció a db szolgáltatást is a postgres image-re állítja át, amely a PostgreSQL 18-at telepíti, és a kötetét a /var/lib/postgresql útvonalra csatolja. A .db.env fájlban a MYSQL_* változókból POSTGRES_USER, POSTGRES_DB és POSTGRES_PASSWORD lesz.

Ezt a választást az első tranzakciók rögzítése előtt tegye meg. A GYIK szerint az egyik adatbázisról a másikra való áttérés lehetséges marad, bár maga a Firefly III nem támogatja, és az alkalmazás exportja nem visz át minden adatot.

Az adatimportáló (Data Importer)

A Firefly III Data Importer külön eszköz, saját telepítéssel és saját frissítésekkel; a 2.3.5-ös verziója 2026. szeptember 23-án jelent meg. CSV- és CAMT.053-fájlokat importál, és harmadik fél adatszolgáltatóin keresztül a bankjaiból is képes lekérni a tranzakciókat, mindegyik szolgáltató a saját feltételeivel.

A hivatalos Docker-tároló egy második fájlban, a docker-compose-importer.yml fájlban adja, amely megtartja ugyanazokat a szolgáltatásokat, és hozzáadja az importer szolgáltatást. A beállításai egy .importer.env fájlba kerülnek, amely az importáló .env.example fájljából készül. Szolgálja ki saját domainnéven, helyben közzétett porttal és egy második proxyblokkal: a GYIK kéri, hogy ne helyezze alkönyvtárba.

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

• A FIREFLY_III_URL: az alkalmazás belső címe, amelyet az importáló a Docker-hálózaton keresztül ér el.
• A VANITY_URL: a Firefly III nyilvános címe, amelyet a felhasználói ismernek.
• Az OAuth-kliens: a Firefly III profiljában hozzon létre egy klienst, amelynek visszahívási URL-je az importáló címe, a végén a /callback résszel, és vegye ki a pipát a „Confidential” (bizalmas) mezőből. Az importáló ezután a kliensazonosítót kéri.
• Több felhasználó: hagyja üresen a FIREFLY_III_ACCESS_TOKEN értékét, és tartsa meg a FIREFLY_III_URL változót; ekkor minden felhasználó a saját fiókjával jelentkezik be az importálóba.

Az e-mailek: az SMTP-konfiguráció

Alapértelmezésként a MAIL_MAILER=log a naplókba írja az üzeneteket ahelyett, hogy elküldené őket. Az értesítések, például az előfizetésekre vonatkozó figyelmeztetések fogadásához állítsa be a küldést az .env fájlban. A dokumentáció kéri, hogy mindig módosítsa a MAIL_FROM és a SITE_OWNER értékét, különben egyetlen e-mail sem indul el.

Simafri VPS-en a küldés egy hitelesített SMTP-továbbítón keresztül megy, a 587-es porton: egy meglévő levelezési fiók címével, vagy a Simafri Suite-tal.

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

• A MAIL_ENCRYPTION a szolgáltatójától függően a null, az ssl, a starttls vagy a tls értéket fogadja el; a 6.7.9-es verzió kódja üres érték esetén a tls értéket használja.
• A próba: a /settings/notifications oldal tesztüzenetet küld, miután a konténert újra létrehozta.
• Más csatornák: az értesítések a Slackre is mehetnek, valamint a Discordra vagy a Mattermostra, a webhook-URL-jükkel, amelynek a végére a /slack kerül.

A mentések

A Firefly III-nak nincs beépített mentési rutinja: a dokumentáció a rendszer saját eszközeit ajánlja, és rámutat, hogy az alkalmazás exportfunkciója nem mentés. Dockerrel a következőket kell megőrizni:

Az adatbázis, futó szolgáltatás mellett

MariaDB esetén a mariadb-dump a szolgáltatás leállítása nélkül exportálja az adatbázist; a --single-transaction kapcsolója zárolás nélkül ad konzisztens másolatot az InnoDB-táblákról. A Compose-fájl mappájából futtatva a parancs a konténer környezetéből olvassa ki a hozzáférési adatokat:

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

PostgreSQL esetén ugyanez a pg_dump segítségével történik:

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

Ütemezze ezt az exportot a szerveren legalább naponta egyszer, és válogassa ki a fájlokat, mert felhalmozódnak.

A kötetek, leállított szolgáltatás mellett

A dokumentáció minden kötetet egy eldobható konténerrel archivál. A Docker Compose a kötetek neve elé a projekt nevét teszi, amely alapértelmezésként a mappa neve: az archiválás előtt ellenőrizze a pontos neveket.

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

Egy elírt kötetnév nem okoz hibát: a Docker ezen a néven üres kötetet hoz létre és azt archiválja, ami felülírja az előző mentést. A dokumentáció kéri, hogy minden archiválás előtt ellenőrizze, létezik-e a kötet.

Őrizzen meg egy titkosított másolatot az .env fájlról és ezekről az archívumokról a szerveren kívül, mivel a kulcsot és az adatbázis hozzáférési adatait tartalmazzák. A szerver lemezére téve ezek a fájlok a szerver éjszakai mentéseibe is bekerülnek.

Visszaállítás

A dokumentáció a fordított paranccsal, leállított szolgáltatás mellett állít vissza egy kötetet; a csatolmányok kötete ugyanígy állítható vissza:

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

Egy SQL-export a futó adatbázisba töltődik vissza:

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

Állítsa vissza az .env fájlt is az APP_KEY kulccsal együtt, majd indítsa újra a szolgáltatást, és nyissa meg a számláit. A dokumentáció minden módszer után megismétli: egy mentéssel az első teendő a visszaállítása, hogy ellenőrizze, működik-e.

Frissítések és migrációk

A Firefly III maga frissíti magát, akár olyan régi verziókról is, mint a 4.7-es, és a konténer indulásakor migrálja az adatbázisát. A dokumentáció figyelmeztet, hogy egyes frissítések adatokat törölnek vagy tisztítanak, és mindegyik előtt az adatbázis és a kötetek mentését kéri, különösen főverziók között. A Compose-fájl mappájából:

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

• A tempó: a 2026. szeptember 14-i 6.7.0-s verziótól a 2026. október 11-i 6.7.9-esig tíz verzió jelent meg négy hét alatt. Kövesse a kiadási megjegyzéseket: a 6.7.8-as verzió óta az alkalmazásban egy ablak összefoglalja a telepített verzió fő változásait.
• A 6.7.0-s verzió új felületet hozott; a szabálykifejezés-motorja alapértelmezésként ki van kapcsolva, és a /settings oldalon kapcsolható vissza.
• A Compose-fájl: ha újra letölti, ellenőrizze, milyen adatbázisverziót deklarál. A dokumentáció figyelmeztet, hogy a MariaDB egy új főverziója nem feltétlenül veszi át a régi kötetét.
• Egy sikertelen migráció: a 6.4.19-es verzió óta a konténeren belül a php artisan correction:rollback-single-migration az adatok érintése nélkül eltávolítja a legutóbbi migrációs bejegyzést, majd a php artisan migrate újra lefuttatja.
• Aláírt kiadások: a projekt aláírja a kiadásait, amit a PGP-kulcsával ellenőrizhet.

Az importáló ugyanígy frissül, a dokumentációja szerint a leállítás és az image-ek letöltése között egy docker compose rm -f paranccsal.

Ki mit csinál egy Managed VPS-en

A saját üzemeltetés az alkalmazás mellett a szerver gondozását is megköveteli. Egy Managed VPS esetén csapataink átveszik a szervert, és proaktívan követik a példányát; a Firefly III továbbra is az Ön szoftvere marad, a beállításaival és a pénzügyi adataival.

Ha inkább azt szeretné, hogy csapataink magában az alkalmazásban avatkozzanak be, ez a szolgáltatás óradíjban vagy átalánydíjban számlázódik, a beavatkozás előtt közölt árajánlattal.