Firefly III на Ubuntu 24.04: пошаговая установка

MAATRIX

Учёт личных финансов в блокнотах и таблицах рано или поздно превращается в хаос, а облачные сервисы вроде YNAB или Monefy требуют доверить историю трат чужому серверу — и часто не работают с российскими картами. Firefly III снимает оба вопроса: это open-source менеджер бюджета, который вы разворачиваете на собственном VPS и держите все данные при себе. Ниже — пошаговая установка на чистой Ubuntu 24.04 через Docker Compose, с базой данных, HTTPS и первыми шагами настройки.

Что такое Firefly III и зачем свой сервер

Firefly III — PHP-приложение для учёта личных и семейных финансов: счета, категории, бюджеты, теги, повторяющиеся транзакции, импорт выписок из банков (CSV и через сторонние коннекторы), отчёты и графики по периодам. Проект живёт на GitHub с 2015 года, активно развивается и распространяется бесплатно под AGPL-лицензией.

Ключевое отличие от облачных аналогов — данные не покидают ваш сервер. Это важно по двум причинам:

• Финансовая история — чувствительные данные, и вы сами решаете, где они хранятся и кто имеет к ним доступ.
• Отсутствует зависимость от иностранного биллинга: сервис не спросит международную карту, потому что его вообще нет — есть только ваш VPS.

Для self-hosted версии Firefly III нужен постоянно работающий сервер с PHP, веб-сервером и базой данных. Проще всего поднять всё это через Docker Compose — так вы получите готовое окружение без ручной настройки PHP-FPM и зависимостей.

Минимальные требования: 1 vCPU, 1 ГБ RAM хватает для личного использования одним-двумя пользователями; для семьи с активным импортом выписок и историей за несколько лет комфортнее будет 2 ГБ RAM. Диск — от 10 ГБ, с запасом под бэкапы базы.

Подготовка сервера

Понадобится VPS с Ubuntu 24.04, доступ по SSH под пользователем с правами sudo, и домен (или поддомен), направленный на IP сервера — Firefly III удобнее и безопаснее эксплуатировать по HTTPS, а не по голому IP.

Обновите систему и поставьте базовые утилиты:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git ufw

Настройте файрвол — откройте только SSH и веб-порты:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Если хотите разобрать тонкости UFW отдельно — есть подробный разбор настройки файрвола на Ubuntu 24.04.

Установите Docker Engine и плагин Compose по официальному репозиторию Docker (это надёжнее версии из apt-репозиториев Ubuntu, которая часто отстаёт):

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

После этой команды перелогиньтесь (или выполните newgrp docker), чтобы группа docker применилась без sudo на каждую команду.

Структура проекта и переменные окружения

Создайте рабочую директорию и файл с переменными для базы данных и самого приложения:

mkdir -p ~/firefly-iii && cd ~/firefly-iii

Сгенерируйте случайный APP_KEY — 32-байтовую строку в base64, которую Firefly III использует для шифрования сессий и части данных:

echo "base64:$(openssl rand -base64 32)"

Сохраните результат — он понадобится в .env. Создайте файл .env:

cat > .env <<'EOF'
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:ВСТАВЬТЕ_СГЕНЕРИРОВАННЫЙ_КЛЮЧ_СЮДА
APP_URL=https://finance.example.com
TRUSTED_PROXIES=**

DB_CONNECTION=mysql
DB_HOST=firefly_db
DB_PORT=3306
DB_DATABASE=firefly
DB_USERNAME=firefly
DB_PASSWORD=замените_на_сложный_пароль

MYSQL_RANDOM_ROOT_PASSWORD=yes
MYSQL_DATABASE=firefly
MYSQL_USER=firefly
MYSQL_PASSWORD=замените_на_сложный_пароль

DEFAULT_LANGUAGE=ru
DEFAULT_LOCALE=ru_RU
TZ=Europe/Moscow
EOF

Замените APP_URL на реальный домен и оба пароля — на длинные случайные строки (например, openssl rand -base64 24 для каждого). Пароли DB_PASSWORD и MYSQL_PASSWORD должны совпадать — это один и тот же пользователь MySQL.

Если хотите вести отдельный лог логики импорта выписок, Firefly III официально поддерживает и PostgreSQL — конфигурация аналогична, меняются только переменные DB_CONNECTION=pgsql и образ базы. Для большинства личных сценариев MySQL/MariaDB достаточно и проще в бэкапе; общий подход к установке MariaDB на сервер разобран в статье про установку MariaDB на Ubuntu 24.04.

docker-compose.yml: приложение и база данных

Создайте docker-compose.yml в той же директории:

services:
  firefly_app:
    image: fireflyiii/core:latest
    container_name: firefly_app
    restart: unless-stopped
    volumes:
      - firefly_upload:/var/www/html/storage/upload
    env_file: .env
    ports:
      - "127.0.0.1:8080:8080"
    depends_on:
      - firefly_db

  firefly_db:
    image: mariadb:11
    container_name: firefly_db
    restart: unless-stopped
    environment:
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
      - MYSQL_DATABASE=firefly
      - MYSQL_USER=firefly
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - firefly_db_data:/var/lib/mysql
    env_file: .env

  firefly_cron:
    image: alpine:3.20
    container_name: firefly_cron
    restart: unless-stopped
    entrypoint: |
      /bin/sh -c "
      apk add --no-cache curl >/dev/null;
      while true; do
        sleep 86400;
        curl -s -X POST http://firefly_app:8080/api/v1/cron/ЗАМЕНИТЕ_НА_STATIC_CRON_TOKEN;
      done"
    depends_on:
      - firefly_app

volumes:
  firefly_upload:
  firefly_db_data:

Обратите внимание: приложение слушает 127.0.0.1:8080 — наружу оно не торчит, доступ будет только через обратный прокси на этом же сервере. Это стандартная и более безопасная схема, чем открывать порт приложения напрямую в интернет.

Контейнер firefly_cron — упрощённая замена системному cron-заданию, которое Firefly III использует для повторяющихся транзакций и напоминаний о счетах. Токен STATIC_CRON_TOKEN задайте в .env (любая строка из 32 символов) и подставьте тот же токен в URL контейнера cron:

echo "STATIC_CRON_TOKEN=$(openssl rand -hex 16)" >> .env

Запустите стек:

docker compose up -d
docker compose logs -f firefly_app

Первый запуск выполняет миграции базы — дождитесь в логе строки о завершении миграций (обычно 30–60 секунд), затем прервите просмотр логов через Ctrl+C.

Обратный прокси и HTTPS

Приложение слушает локальный порт, значит нужен веб-сервер снаружи. Проще всего поставить Nginx и Certbot напрямую на хост:

sudo apt install -y nginx

Создайте конфиг /etc/nginx/sites-available/firefly:

server {
    listen 80;
    server_name finance.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 32m;
    }
}

Активируйте сайт и перезапустите Nginx:

sudo ln -s /etc/nginx/sites-available/firefly /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Получите сертификат Let's Encrypt:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d finance.example.com

Certbot сам пропишет редирект на HTTPS и настроит автопродление. Если по пути возникнут ошибки валидации домена — там же на блоге есть разбор частых причин, почему не проходит валидация Let's Encrypt. Общая логика выбора между Certbot и acme.sh для таких задач разобрана в статье Certbot или acme.sh — что выбрать.

client_max_body_size 32m важен, если вы планируете загружать в Firefly III банковские выписки в CSV или PDF-квитанции — по умолчанию Nginx режет тело запроса на 1 МБ.

Первый запуск и настройка учётной записи

Откройте https://finance.example.com — Firefly III покажет мастер регистрации первого администратора. Заполните email и пароль (это локальная учётная запись, никуда не отправляется). После входа:

1. Создайте счета (Accounts → Asset accounts) — банковская карта, наличные, накопительный счёт. Для каждого счёта укажите валюту и начальный баланс.
2. Настройте валюту по умолчанию в Options → Currencies, если работаете не только в рублях — Firefly III поддерживает мультивалютный учёт с ручным или API-курсом конвертации.
3. Заведите категории и бюджеты (Budgets → Create budget) — например, «Продукты», «Транспорт», «Подписки», с лимитом на месяц. Firefly III покажет прогресс-бар расхода бюджета в реальном времени.
4. Настройте повторяющиеся транзакции (Recurring transactions) для регулярных платежей — аренда, подписки, зарплата. Именно их обрабатывает cron-контейнер раз в сутки.

Для импорта выписок из банка Firefly III поддерживает CSV-импорт через встроенный мастер (Import data → CSV file) с гибким маппингом колонок — подходит для любого банка, который выгружает историю операций в CSV. Для части банков есть более специализированные коннекторы (Nordigen/GoCardless, Spectre), но для российских банков практичнее всего именно ручной CSV-импорт с настройкой шаблона один раз.

Бэкапы: не потерять историю финансов

В отличие от статического сайта, потеря базы Firefly III — это потеря истории транзакций за годы, которую не восстановить. Бэкап нужен с первого дня.

Простой скрипт дампа базы данных из контейнера:

mkdir -p ~/firefly-iii/backups
cat > ~/firefly-iii/backup.sh <<'EOF'
#!/bin/bash
set -e
cd ~/firefly-iii
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
source .env
docker compose exec -T firefly_db mysqldump -u firefly -p"${DB_PASSWORD}" firefly | gzip > backups/firefly_${TIMESTAMP}.sql.gz
find backups/ -name "firefly_*.sql.gz" -mtime +14 -delete
EOF
chmod +x ~/firefly-iii/backup.sh

Добавьте в cron ежедневный запуск и, обязательно, копирование бэкапов на отдельное хранилище (не на тот же диск, где крутится сервер):

(crontab -l 2>/dev/null; echo "0 3 * * * /home/$USER/firefly-iii/backup.sh") | crontab -

Если хотите более системный подход к резервному копированию баз данных с ротацией и офсайт-копией, посмотрите статью про автоматизацию резервного копирования баз данных — те же принципы (3-2-1, шифрование архива, проверка восстановления) применимы и к базе Firefly III.

Обновление приложения

Firefly III выпускает обновления регулярно, включая исправления безопасности. Обновление на Docker-инсталляции — это подтягивание нового образа и перезапуск:

cd ~/firefly-iii
docker compose pull
docker compose up -d
docker compose logs -f firefly_app

Контейнер сам выполнит миграции базы при старте, если схема изменилась. Перед крупным обновлением (смена мажорной версии) сделайте свежий бэкап базы вручную — ~/firefly-iii/backup.sh — и проверьте changelog проекта на предмет breaking changes, они бывают редко, но случаются.

Частые вопросы