Skip to content

Self-managed server

If you have your own (virtual) web server you can use this guide to install Firefly III. You may have some ingredients prepared already.

Note

Some of these commands use the sudo or sudo -u www-data command. These are only available when you have the necessary privileges. If you do not have these privileges, you may need to ask your system administrator to run these commands for you.

Ingredients

You need a working LAMP, LEMP or WAMP (1) stack. Make sure you use PHP 8.4. How to set this up is outside the scope of this manual, but this is something you can look up.

  1. Linux, Apache, MySQL, PHP (LAMP) or Linux, Nginx, MySQL, PHP (LEMP) or Windows, Apache, MySQL, PHP (WAMP).

You will also need a (MySQL) database and credentials for a user that has permissions on that database. Firefly III creates its own tables. You can use SQLite if this is difficult to set up.

In case you want to use one of the languages that Firefly III is equipped with, make sure you install the necessary locales. For Debian / Ubuntu for example, use sudo apt install language-pack-nl-base && sudo locale-gen.

Several users have created specific guides for their OS and database combination.

  1. Firefly III in Ubuntu 20.04 and proxmox
  2. Firefly III scripted installer
  3. Firefly III Gulp orchestration scripts

Preparing your server

Extra packages

Install the following PHP modules:

  • PHP BCMath Arbitrary Precision Mathematics
  • PHP Internationalization extension
  • PHP Curl
  • PHP Zip
  • PHP Sodium
  • PHP GD
  • PHP XML
  • PHP MBString
  • PHP support for whatever database you're going to use.

You can search the web to find out how to install these modules. Some may be installed already depending on your system. Use phpinfo() or php -i to find out.

Installing Firefly III

Installing by pulling the remote repository

It's no longer possible to install Firefly III by pulling the code from the main or develop branch of the repository. Generated (JS) code and other dependencies are not in the repository, so your new installation may not work as expected. To do so manually, please review this FAQ question

Main command

v6.4.9 is the latest version.

It is up to you, if you prefer the tar.gz file or the zip file.

Validate the downloaded file

Optionally, you can validate and test the integrity of your download by also downloading the SHA256 checksum file.

With this SHA256 checksum file, you can verify the integrity of the download by running the following command:

# Should return: "FireflyIII-v6.4.9.zip: OK"
sha256sum -c FireflyIII-v6.4.9.zip.sha256
sha256sum -c FireflyIII-v6.4.9.tar.gz.sha256

# alternative command:
shasum -a 256 -c FireflyIII-v6.4.9.zip.sha256
shasum -a 256 -c FireflyIII-v6.4.9.tar.gz.sha256

If you also want to verify the digital signature of the release, please follow the instructions under "Verify the signature" on the page about signatures.

Extract the file

Extract the downloaded file in your web server's root directory, or in a specific directory you want to use.

Tip

Some servers require sudo to extract or change things in the /var/www directory, because the directory is owned by a dedicated user (e.g. www-data on Debian/Ubuntu). If this is the case for you, make sure to prefix the commands in this document with sudo -u www-data (replace www-data with this username) to ensure that all of your files have the same permissions.

# the directory name is up to you, of course:
mkdir /var/www/firefly-iii
unzip FireflyIII-v6.4.9.zip -d /var/www/firefly-iii

# the tar.gz file extracts with the following command.
tar -xvf FireflyIII-v6.4.9.tar.gz -C /var/www/firefly-iii

This should get you the entire installation in the directory of your choice.

Web server configuration

Info

Since this is very specific to each system, there are no instructions how to do this.

Most servers will serve files from the /var/www directory. Firefly III would be served from /firefly-iii/public. This is not really what you would want to do.

You can look up for your webserver (Apache or nginx) how to change the root directory or how to set up virtual hosts.

Firefly III configuration

In the directory where you just unzipped Firefly III you will find a .env.example file. Rename or copy it to .env. 

cp .env.example .env

Open this file using your favorite editor. There are instructions what to do in this file.

Make sure you configure at least the database. For SQLite, you must drop all the configuration except DB_CONNECTION=sqlite.

Initialize the database

This step is very important, because Firefly III needs a database to work with, and it will tell you whether your configuration is correct.

If you decide to use SQLite, make sure you run the following command to create the SQLite database file.

# the directory may be different on your system:
cd /var/www/firefly-iii
touch ./storage/database/database.sqlite

Either way, in all cases, run these commands to initialize the database:

php artisan firefly-iii:upgrade-database
php artisan firefly-iii:correct-database
php artisan firefly-iii:report-integrity
php artisan firefly-iii:laravel-passport-keys

Now you should be able to visit http://localhost and see Firefly III.

It doesn't work!

This manual can't list all the possible exceptions and errors you may run into. Some common issues are documented in the FAQ.

Look in these directions when you're running into problems:

  • Apache may not have mod_rewrite enabled or the htaccess file isn't activated (AllowOverride).
  • Nginx may not have the correct try_files instruction in the location block.

Visiting Firefly III

Check out the tutorial on creating accounts and transactions.