Gostovanje Firefly III na Managed VPS: vaše finance na vašem strežniku

Kaj počne Firefly III

Firefly III je aplikacija za upravljanje osebnih financ, zasnovana za samostojno gostovanje. Beleži vaše izdatke in prihodke, s proračuni, kategorijami in oznakami, tako da vidite, kam gre vaš denar. README ga opisuje kot povsem samostojno gostovanega in izoliranega: ne vzpostavi stika z nobenim zunanjim strežnikom, dokler mu tega izrecno ne naročite.

• Knjigovodstvo: dvostavno knjigovodstvo, računi sredstev, obveznosti in katera koli valuta.
• Avtomatizacija: ponavljajoče se transakcije in pravila, ki jih napišete za razvrščanje vsake transakcije.
• Spremljanje: proračuni, hranilniki za varčevanje za cilj, poročila o prihodkih in odhodkih, grafi.
• Varnost: dvostopenjsko preverjanje pristnosti za vsak račun.
• Odprtost: API REST JSON, ki pokriva skoraj vso aplikacijo, in spletni kavlji (webhooks).

Ena instanca gosti poljubno število uporabnikov, vsakega s finančno upravo, povsem ločeno od drugih. Dokumentacija opisuje model za deljenje ene same uprave, ki je trenutno v razvoju.

Kaj dovoljuje licenca AGPL

Firefly III je objavljen pod licenco GNU Affero General Public License, različica 3 ali, po vaši izbiri, katera koli poznejša različica: to je identifikator SPDX AGPL-3.0-or-later v njegovi datoteki composer.json. Besedilo določa neomejeno dovoljenje za poganjanje nespremenjenega programa. Sliko, ki jo objavi projekt, torej lahko uporabljate zase, za svojo družino ali za svoje podjetje, ne da bi morali kupiti licenco.

13. člen dodaja pogoj, značilen za AGPL: če program spremenite, mora vaša različica vsem, ki jo uporabljajo na daljavo, prek omrežja, ponuditi možnost brezplačnega prejema izvorne kode. Orodje Data Importer je pod isto licenco.

Namestitev z Docker Compose

Dokumentacija Docker Compose označuje za najpreprostejši način namestitve programa Firefly III. Na strežniku z nameščenim Dockerjem ustvarite mapo in vanjo prenesite tri uradne datoteke, v surovi obliki: njihovi presledki so pomembni, dokumentacija pa prosi, naj jih ne kopirate iz brskalnika.

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 opisuje tri storitve: app, aplikacijo, db, podatkovno zbirko MariaDB, in cron, načrtovano opravilo.
• .env hrani nastavitve programa Firefly III, med njimi šifrirni ključ in dostop do zbirke.
• .db.env hrani nastavitve zbirke. Obdržite obe imeni: datoteka Compose ju kliče prek env_file.

Nastavitve, ki jih spremenite pred prvim zagonom

Z ukazom, navedenim v datoteki .env, ustvarite dva niza po 32 znakov: enega za ključ, drugega za geslo zbirke.

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 šifrira vaše seje. Ima natanko 32 znakov, brez posebnih znakov, kot so =, #, < ali >, datoteka pa prosi, naj ga skrbno varujete.
• DB_PASSWORD v .env in MYSQL_PASSWORD v .db.env dobita isto vrednost.
• SITE_OWNER: vaš naslov, prikazan v nekaterih napakah uporabnikom, ki niso skrbniki.
• APP_URL: javni naslov vaše instance. Datoteka pojasnjuje, da služi preverjanju nekaterih zahtev in sestavljanju povezav v e-poštnih sporočilih.
• TZ: vaš časovni pas, v obliki baze tz, kot kaže primer v datoteki.

Geslo zbirke izberite pred prvim zagonom. Zbirka ga shrani v svoj nosilec takoj, ko je ustvarjena: če ga pozneje spremenite, se ne ujema več, pogosta vprašanja za Docker pa ponujajo en sam izhod, odstranitev vsebnikov in nosilcev ter začetek znova.

Lokalno objavljena vrata

Uradna datoteka aplikacijo objavi na vratih 80 vseh naslovov strežnika. Če jo želite streči prek HTTPS za obratnim posredniškim strežnikom na istem stroju, v storitvi app spremenite to eno vrstico:

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

Ob prvem zagonu vsebnik sam ustvari zbirko in izvede njene migracije. Ko je namestitev končana, se vam Firefly III v dnevniku zahvali za namestitev: preidite na obratni posredniški strežnik.

• Oznaka latest sledi zadnji stabilni različici. Oznaka, kot je version-6.7.9, določi različico; projekt stare odstrani po približno šestih mesecih.
• Arhitekture: slike so zgrajene za linux/amd64 in linux/arm64.
• Nosilci: firefly_iii_upload hrani priponke, firefly_iii_db zbirko.

Dokumentacija ne navaja potrebnega pomnilnika; njena pogosta vprašanja za Docker predlagajo PHP_MEMORY_LIMIT=512M ali več, če PHP-ju zmanjka pomnilnika. Velikost je odvisna od števila uporabnikov, obsega transakcij in uvoza podatkov. Na Managed VPS nam opišite svojo rabo in priporočimo vam ustrezno velikost.

HTTPS in obratni posredniški strežnik

Firefly III aplikacijo v vsebniku streže prek HTTP na vratih 8080, HTTPS pa je na obratnem posredniškem strežniku pred njim. Aplikacija bere glavo X-Forwarded-Proto, da ve, da je obiskovalec prišel prek HTTPS, če le zaupa posredniškemu strežniku:

TRUSTED_PROXIES=*

Pogosta vprašanja za Docker so pri tem jasna: brez TRUSTED_PROXIES=* povezave ostanejo na http, obrazci in grafi prenehajo delovati, varnostne glave CSP pa odpovedo. Z vrati, objavljenimi na 127.0.0.1, aplikacijo doseže le posredniški strežnik na istem strežniku. Po vsaki spremembi datoteke .env vsebnik znova ustvarite:

docker compose up -d --force-recreate app

S Caddyjem

Caddy sam pridobi potrdilo Let’s Encrypt, njegova direktiva reverse_proxy pa privzeto nastavi glave X-Forwarded-For, X-Forwarded-Proto in X-Forwarded-Host:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Z Nginxom in Certbotom

Ta blok sledi glavam iz pogostih vprašanj o namestitvi in medpomnilnikom, ki jih ta predlagajo proti napakam 502, ko aplikacija vrne žeton v dolgi glavi. Posluša na vratih 80, da lahko Certbot vzpostavi 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 nato namesti potrdilo in poskrbi za njegovo obnavljanje:

sudo certbot --nginx

• Lastno ime domene: Firefly III strežite pod lastnim imenom, kot je finances.example.com. Pogosta vprašanja opozarjajo, da Laravel ne razčleni golega naslova IPv6 v URL-ju.
• Napake 431: pogosta vprašanja jih pripisujejo premajhni omejitvi velikosti glav na posredniškem strežniku, zaradi katere nekatera dejanja odpovedo, na primer prijava.

Prvi račun in registracije

Prvi registrirani uporabnik postane lastnik instance. Iz varnostnih razlogov se registracije nato same zaprejo: večina ljudi Firefly III namesti le zase.

1. Odprite svoj naslov HTTPS, takoj ko posredniški strežnik odgovori, in ustvarite svoj račun: dobi vlogo lastnika.
2. V svojem profilu vključite dvostopenjsko preverjanje pristnosti in shranite osem rezervnih kod, ki jih prikaže.
3. Če želite instanco odpreti drugim, pojdite na /settings, odprite konfiguracijske možnosti programa Firefly III, odznačite možnost, ki onemogoča registracije, in shranite.

• Dvostopenjsko preverjanje pristnosti temelji na uri: pogosta vprašanja navajajo, da ga časovna razlika med telefonom in strežnikom onemogoči.
• Prijava prek vašega ponudnika identitete: z AUTHENTICATION_GUARD=remote_user_guard Firefly III zaupa posredniškemu strežniku za overjanje, postavljenemu pred njim, kot sta Authelia ali Authentik, ki uporabnika posreduje v glavi.
• Žetoni za dostop: odjemalci OAuth in osebni žetoni API se ustvarijo v profilu.

Opravilo cron

Več funkcij deluje le z načrtovanim opravilom: samodejni proračuni, ponavljajoče se transakcije, opozorila o naročninah in posodobljeni menjalni tečaji. Slika Docker sama ne poganja cron; uradna datoteka zato doda majhno storitev cron, ki aplikacijo pokliče vsak dan ob 3. uri zjutraj.

Overi se s statičnim žetonom. Z istim ukazom ustvarite tretji niz in ga postavite v .env:

STATIC_CRON_TOKEN=

Ta žeton ima natanko 32 znakov: koda različice 6.7.9 ne sprejme nobene druge dolžine. Tukaj je storitev, kot jo določa uradna datoteka; dvojni $$ je nameren in kliče vrstici TZ in STATIC_CRON_TOKEN iz datoteke .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

Eno opravilo zadošča za vse uporabnike instance. Da preverite, ali se je izvedlo, preberite dnevnik vsebnika: vsako opravilo poroča v JSON, z job_fired in job_succeeded.

docker logs firefly_iii_cron

Če ga želite zagnati ročno, pogosta vprašanja za Docker prosijo, naj to storite kot uporabnik www-data in ne kot root: to past povezujejo z napakami dovoljenj pri dnevniških datotekah:

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

MariaDB, PostgreSQL ali SQLite

Uradna datoteka vsebuje MariaDB, s sliko mariadb:lts. Firefly III podpira tudi PostgreSQL in SQLite, ki ju izberete z DB_CONNECTION v .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

Za PostgreSQL dokumentacija storitev db preusmeri tudi na sliko postgres, ki namesti PostgreSQL 18, njen nosilec pa priklopi na /var/lib/postgresql. V .db.env spremenljivke MYSQL_* postanejo POSTGRES_USER, POSTGRES_DB in POSTGRES_PASSWORD.

To izbiro opravite, preden vnesete prve transakcije. Pogosta vprašanja navajajo, da je prehod z ene zbirke na drugo še vedno mogoč, čeprav ga Firefly III sam ne podpira, in da izvoz aplikacije ne prenese vseh podatkov.

Orodje Data Importer

Firefly III Data Importer je ločeno orodje, z lastno namestitvijo in lastnimi posodobitvami; njegova različica 2.3.5 je izšla 23. septembra 2026. Uvaža datoteke CSV in CAMT.053, transakcije pa lahko pridobi tudi iz vaših bank prek zunanjih ponudnikov podatkov, vsak s svojimi pogoji.

Uradni repozitorij Docker ga ponuja v drugi datoteki, docker-compose-importer.yml, ki ohrani iste storitve in doda importer. Njegove nastavitve gredo v datoteko .importer.env, povzeto po datoteki .env.example orodja. Strežite ga pod lastnim imenom domene, z lokalno objavljenimi vrati in drugim blokom posredniškega strežnika: pogosta vprašanja prosijo, naj ga ne postavite v podmapo.

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

• FIREFLY_III_URL: notranji naslov aplikacije, ki ga orodje doseže prek omrežja Docker.
• VANITY_URL: javni naslov programa Firefly III, tisti, ki ga poznajo vaši uporabniki.
• Odjemalec OAuth: v profilu Firefly III ustvarite odjemalca, katerega povratni URL je naslov orodja, ki mu sledi /callback, in odznačite „Confidential“. Orodje nato zahteva njegov identifikator odjemalca.
• Več uporabnikov: FIREFLY_III_ACCESS_TOKEN pustite prazen in obdržite FIREFLY_III_URL; vsak uporabnik se nato v orodje prijavi s svojim računom.

E-pošta: nastavitev SMTP

Privzeto MAIL_MAILER=log sporočila zapiše v dnevnike, namesto da bi jih poslal. Če želite prejemati obvestila, na primer opozorila o naročninah, pošiljanje nastavite v .env. Dokumentacija prosi, naj vedno spremenite MAIL_FROM in SITE_OWNER, sicer nobeno sporočilo ne odide.

Na VPS Simafri pošiljanje poteka prek overjenega releja SMTP, na vratih 587: z naslovom poštnega računa, ki ga že imate, ali s 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 sprejme null, ssl, starttls ali tls, odvisno od vašega ponudnika; koda različice 6.7.9 ob prazni vrednosti uporabi tls.
• Preizkus: stran /settings/notifications pošlje preizkusno e-pošto, ko je vsebnik znova ustvarjen.
• Drugi kanali: obvestila gredo lahko tudi v Slack, v Discord ali Mattermost pa prek njunega URL-ja spletnega kavlja, ki mu sledi /slack.

Varnostne kopije

Firefly III nima vgrajenega postopka varnostnega kopiranja: dokumentacija priporoča orodja sistema in poudarja, da funkcija izvoza v aplikaciji ni varnostna kopija. Z Dockerjem hranite naslednje:

Zbirka, med delovanjem storitve

Pri MariaDB mariadb-dump izvozi zbirko brez ustavitve storitve; njegova možnost --single-transaction da dosledno kopijo tabel InnoDB, ne da bi jih zaklenila. Ukaz, zagnan v mapi datoteke Compose, dostopne podatke prebere iz okolja vsebnika:

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

Pri PostgreSQL ista zamisel poteka prek pg_dump:

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

Ta izvoz na strežniku načrtujte vsaj enkrat na dan in med datotekami, ki se kopičijo, redno delajte red.

Nosilci, z ustavljeno storitvijo

Dokumentacija vsak nosilec arhivira z začasnim vsebnikom. Docker Compose imenom nosilcev doda predpono z imenom projekta, ki je privzeto ime mape: pred arhiviranjem preverite natančna imena.

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

Napačno zapisano ime nosilca ne sproži nobene napake: Docker pod tem imenom ustvari prazen nosilec in ga arhivira, kar prepiše prejšnjo varnostno kopijo. Dokumentacija prosi, naj pred vsakim arhiviranjem preverite, ali nosilec obstaja.

Kopijo datoteke .env in teh arhivov hranite šifrirano zunaj strežnika, saj vsebuje ključ in dostopne podatke zbirke. Postavljene na disk strežnika te datoteke vstopijo tudi v njegove nočne varnostne kopije.

Obnova

Dokumentacija nosilec obnovi z obratnim ukazom, z ustavljeno storitvijo; nosilec s priponkami se obnovi na enak način:

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

Izvoz SQL se znova naloži v delujočo zbirko:

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

Obnovite tudi .env z njegovim APP_KEY, nato znova zaženite in odprite svoje račune. Dokumentacija to ponovi po vsaki metodi: prvo, kar storite z varnostno kopijo, je obnova, da preverite, ali deluje.

Posodobitve in migracije

Firefly III se posodobi sam, tudi z različic, starih vse do 4.7, ob zagonu vsebnika pa izvede migracije svoje zbirke. Dokumentacija opozarja, da nekatere posodobitve podatke odstranijo ali počistijo, in pred vsako zahteva varnostno kopijo zbirke in nosilcev, zlasti med glavnimi različicami. V mapi datoteke Compose:

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

• Ritem: od 6.7.0 s 14. septembra 2026 do 6.7.9 z 11. oktobra 2026 je v štirih tednih izšlo deset različic. Spremljajte opombe k izdajam: od 6.7.8 okno v aplikaciji povzame glavne spremembe nameščene različice.
• Različica 6.7.0 je prinesla nov vmesnik; njen mehanizem izrazov za pravila je privzeto izklopljen in se znova vključi v /settings.
• Datoteka Compose: če jo znova prenesete, preverite različico zbirke, ki jo določa. Dokumentacija opozarja, da nova glavna različica MariaDB morda ne prevzame nosilca stare.
• Migracija, ki ni uspela: od 6.4.19 php artisan correction:rollback-single-migration odstrani zadnji vnos migracije, ne da bi se dotaknil podatkov, nato pa ga php artisan migrate znova izvede, v vsebniku.
• Podpisane izdaje: projekt svoje izdaje podpisuje, kar lahko preverite z njegovim ključem PGP.

Orodje za uvoz se po svoji dokumentaciji posodablja na enak način, z docker compose rm -f med ustavitvijo in prenosom slik.

Kdo kaj dela na Managed VPS

Samostojno gostovanje poleg aplikacije zahteva tudi vzdrževanje strežnika. Na Managed VPS naše ekipe prevzamejo strežnik in proaktivno spremljajo vašo instanco; Firefly III ostaja vaša programska oprema, z njenimi nastavitvami in vašimi finančnimi podatki.

Če želite, da naše ekipe posežejo v samo aplikacijo, se ta storitev zaračuna po urah ali pavšalno, z oceno stroškov, sporočeno pred posegom.