Хостване на Firefly III на Managed VPS: финансите ви на ваш сървър

Какво прави Firefly III

Firefly III е програма за управление на лични финанси, създадена за самостоятелно хостване. Тя следи разходите и приходите ви, с бюджети, категории и етикети, за да виждате къде отиват парите ви. README го описва като изцяло самостоятелно хостван и изолиран: той не се свързва с никакъв външен сървър, докато изрично не му кажете.

• Счетоводството: двустранно записване, сметки за активи, задължения и всяка валута, която пожелаете.
• Автоматизацията: повтарящи се транзакции и правила, които пишете, за да подреждате всяка транзакция.
• Проследяването: бюджети, касички за спестяване към цел, отчети за приходи и разходи, графики.
• Сигурността: двуфакторно удостоверяване за всеки акаунт.
• Отвореността: REST JSON API, което покрива почти цялото приложение, плюс webhooks.

Една инстанция приема колкото потребители пожелаете, всеки със своя финансова администрация, напълно отделена от останалите. Документацията описва модел за споделяне на една администрация, който в момента е в разработка.

Какво позволява лицензът AGPL

Firefly III е публикуван с GNU Affero General Public License, версия 3 или, по ваш избор, всяка по-късна версия: това е идентификаторът SPDX AGPL-3.0-or-later във файла му composer.json. Текстът потвърждава неограничено разрешение да пускате непроменената програма. Можете следователно да използвате образа, публикуван от проекта, за себе си, семейството или фирмата си, без да купувате лиценз.

Член 13 добавя условие, присъщо на AGPL: ако променяте програмата, вашата версия трябва да предложи на всеки, който я използва от разстояние, през мрежата, начин да получи безплатно нейния изходен код. Data Importer е със същия лиценз.

Инсталиране с Docker Compose

Документацията нарича Docker Compose най-лесния начин да инсталирате Firefly III. На сървър с инсталиран Docker създайте папка и изтеглете в нея трите официални файла в суров вид: отстъпите в тях имат значение, а документацията моли да не ги копирате от браузъра.

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 описва три услуги: app, приложението, db, база данни MariaDB, и cron, планираната задача.
• .env съдържа настройките на Firefly III, сред които ключа за шифроване и достъпа до базата.
• .db.env съдържа настройките на базата данни. Запазете и двете имена: файлът Compose ги посочва чрез env_file.

Настройките, които се сменят преди първото стартиране

Генерирайте два низа от по 32 знака с командата, дадена във файла .env: един за ключа и един за паролата на базата.

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 шифрова сесиите ви. Той е дълъг точно 32 знака, без специални знаци като =, #, < или >, а файлът моли да го пазите много грижливо.
• DB_PASSWORD в .env и MYSQL_PASSWORD в .db.env получават една и съща стойност.
• SITE_OWNER: вашият адрес, показван в някои грешки на потребителите, които не са администратори.
• APP_URL: публичният адрес на инстанцията ви. Файлът обяснява, че той служи за проверка на някои заявки и за изграждане на връзките в имейлите.
• TZ: вашата часова зона, във формата на базата tz, както показва примерът във файла.

Изберете паролата на базата данни преди първото стартиране. Базата я записва в своя том още при създаването си: сменете ли я след това, тя вече не съвпада, а Docker FAQ предлага само един изход, да изтриете контейнерите и томовете и да започнете отначало.

Порт, публикуван локално

Официалният файл публикува приложението на порт 80 на всички адреси на сървъра. За да го предоставите през HTTPS зад обратен прокси на същата машина, сменете само този ред в услугата 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

При първото стартиране контейнерът сам създава и мигрира базата данни. Когато инсталирането приключи, Firefly III ви благодари в журнала, че сте го инсталирали: преминете към обратния прокси.

• Етикетът latest следва последната стабилна версия. Етикет като version-6.7.9 фиксира версия; проектът премахва старите след около шест месеца.
• Архитектурите: образите се изграждат за linux/amd64 и linux/arm64.
• Томовете: firefly_iii_upload пази прикачените файлове, firefly_iii_db базата данни.

Документацията не дава число за паметта; нейният Docker FAQ предлага PHP_MEMORY_LIMIT=512M или повече, ако на PHP не му стига памет. Размерът зависи от броя на потребителите, от обема на транзакциите и от импортирането на данни. На Managed VPS ни опишете как го използвате и ще ви препоръчаме подходящия размер.

HTTPS и обратният прокси

Firefly III предоставя приложението през HTTP на порт 8080 в контейнера, а HTTPS се поема от обратния прокси пред него. Приложението чете заглавката X-Forwarded-Proto, за да знае, че посетителят е дошъл през HTTPS, стига да има доверие на проксито:

TRUSTED_PROXIES=*

Docker FAQ е категоричен по този въпрос: без TRUSTED_PROXIES=* връзките остават на http, формулярите и графиките спират да работят, а защитните заглавки CSP не минават. С порт, публикуван на 127.0.0.1, само проксито на самия сървър достига до приложението. Създавайте контейнера наново след всяка промяна във файла .env:

docker compose up -d --force-recreate app

С Caddy

Caddy сам получава сертификата Let’s Encrypt, а директивата му reverse_proxy поставя по подразбиране заглавките X-Forwarded-For, X-Forwarded-Proto и X-Forwarded-Host:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

С Nginx и Certbot

Този блок следва заглавките от FAQ за инсталирането и буферите, които той предлага срещу грешките 502, когато приложението връща токен в дълга заглавка. Той слуша на порт 80, за да остави на Certbot да постави 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 поставя сертификата и се грижи да го подновява:

sudo certbot --nginx

• Собствено име на домейн: предоставяйте Firefly III на отделно име, като finances.example.com. FAQ отбелязва, че Laravel не разчита суров IPv6 адрес в URL адреса.
• Грешките 431: FAQ ги свързва с твърде малко ограничение за размера на заглавките в проксито, заради което някои действия, като влизането, не успяват.

Първият акаунт и регистрациите

Първият регистриран потребител става собственик на инстанцията. От съображения за сигурност регистрациите след това се затварят сами: повечето хора инсталират Firefly III само за себе си.

1. Отворете своя HTTPS адрес веднага щом проксито отговори и създайте акаунта си: той получава ролята на собственик.
2. Включете двуфакторното удостоверяване в профила си и запазете осемте резервни кода, които то показва.
3. За да отворите инстанцията за други хора, отидете в /settings, отворете опциите за конфигуриране на Firefly III, махнете отметката от опцията, която изключва регистрациите, и запишете.

• Двуфакторното удостоверяване разчита на часовника: FAQ посочва, че разлика във времето между телефона и сървъра го проваля.
• Влизане през вашия доставчик на идентичност: с AUTHENTICATION_GUARD=remote_user_guard Firefly III се доверява на прокси за удостоверяване, поставен пред него, като Authelia или Authentik, който предава потребителя в заглавка.
• Токените за достъп: клиентите OAuth и личните API токени се създават от профила.

Cron задачата

Няколко функции работят само с планирана задача: автоматичните бюджети, повтарящите се транзакции, предупрежденията за абонаменти и актуалните валутни курсове. Docker образът не пуска cron сам; официалният файл добавя за целта малка услуга cron, която извиква приложението всеки ден в 3 часа сутринта.

Тя се удостоверява със статичен токен. Генерирайте трети низ със същата команда и го поставете в .env:

STATIC_CRON_TOKEN=

Този токен е дълъг точно 32 знака: кодът на версия 6.7.9 не приема друга дължина. Ето услугата така, както я декларира официалният файл; двойното $$ е нарочно и сочи към редовете TZ и STATIC_CRON_TOKEN на файла .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

Една задача стига за всички потребители на инстанцията. За да проверите, че се е изпълнила, прочетете журнала на контейнера: всяка задача докладва в JSON, с job_fired и job_succeeded.

docker logs firefly_iii_cron

За да я пуснете ръчно, Docker FAQ моли да минете през потребителя www-data, а не през root: FAQ свързва този капан с грешки в правата върху журналните файлове:

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

MariaDB, PostgreSQL или SQLite

Официалният файл доставя MariaDB, с образа mariadb:lts. Firefly III поддържа също PostgreSQL и SQLite, които се избират с DB_CONNECTION в .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

За PostgreSQL документацията насочва и услугата db към образа postgres, който инсталира PostgreSQL 18, и монтира тома ѝ на /var/lib/postgresql. В .db.env променливите MYSQL_* стават POSTGRES_USER, POSTGRES_DB и POSTGRES_PASSWORD.

Направете този избор, преди да въведете първите си транзакции. FAQ посочва, че преминаването от една база към друга остава възможно, без да се поддържа от самия Firefly III, и че експортът на приложението не пренася всички данни.

Data Importer

Firefly III Data Importer е отделен инструмент, със собствено инсталиране и собствени обновления; версията му 2.3.5 излезе на 23 септември 2026 г. Той импортира файлове CSV и CAMT.053 и може също да изтегля транзакциите от банките ви чрез доставчици на данни от трети страни, всеки със свои условия.

Официалното Docker хранилище го доставя във втори файл, docker-compose-importer.yml, който запазва същите услуги и добавя importer. Настройките му отиват във файл .importer.env, взет от .env.example на импортера. Предоставяйте го на собствено име на домейн, с порт, публикуван локално, и втори блок в проксито: FAQ моли да не го поставяте в поддиректория.

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

• FIREFLY_III_URL: вътрешният адрес на приложението, до който импортерът стига през мрежата на Docker.
• VANITY_URL: публичният адрес на Firefly III, този, който потребителите ви познават.
• Клиентът OAuth: в профила си във Firefly III създайте клиент, чийто адрес за обратно извикване е адресът на импортера, последван от /callback, и махнете отметката „Confidential“. После импортерът иска неговия идентификатор на клиент.
• Няколко потребители: оставете FIREFLY_III_ACCESS_TOKEN празно и запазете FIREFLY_III_URL; тогава всеки потребител влиза в импортера със собствения си акаунт.

Имейлите: SMTP конфигурацията

По подразбиране MAIL_MAILER=log записва съобщенията в журналите, вместо да ги изпраща. За да получавате известията, като предупрежденията за абонаменти, настройте изпращането в .env. Документацията моли винаги да сменяте MAIL_FROM и SITE_OWNER, иначе нито един имейл няма да излезе.

На VPS на Simafri изпращането минава през удостоверено SMTP реле, на порт 587: адресът на пощенски акаунт, който вече имате, или 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 приема null, ssl, starttls или tls, според доставчика ви; кодът на версия 6.7.9 преминава към tls, когато стойността е празна.
• Изпитването: страницата /settings/notifications изпраща тестов имейл, след като контейнерът е създаден наново.
• Други канали: известията могат да отиват и в Slack, както и в Discord или Mattermost чрез техния webhook адрес, последван от /slack.

Резервните копия

Firefly III няма вградена процедура за архивиране: документацията препоръчва инструментите на самата система и посочва, че функцията за експорт на приложението не е резервно копие. С Docker ето какво трябва да пазите:

Базата, при работеща услуга

С MariaDB mariadb-dump експортира базата, без да спира услугата; опцията му --single-transaction дава съгласувано копие на таблиците InnoDB, без да ги заключва. Изпълнена от папката на файла Compose, командата чете данните за достъп от средата на контейнера:

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

С PostgreSQL същата идея минава през pg_dump:

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

Планирайте този експорт на сървъра поне веднъж дневно и подреждайте файловете, които се трупат.

Томовете, при спряна услуга

Документацията архивира всеки том с временен контейнер. Docker Compose добавя пред имената на томовете името на проекта, което по подразбиране е името на папката: проверете точните имена, преди да пуснете архивирането.

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

Грешно изписано име на том не предизвиква никаква грешка: Docker създава празен том с това име и го архивира, което презаписва предишното резервно копие. Документацията моли да проверявате, че томът съществува, преди всяко архивиране.

Пазете копие на .env и на тези архиви извън сървъра, шифровано, защото то носи ключа и данните за достъп до базата. Поставени на диска на сървъра, тези файлове влизат и в нощните му резервни копия.

Възстановяване

Документацията възстановява том с обратната команда, при спряна услуга; томът с прикачените файлове се възстановява по същия начин:

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

SQL експорт се зарежда обратно в работещата база:

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

Възстановете и .env с неговия APP_KEY, после стартирайте отново и отворете сметките си. Документацията го повтаря след всеки метод: първото, което се прави с резервно копие, е да се възстанови, за да се провери, че работи.

Обновленията и миграциите

Firefly III се обновява сам, дори от версии толкова стари като 4.7, и мигрира базата си при стартирането на контейнера. Документацията предупреждава, че някои обновления премахват или почистват данни, и иска резервно копие на базата и на томовете преди всяко от тях, особено при смяна на основна версия. От папката на файла Compose:

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

• Темпото: от 6.7.0 на 14 септември 2026 г. до 6.7.9 на 11 октомври 2026 г. излязоха десет версии за четири седмици. Следете бележките към версиите: от 6.7.8 прозорец в приложението обобщава основните промени на инсталираната версия.
• Версия 6.7.0 донесе нов интерфейс; нейният механизъм за изрази в правилата е изключен по подразбиране и се включва отново в /settings.
• Файлът Compose: ако го изтеглите отново, проверете версията на базата, която той декларира. Документацията предупреждава, че нова основна версия на MariaDB може да не поеме тома на старата.
• Миграция, която не е минала: от 6.4.19 php artisan correction:rollback-single-migration премахва записа за последната миграция, без да докосва данните, после php artisan migrate я изпълнява отново, в контейнера.
• Подписаните версии: проектът подписва версиите си, което можете да проверите с неговия PGP ключ.

Импортерът се обновява по същия начин, с docker compose rm -f между спирането и изтеглянето на образите, според документацията му.

Кой какво прави на Managed VPS

Самостоятелното хостване изисква да поддържате сървъра освен приложението. На Managed VPS нашите екипи поемат сървъра и следят проактивно вашата инстанция; Firefly III остава ваш софтуер, с неговите настройки и вашите финансови данни.

Ако предпочитате нашите екипи да се намесват в самото приложение, тази услуга се фактурира на час или на фиксирана цена, с оферта, съобщена преди намесата.