Mustafa Can Yücel

Setting Up Your Debian Server 7: Firefly III

Firely 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. Firefly III supports the use of budgets, categories, and tags. Using a bunch of external tools, you can import data. It also has many neat financial reports available.

I have been using Bluecoins for account and finance tracking; it is one of the best applications available on mobile. It supports synchronization between devices, however, it does not have a web interface. I have been looking for a web interface for a while and I have found Firefly-III. It is a self-hosted application, which means that I can host it on my server and access it from anywhere. It also has a (third-party) mobile application, which is a plus.

Firefly-III requires a LAMP stack to run (Linux, Apache, MySQL, PHP). It has a docker image that includes all the dependencies, but it can mess up with the existing Apache configurations. It is also much more fun to install it manually, so let's get started. Firefly-III requires PHP version 8.2 or higher and we have already updated our version in the previous section. It also requires a bunch of PHP extensions, all of which should be already installed:

  • PHP BCMath Arbitrary Precision Mathematics
  • PHP Internationalization extension
  • PHP Curl
  • PHP Zip
  • PHP Sodium
  • PHP GD
  • PHP MBString
  • PHP whatever database you're gonna use (we will use MySQL/MariaDB).
To check if an extension is installed, you can use the following command to see if it exists in the PHP configuration:
php -i | grep {extension}
Then we will install composer with sudo rights:
curl -sS | sudo php -- --install-dir=/usr/local/bin --filename=composer
Now we verify if the composer is installed correctly:
composer -v
Now we will install Firefly III with composer, into the /var/www/ directory (composer will automatically create a folder named firefly-iii):
cd /var/www/
sudo composer create-project grumpydictator/firefly-iii --no-dev --prefer-dist firefly-iii 6.0.10
For the version, substitute the latest version number from the official Firefly-III site. Then we will change the ownership of the /var/www/firefly-iii directory to the www-data user and group:
sudo chown -R www-data:www-data /var/www/firefly-iii
sudo chmod -R 775 /var/www/firefly-iii/storage
After this, we need to create the database and its user for the Firefly-III. First, we need to log in to the MySQL server:
sudo mariadb
Then create a new database and user for Firefly-III (change the password):
CREATE USER 'firefly'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON firefly.* TO 'firefly'@'localhost';
Now we can update the configuration of the Firefly-III. Start editing the .env file in the /var/www/firefly-iii directory:
sudo vi /var/www/firefly-iii/.env
The most important lines to update are (change the email and password):
# leave empty or omit when not using a socket connection
It is always better to read the whole configuration file and update fields according to your needs. After you are done, save and exit the file. Then we initialize the database and the application:
sudo php artisan firefly-iii:upgrade-database
sudo php artisan firefly-iii:correct-database
sudo php artisan firefly-iii:report-integrity
sudo php artisan passport:install
All of these operations should complete without an error; if you get an error most likely the database configuration is incorrect.

Note From the Future

I strongly advise you to use Caddy instead of Apache. It is much easier to set up and use. For setting up Caddy, you can skip to Switching to Caddy Server post. If you still want to use Apache, you can continue reading this post.

Now we need to configure Apache to serve the Firefly-III application. First and foremost, we add an A DNS record for our subdomain for our server IP; for this example, we will use Then we need to create a new Apache configuration file for our subdomain:

sudo vi /etc/apache2/sites-available/
Then we add the following lines to the file (change the domain name):
<VirtualHost *:80>
    DocumentRoot /var/www/firefly-iii/public
    <Directory /var/www/firefly-iii/public>
        AllowOverride All
Then we enable the new configuration and restart Apache:
sudo a2ensite
sudo systemctl restart apache2
Now we can access the Firefly-III application from the browser by visiting Let's check if the site is working correctly, but do not create an account (yet). If you get an error, check the Apache error log.

Our app is working now, but it is using unencrypted HTTP traffic. We will enable HTTPS with Let's Encrypt, using Certbot. We have used it for many times now, so it should be available; if not, see the previous section. We will use the certbot command to obtain a standalone certificate for our domain (do not forget that we need port 80 to be available, so we disable apache2 for a moment):

sudo systemctl stop apache2
sudo certbot certonly --standalone 
Note that all the standalone certificates are placed under the /etc/letsencrypt/live/ directory. Then we update the Apache configuration to redirect the HTTP traffic to HTTPS, and to use the certificate we just obtained:
sudo vi /etc/apache2/sites-available/
Then we add the following lines to the file (change the domain name):
<VirtualHost *:80>
    Redirect permanent /
<VirtualHost *:443>
    DocumentRoot /var/www/firefly-iii/public
    <Directory /var/www/firefly-iii/public>
        AllowOverride All
    ErrorLog ${APACHE_LOG_DIR}/firefly.error.log
    CustomLog ${APACHE_LOG_DIR}/firefly.access.log combined
    SSLCertificateFile /etc/letsencrypt/live/
    SSLCertificateKeyFile /etc/letsencrypt/live/
    Include /etc/letsencrypt/options-ssl-apache.conf
Then we enable the new configuration and restart Apache:
sudo a2ensite
sudo systemctl restart apache2
Now we can access the Firefly-III application from the browser by visiting The first time you visit the site, you will be redirected to the login page. We create a new account and log in. You can find how to use Firefly-III in the official documentation.

The application's website is fully responsive; however, if you want to have a native mobile application, you can try Waterfly-III. It is a mobile application for Firefly-III, and it is available for Android. As the author said, its design is heavily influenced by Bluecoins, which is a big plus. The app is built using Flutter and tries to keep to the Material 3 design guidelines. Additionally, the author tries to keep the app as "lean" as possible, without external trackers or unneeded dependency on external packages. If you are not happy with third-party software, Firefly-III supports a full-fledged REST API, so you can build your own mobile application.