Firefly III¶

“Firefly III” is a (self-hosted) manager for your personal finances. It can help you keep track of your expenses and income, so you can spend less and save more.

Note

For this guide you should be familiar with the basic concepts of

License¶

Firefly III is released under the AGPLv3 license. All relevant information can be found in the GitHub repository of the project.

Prerequisites¶

You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$

Your domain needs to be set up:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation¶

cd to the directory one level above your document root, then install Firefly III via composer. You can find the latest version on the release tracker, replace the version below with the version number.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/
[isabell@stardust isabell]$ composer create-project grumpydictator/firefly-iii --no-dev --prefer-dist firefly_iii 5.4.6
[...]
[isabell@stardust isabell]$

After the installation has finished, remove your unused DocumentRoot and create a new symbolic link to the firefly_iii/public directory.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/
[isabell@stardust isabell]$ rm -f html/nocontent.html; rmdir html
[isabell@stardust isabell]$ ln -s /var/www/virtual/$USER/firefly_iii/public html
[isabell@stardust isabell]$

Configuration¶

We suggest you use an additional database for Firefly III to save your data. You have to create this database first.

[isabell@stardust ~]$ mysql -e "CREATE DATABASE ${USER}_fireflyiii"
[isabell@stardust ~]$

cd into your Firefly III directory.

[isabell@stardust isabell]$ cd firefly_iii
[isabell@stardust firefly_iii]$

Edit the .env file to change the settings. Change DB_HOST to localhost and change the values of DB_DATABASE, DB_USERNAME, DB_PASSWORD to reflect your MySQL credentials. Also edit any other settings like the time zone (TZ) or default language (DEFAULT_LANGUAGE) while the file is open. After you have edited all the necessary settings save the file.

Finishing installation¶

To finish the installation and setup your database run the following commands:

[isabell@stardust firefly_iii]$ php artisan migrate:refresh --seed
[isabell@stardust firefly_iii]$ php artisan firefly-iii:upgrade-database
[isabell@stardust firefly_iii]$ php artisan passport:install
[isabell@stardust firefly_iii]$

Go to https://isabell.uber.space to access your Firefly III installation.

Warning

Please make sure to directly create an account, as the first account will be an admin account.

Tuning¶

Mail¶

To setup Firefly III to be able to send mails, you first have to create a new mailbox user:

[isabell@stardust ~]$ uberspace mail user add firefly_iii
Enter a password for the mailbox:
Please confirm your password:
New mailbox created for user: 'firefly_iii', it will be live in a few minutes...
[isabell@stardust ~]$

Afterwards navigate to your Firefly III home folder and edit the .env file. The mail configuration should be setup like this:

MAIL_MAILER=smtp
MAIL_HOST=stardust.uberspace.de
MAIL_PORT=587
MAIL_FROM=firefly_iii@isabell.uber.space
MAIL_USERNAME=firefly_iii@isabell.uber.space
MAIL_PASSWORD=MySuperSecretPassword
MAIL_ENCRYPTION=tls

Note

Replace MySuperSecretPassword with the password you just assigned to the mailbox.

Cronjob¶

For Firefly III to be able to create recurring transactions a cronjob needs to be set up. Use the crontab -e command and add the following line. This will run the job for recurring transactions every night.

# cron job for Firefly III
0 3 * * * /usr/bin/php /var/www/virtual/$USER/firefly_iii/artisan firefly-iii:cron

Updates¶

Warning

Please make sure to backup your data before updating.

To update your Firefly III installation, cd to the directory one level above your document root, then download the new version via composer. Replace <next_version> with the latest version.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/
[isabell@stardust isabell]$ composer create-project grumpydictator/firefly-iii --no-dev --prefer-dist firefly-iii-updated <next_version>
[...]
[isabell@stardust isabell]$

After the installation has finished, we need to copy over our settings located in the .env file and other data.

[isabell@stardust isabell]$ cp firefly_iii/.env firefly-iii-updated/.env
[isabell@stardust isabell]$ cp firefly_iii/storage/upload/* firefly-iii-updated/storage/upload/
[isabell@stardust isabell]$ cp firefly_iii/storage/export/* firefly-iii-updated/storage/export/
[isabell@stardust isabell]$

Navigate into the newly created folder and run the following commands to finish the upgrade:

[isabell@stardust isabell]$ cd firefly-iii-updated
[isabell@stardust firefly-iii-updated]$ rm -rf bootstrap/cache/*
[isabell@stardust firefly-iii-updated]$ php artisan cache:clear
[isabell@stardust firefly-iii-updated]$ php artisan migrate --seed
[isabell@stardust firefly-iii-updated]$ php artisan firefly-iii:upgrade-database
[isabell@stardust firefly-iii-updated]$ php artisan passport:install
[isabell@stardust firefly-iii-updated]$ php artisan cache:clear
[isabell@stardust firefly-iii-updated]$

Move one folder up again and rename the updated folder, so our document root points to the updated version.

[isabell@stardust firefly-iii-updated]$ cd ..
[isabell@stardust isabell]$ mv firefly_iii firefly-iii-old
[isabell@stardust isabell]$ mv firefly-iii-updated firefly_iii
[isabell@stardust isabell]$

You can now go to https://isabell.uber.space to access your updated Firefly III installation.

Acknowledgements¶

This guide is based on the official Firefly III setup guide.

Tested with Firefly III 5.4.6, Uberspace 7.8.0.0.

Written by: Felix Kohlen <https://github.com/FelixKohlen>