Hosting Firefly III na Managed VPS: Państwa finanse na Państwa serwerze

Co robi Firefly III

Firefly III to menedżer finansów osobistych przeznaczony do samodzielnego hostingu. Śledzi wydatki i przychody, z budżetami, kategoriami i tagami, aby było widać, dokąd idą Państwa pieniądze. README opisuje go jako w pełni samodzielnie hostowany i odizolowany: nie kontaktuje się z żadnym zewnętrznym serwerem, dopóki wyraźnie mu Państwo tego nie polecą.

• Księgowość: zapis podwójny, konta aktywów, zobowiązania i dowolna waluta.
• Automatyzacja: transakcje cykliczne oraz reguły, które Państwo sami piszą, aby przyporządkować każdą transakcję.
• Śledzenie: budżety, skarbonki do oszczędzania na wybrany cel, raporty przychodów i wydatków, wykresy.
• Bezpieczeństwo: uwierzytelnianie dwuskładnikowe dla każdego konta.
• Otwartość: REST JSON API obejmujące niemal całą aplikację, a do tego webhooki.

Jedna instancja obsługuje dowolną liczbę użytkowników, a każdy z nich prowadzi administrację finansową całkowicie oddzieloną od pozostałych. Dokumentacja zapowiada model współdzielenia jednej administracji, który jest obecnie w przygotowaniu.

Na co pozwala licencja AGPL

Firefly III jest udostępniany na GNU Affero General Public License, w wersji 3 lub, według Państwa wyboru, dowolnej późniejszej: tak brzmi identyfikator SPDX AGPL-3.0-or-later w jego pliku composer.json. Tekst potwierdza nieograniczone prawo do uruchamiania niezmodyfikowanego programu. Mogą więc Państwo używać obrazu opublikowanego przez projekt dla siebie, rodziny lub firmy, bez zakupu licencji.

Artykuł 13 dodaje warunek właściwy dla AGPL: jeśli Państwo zmodyfikują program, Państwa wersja musi oferować każdemu, kto korzysta z niej zdalnie, przez sieć, możliwość bezpłatnego uzyskania jej kodu źródłowego. Importer danych jest udostępniany na tej samej licencji.

Instalacja przez Docker Compose

Dokumentacja nazywa Docker Compose najprostszym sposobem instalacji Firefly III. Na serwerze z zainstalowanym Dockerem proszę utworzyć katalog i pobrać do niego trzy oficjalne pliki w surowej postaci: liczą się w nich odstępy, a dokumentacja prosi, by nie kopiować ich z przeglądarki.

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 trzy usługi: app, czyli aplikację, db, czyli bazę MariaDB, oraz cron, czyli zadanie cykliczne.
• .env zawiera ustawienia Firefly III, w tym klucz szyfrowania i dostęp do bazy.
• .db.env zawiera ustawienia bazy. Proszę zachować obie nazwy: plik Compose odwołuje się do nich przez env_file.

Ustawienia do zmiany przed pierwszym uruchomieniem

Proszę wygenerować dwa ciągi po 32 znaki poleceniem podanym w pliku .env: jeden na klucz, drugi na hasło do bazy.

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 szyfruje sesje. Ma dokładnie 32 znaki, bez znaków specjalnych takich jak =, #, < czy >, a plik prosi, by strzec go bardzo starannie.
• DB_PASSWORD w .env i MYSQL_PASSWORD w .db.env przyjmują tę samą wartość.
• SITE_OWNER: Państwa adres, wyświetlany w niektórych komunikatach o błędach użytkownikom, którzy nie są administratorami.
• APP_URL: publiczny adres Państwa instancji. Plik wyjaśnia, że służy on do weryfikacji niektórych żądań i do budowania linków w e-mailach.
• TZ: Państwa strefa czasowa, w formacie bazy tz, jak pokazuje przykład w pliku.

Hasło do bazy proszę wybrać przed pierwszym uruchomieniem. Baza zapisuje je w swoim woluminie od chwili utworzenia: zmienione później przestaje się zgadzać, a FAQ Dockera podaje tylko jedno wyjście, czyli usunięcie kontenerów i woluminów i rozpoczęcie od nowa.

Port opublikowany lokalnie

Oficjalny plik publikuje aplikację na porcie 80 wszystkich adresów serwera. Aby udostępnić ją przez HTTPS za odwrotnym proxy na tej samej maszynie, proszę zmienić ten jeden wiersz w usłudze 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

Przy pierwszym uruchomieniu kontener sam tworzy bazę i wykonuje jej migracje. Gdy instalacja dobiegnie końca, Firefly III dziękuje w dzienniku za jej wykonanie: wtedy proszę przejść do odwrotnego proxy.

• Tag latest podąża za ostatnią stabilną wersją. Tag taki jak version-6.7.9 przypina wersję; projekt usuwa stare tagi po około sześciu miesiącach.
• Architektury: obrazy są budowane dla linux/amd64 i linux/arm64.
• Woluminy: firefly_iii_upload przechowuje załączniki, a firefly_iii_db bazę danych.

Dokumentacja nie podaje wymagań dotyczących pamięci; FAQ Dockera sugeruje PHP_MEMORY_LIMIT=512M lub więcej, jeśli PHP zabraknie pamięci. Rozmiar zależy od liczby użytkowników, liczby transakcji i importera danych. Na Managed VPS wystarczy opisać nam swoje zastosowanie, a polecimy odpowiedni rozmiar.

HTTPS i odwrotne proxy

Firefly III udostępnia aplikację przez HTTP na porcie 8080 wewnątrz kontenera, a HTTPS zapewnia odwrotne proxy umieszczone przed nim. Aplikacja odczytuje nagłówek X-Forwarded-Proto, aby wiedzieć, że odwiedzający przyszedł przez HTTPS, pod warunkiem że ufa proxy:

TRUSTED_PROXIES=*

FAQ Dockera jest w tej kwestii jednoznaczne: bez TRUSTED_PROXIES=* linki pozostają w http, formularze i wykresy przestają działać, a nagłówki bezpieczeństwa CSP zawodzą. Przy porcie opublikowanym na 127.0.0.1 do aplikacji dociera wyłącznie proxy samego serwera. Po każdej zmianie pliku .env proszę utworzyć kontener na nowo:

docker compose up -d --force-recreate app

Z Caddy

Caddy sam uzyskuje certyfikat Let’s Encrypt, a jego dyrektywa reverse_proxy domyślnie ustawia nagłówki X-Forwarded-For, X-Forwarded-Proto i X-Forwarded-Host:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Z Nginx i Certbotem

Ten blok stosuje nagłówki z FAQ instalacji oraz bufory, które FAQ proponuje przeciw błędom 502, gdy aplikacja zwraca token w długim nagłówku. Nasłuchuje na porcie 80, aby Certbot mógł zainstalować 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 następnie instaluje certyfikat i zajmuje się jego odnawianiem:

sudo certbot --nginx

• Własna nazwa domeny: proszę udostępnić Firefly III pod osobną nazwą, taką jak finances.example.com. FAQ zaznacza, że Laravel nie odczytuje surowego adresu IPv6 w URL.
• Błędy 431: FAQ wiąże je ze zbyt małym limitem rozmiaru nagłówków na proxy, przez który niektóre działania kończą się niepowodzeniem, na przykład logowanie.

Pierwsze konto i rejestracja

Pierwszy użytkownik, który się zarejestruje, zostaje właścicielem instancji. Ze względów bezpieczeństwa rejestracja zamyka się wtedy sama: większość osób instaluje Firefly III wyłącznie dla siebie.

1. Proszę otworzyć swój adres HTTPS, gdy tylko proxy odpowiada, i utworzyć konto: otrzymuje ono rolę właściciela.
2. Proszę włączyć uwierzytelnianie dwuskładnikowe w swoim profilu i zachować osiem wyświetlonych kodów zapasowych.
3. Aby otworzyć instancję dla innych osób, proszę przejść do /settings, otworzyć opcje konfiguracji Firefly III, odznaczyć opcję wyłączającą rejestrację i zapisać.

• Uwierzytelnianie dwuskładnikowe opiera się na zegarze: FAQ podaje, że różnica czasu między telefonem a serwerem uniemożliwia logowanie.
• Logowanie przez dostawcę tożsamości: przy AUTHENTICATION_GUARD=remote_user_guard Firefly III ufa umieszczonemu przed nim proxy uwierzytelniającemu, takiemu jak Authelia czy Authentik, które przekazuje użytkownika w nagłówku.
• Tokeny dostępu: klientów OAuth i osobiste tokeny API tworzy się z poziomu profilu.

Zadanie cron

Kilka funkcji działa tylko z zadaniem cyklicznym: automatyczne budżety, transakcje cykliczne, ostrzeżenia o subskrypcjach i aktualne kursy walut. Obraz Docker sam nie uruchamia crona; oficjalny plik dodaje w tym celu niewielką usługę cron, która wywołuje aplikację codziennie o 3:00.

Uwierzytelnia się ona statycznym tokenem. Proszę wygenerować trzeci ciąg tym samym poleceniem i umieścić go w .env:

STATIC_CRON_TOKEN=

Ten token ma dokładnie 32 znaki: kod wersji 6.7.9 nie przyjmuje innej długości. Oto usługa w postaci, w jakiej deklaruje ją oficjalny plik; podwójne $$ jest zamierzone i odwołuje się do wierszy TZ i STATIC_CRON_TOKEN pliku .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

Jedno zadanie wystarcza dla wszystkich użytkowników instancji. Aby sprawdzić, czy zostało wykonane, proszę przeczytać dziennik kontenera: każde zadanie zdaje w nim sprawozdanie w formacie JSON, z polami job_fired i job_succeeded.

docker logs firefly_iii_cron

Aby uruchomić je ręcznie, FAQ Dockera prosi o użycie użytkownika www-data zamiast root: FAQ wiąże tę pułapkę z błędami uprawnień do plików dziennika:

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

MariaDB, PostgreSQL czy SQLite

Oficjalny plik dostarcza MariaDB, z obrazem mariadb:lts. Firefly III obsługuje też PostgreSQL i SQLite, wybierane przez DB_CONNECTION w .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

Dla PostgreSQL dokumentacja kieruje też usługę db na obraz postgres, który instaluje PostgreSQL 18, i montuje jej wolumin w /var/lib/postgresql. W .db.env zmienne MYSQL_* ustępują miejsca POSTGRES_USER, POSTGRES_DB i POSTGRES_PASSWORD.

Wyboru proszę dokonać przed wprowadzeniem pierwszych transakcji. FAQ podaje, że przejście z jednej bazy na inną pozostaje możliwe, choć sam Firefly III go nie wspiera, a eksport aplikacji nie przenosi wszystkich danych.

Importer danych

Firefly III Data Importer to osobne narzędzie, z własną instalacją i własnymi aktualizacjami; jego wersja 2.3.5 ukazała się 23 września 2026 roku. Importuje pliki CSV i CAMT.053, a także potrafi pobierać transakcje z Państwa banków przez zewnętrznych dostawców danych, z których każdy ma własne warunki.

Oficjalne repozytorium Docker dostarcza go w drugim pliku, docker-compose-importer.yml, który zachowuje te same usługi i dodaje importer. Jego ustawienia trafiają do pliku .importer.env, utworzonego na podstawie .env.example importera. Proszę udostępnić go pod własną nazwą domeny, z portem opublikowanym lokalnie i drugim blokiem proxy: FAQ prosi, by nie umieszczać go w podkatalogu.

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

• FIREFLY_III_URL: wewnętrzny adres aplikacji, do którego importer dociera przez sieć Dockera.
• VANITY_URL: publiczny adres Firefly III, ten, który znają Państwa użytkownicy.
• Klient OAuth: w swoim profilu Firefly III proszę utworzyć klienta, którego adres zwrotny to adres importera z dopiskiem /callback, i odznaczyć „Confidential”. Importer poprosi następnie o identyfikator tego klienta.
• Kilku użytkowników: proszę zostawić FIREFLY_III_ACCESS_TOKEN puste i zachować FIREFLY_III_URL; każdy użytkownik loguje się wtedy do importera własnym kontem.

E-maile: konfiguracja SMTP

Domyślnie MAIL_MAILER=log zapisuje wiadomości w dziennikach zamiast je wysyłać. Aby otrzymywać powiadomienia, na przykład ostrzeżenia o subskrypcjach, proszę skonfigurować wysyłkę w .env. Dokumentacja prosi, by zawsze zmienić MAIL_FROM i SITE_OWNER, w przeciwnym razie żaden e-mail nigdy nie wyjdzie.

Na VPS Simafri wysyłka odbywa się przez uwierzytelniony przekaźnik SMTP, na porcie 587: adres posiadanego już konta pocztowego albo 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 przyjmuje null, ssl, starttls lub tls, zależnie od dostawcy; przy pustej wartości kod wersji 6.7.9 przyjmuje tls.
• Próba: strona /settings/notifications wysyła testowego e-maila, gdy kontener zostanie utworzony na nowo.
• Inne kanały: powiadomienia mogą też trafiać do Slacka, a także do Discorda lub Mattermosta przez ich adres webhooka z dopiskiem /slack.

Kopie zapasowe

Firefly III nie ma wbudowanej procedury kopii zapasowych: dokumentacja zaleca narzędzia samego systemu i zaznacza, że funkcja eksportu aplikacji nie jest kopią zapasową. Przy Dockerze należy zachować następujące elementy:

Baza, przy działającej usłudze

Przy MariaDB mariadb-dump eksportuje bazę bez zatrzymywania usługi; jego opcja --single-transaction daje spójną kopię tabel InnoDB bez ich blokowania. Uruchomione z katalogu pliku Compose, polecenie odczytuje dane dostępowe ze środowiska kontenera:

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

Przy PostgreSQL ta sama metoda działa przez pg_dump:

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

Proszę zaplanować ten zrzut na serwerze co najmniej raz dziennie i porządkować pliki, które się gromadzą.

Woluminy, przy zatrzymanej usłudze

Dokumentacja archiwizuje każdy wolumin za pomocą jednorazowego kontenera. Docker Compose poprzedza nazwy woluminów nazwą projektu, którą domyślnie jest nazwa katalogu: przed uruchomieniem archiwizacji proszę sprawdzić dokładne nazwy.

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

Błędnie wpisana nazwa woluminu nie wywołuje żadnego błędu: Docker tworzy pod tą nazwą pusty wolumin i go archiwizuje, co nadpisuje poprzednią kopię. Dokumentacja prosi, by przed każdą archiwizacją sprawdzić, czy wolumin istnieje.

Kopię .env i tych archiwów proszę przechowywać poza serwerem, w postaci szyfrowanej, ponieważ zawiera klucz i dane dostępowe do bazy. Umieszczone na dysku serwera, pliki te trafiają także do jego nocnych kopii zapasowych.

Przywracanie

Dokumentacja przywraca wolumin odwrotnym poleceniem, przy zatrzymanej usłudze; wolumin z załącznikami przywraca się w ten sam sposób:

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

Zrzut SQL wczytuje się z powrotem do działającej bazy:

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

Proszę przywrócić także .env wraz z jego APP_KEY, a następnie uruchomić ponownie i otworzyć swoje konta. Dokumentacja powtarza to po każdej metodzie: kopię zapasową należy najpierw przywrócić, aby sprawdzić, że działa.

Aktualizacje i migracje

Firefly III aktualizuje się sam, nawet z wersji tak dawnych jak 4.7, i wykonuje migracje bazy przy starcie kontenera. Dokumentacja ostrzega, że niektóre aktualizacje usuwają lub porządkują dane, i prosi o kopię bazy i woluminów przed każdą z nich, zwłaszcza między wersjami głównymi. Z katalogu pliku Compose:

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

• Tempo: od wersji 6.7.0 z 14 września 2026 roku do 6.7.9 z 11 października 2026 roku ukazało się dziesięć wersji w cztery tygodnie. Proszę śledzić informacje o wydaniach: od wersji 6.7.8 okno w aplikacji podsumowuje główne zmiany zainstalowanej wersji.
• Wersja 6.7.0 przyniosła nowy interfejs; jej silnik wyrażeń reguł jest domyślnie wyłączony i włącza się go ponownie w /settings.
• Plik Compose: jeśli pobierają go Państwo ponownie, proszę sprawdzić wersję bazy, którą deklaruje. Dokumentacja ostrzega, że nowa wersja główna MariaDB może nie odczytać woluminu poprzedniej.
• Migracja, która się nie powiodła: od wersji 6.4.19 php artisan correction:rollback-single-migration usuwa ostatni wpis migracji bez naruszania danych, a następnie php artisan migrate wykonuje ją ponownie, wewnątrz kontenera.
• Podpisane wydania: projekt podpisuje swoje wydania, co można zweryfikować jego kluczem PGP.

Importer aktualizuje się w ten sam sposób, z docker compose rm -f między zatrzymaniem a pobraniem obrazów, zgodnie z jego dokumentacją.

Kto za co odpowiada na Managed VPS

Samodzielny hosting wymaga prowadzenia serwera, oprócz samej aplikacji. Na Managed VPS nasze zespoły przejmują serwer i proaktywnie czuwają nad Państwa instancją; Firefly III pozostaje Państwa oprogramowaniem, z jego ustawieniami i Państwa danymi finansowymi.

Jeśli wolą Państwo, aby nasze zespoły interweniowały w samej aplikacji, usługa ta jest rozliczana godzinowo lub ryczałtowo, z wyceną przekazaną przed interwencją.