Skip to content

Instantly share code, notes, and snippets.

@Zamana

Zamana/Firefly_III_in_FreeBSD.md

Last active January 3, 2024 03:01
Show Gist options
  • Save Zamana/bdfed1a06ba08467bd3ce92f4715c7fd to your computer and use it in GitHub Desktop.
Save Zamana/bdfed1a06ba08467bd3ce92f4715c7fd to your computer and use it in GitHub Desktop.
Download ZIP
Firefly III in FreeBSD (it's a FreeNAS jail, actually, but it doesn't matter...)
Raw
Firefly_III_in_FreeBSD.md

Firefly III on FreeBSD/TrueNAS jail

I was able to Install Firefly III in a FreeBSD environment (it is a FreeNAS jail, actually, but it doesn't matter) by following the general instructions in the Firefly III documentation.

Unfortunately I didn't take notes of the whole process, step by step, as I actually do it, but I guess that this general guidelines will lead you in the right path.

“Jail” is nothing more than the container technology used by FreeBSD these days (yes, there is life beyond Docker...), and we can say that a jail is a “mini FreeBSD environment”.

So, after creating the jail (refer to the documentation of FreeBSD or FreeNAS), the first thing you need to do is to “login” at the jail's console and start to use it.

FreeNAS version

This was done in a FreeNAS 11.2-U6 version.

Packages

The FreeBSD's package manager is pkg. So, run pkg update once in order to “build” the package database.

After this, install all these packages, by using pkg install .

You can install them one by one (and eventually make use of the pre-requisite feature of the package system), or use a script to install all of them:

  • curl-7.66.0
  • mysql80-client-8.0.17
  • mysql80-server-8.0.17
  • nginx-1.16.1_4,2
  • php73-7.3.10
  • php73-bcmath-7.3.10
  • php73-curl-7.3.10
  • php73-dom-7.3.10
  • php73-fileinfo-7.3.10
  • php73-filter-7.3.10
  • php73-gd-7.3.10
  • php73-hash-7.3.10
  • php73-iconv-7.3.10
  • php73-intl-7.3.10
  • php73-json-7.3.10
  • php73-ldap-7.3.10
  • php73-mbstring-7.3.10
  • php73-mysqli-7.3.10
  • php73-openssl-7.3.10
  • php73-pdo-7.3.10
  • php73-pdo_mysql-7.3.10
  • php73-pear-1.10.6
  • php73-pear-MDB2-2.5.0.b5
  • php73-pear-MDB2_Driver_mysql-1.5.0.b4
  • php73-pear-MDB2_Driver_mysqli-1.5.0.b4
  • php73-phar-7.3.10
  • php73-session-7.3.10
  • php73-simplexml-7.3.10
  • php73-tokenizer-7.3.10
  • php73-xml-7.3.10
  • php73-zip-7.3.10
  • php73-zlib-7.3.10
  • sudo-1.8.27_1

Bonus

Here is a single command line to install all these packages in FreeNAS 11.2-U7 (some package versions changed from U6):

pkg install -y curl-7.66.0 mysql80-client-8.0.17 mysql80-server-8.0.17 \
nginx-1.16.1_4,2 php73-7.3.13 php73-bcmath-7.3.13 \
php73-curl-7.3.13 php73-dom-7.3.13 php73-fileinfo-7.3.13 \
php73-filter-7.3.13 php73-gd-7.3.13 php73-hash-7.3.13 \
php73-iconv-7.3.13 php73-intl-7.3.13 php73-json-7.3.13 \
php73-ldap-7.3.13 php73-mbstring-7.3.13 php73-mysqli-7.3.13 \
php73-openssl-7.3.13 php73-pdo-7.3.13 php73-pdo_mysql-7.3.13 \
php73-pear-1.10.6 php73-pear-MDB2-2.5.0.b5 \
php73-pear-MDB2_Driver_mysql-1.5.0.b4 \
php73-pear-MDB2_Driver_mysqli-1.5.0.b4 php73-phar-7.3.13 \
php73-session-7.3.13 php73-simplexml-7.3.13 php73-tokenizer-7.3.13 \
php73-xml-7.3.13 php73-zip-7.3.13 php73-zlib-7.3.13 sudo-1.8.28

Paths

Unlike Linux, FreeBSD follows the principle of separating what is the “base system” from the rest. So, anything that is not part of the “core” of a UNIX system generally goes to the /usr/local and sometimes /usr/local/share folders.

So, in our case the php executable is in /usr/local/bin/php and the web server's root is in /usr/local/www.

Follow the DOCS

Now, follow the official documentation at this point and install composer:

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Before installing Firefly III, make the /usr/local/www owned by the www user:

chown -R www:www /usr/local/www

Then browse to /usr/local/www and install Firefly III:

composer create-project grumpydictator/firefly-iii --no-dev --prefer-dist firefly-iii <latest>

...and don't forget to change <latest> by the latest Firefly III version. At the time I'm writing this, it is 4.8.1.4.

You can run this command like this one stated above and then change the permissions and ownership, as the documention suggests, or you can use “sudo -u www (...)” and run the command as the www user, which is the WEB USER of FreeBSD (unlike Linux, that uses www-data).

Services

The 3 services that need to run automatically every time the system boots (or the jails boots) are nginx, php-fpm and mysql-server. So, do it: append to the /etc/rc.conf file the following lines:

mysql_enable="YES"
nginx_enable="YES"
php_fpm_enable="YES"

And start the services manually this time:

service mysql-server start
service php-fpm start
service nginx start

This is pretty close to the Linux systemd counterpart...

Next time you boot/reboot the jail, the services will start automatically.

Database

Now you need to access the MySQL database with root and create the database and the user with the grant privileges so Firefly III can use it.

If you installed the MySQL 8 version, like me, there is an issue regarding the password. So, access your MySQL instance (empty password by default) and create the resources like this:

mysql -u root mysql
root@localhost [mysql]> create database firefly;
root@localhost [mysql]> CREATE USER 'firefly'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
root@localhost [mysql]> grant all privileges on firefly.* to 'firefly'@'localhost';
root@localhost [mysql]> flush privileges;

The difference is in the use of mysql_native_password directive; if you opted for the 6 or 7 version, you can use the password directive.

Feel free to change the database name, the database user (both firefly in my examples) and the password (for obvious reasons).

Configuration

Now go to the /usr/local/www/firefly-iii directory and edit the hidden file .env file to match your scenario.

In my case I changed:

  • SITE_OWNER with my e-mail address
  • TZ with my timezone
  • APP_URL with the URL of my local network
  • DB_* with the MySQL credentials
    and
  • MAIL_* with my e-mail settings.

More about the MAIL_ settings later.

Initialize the database

Before you can use the system, you need to initialize the database. Be sure to execute these commands from the Firefly III folder (/usr/local/www/firefly-iii in our case):

php artisan migrate:refresh --seed
php artisan firefly-iii:upgrade-database
php artisan passport:install

Nginx

After fighting a little bit with Nginx and PHP-FPM, I've finally got one configuration that worked for me. Your mileage may vary, so use this as a starting point (but one that it's really working for me):

vi /usr/local/nginx/nginx.conf

load_module /usr/local/libexec/nginx/ngx_mail_module.so;
load_module /usr/local/libexec/nginx/ngx_stream_module.so;

user  www;

worker_processes  2;

events	{
	worker_connections  1024;
}

http {
	include            mime.types;
	default_type       application/octet-stream;
	sendfile           on;
	keepalive_timeout  65;
		
	server 	{
		listen       80;
		server_name  firefly.local;
		root         /usr/local/www/firefly-iii/public;
		index        index.php;
				
		location / {
    			try_files $uri $uri/ /index.php?$query_string;
    			autoindex on;
    			sendfile off;
		}

		location ~ \.php$ {
			fastcgi_pass   127.0.0.1:9000;
    			fastcgi_split_path_info ^(.+\.php)(/.+)$;
			fastcgi_index  index.php;
			include        fastcgi_params;
			fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
		}
	}
}

Of course you need to configure the PHP-FPM accordingly. In my case I prefer to use the 127.0.0.1:9000 method instead of the socket file. Configure it in the /usr/local/etc/php-fpm.d/www.conf file.

Restart the Nginx service:

service nginx restart

And now you're good to go to the URL configured to create your account and start to using the system.

Bonus

Crontab

To get the tasks of Firefly III running automatically, insert them at the crontab of the www user, like this:

crontab -u www -e

And paste this content inside the file:

# cron job for Firefly III
0 3 * * * /usr/local/bin/php /usr/local/www/firefly-iii/artisan firefly-iii:cron

Check if it's really there with:

crontab -u www -l

e-mail

Again, your mileage may very (a lot, in this case...).

In my case, I have another jail running postfix, that relays to my personal Google e-mail address. I prefer this approach so my credentials are in one place only. You can configure an entire postfix inside this jail, or you can use whatever method you want, as long as you know how to configure it up.

In my specific case, explained above, I decided to use the sendmail system that is already present in the jail to relay to my postfix in the other jail.

By searching in the internet, I found this procedure to configure sendmail:

First, edit the /etc/hosts of the jail and make your “mail system” accessible by name (this is a sendmail's requirement...):

192.168.0.112   firefly
192.168.0.125   postfix

Change the IPs and names accordingly!

Second, go to the /etc/mail directory and run the make command once, which will create some sendmail's voodoo files for you.

Then edit the <hostname>.mc file that the previous make command created, and append/insert/create a line pointing to your mail system:

define(`SMART_HOST', `postfix')

  • Disclaimer 1: “postfix” is the name of my other jail that runs... postfix.

  • Disclaimer 2: pay attention to the use of ` and ' (sendmail's voodoo!)

Then edit the <hostname>.submit.mc file and insert another line, exactly like the above, but BEFORE the last one, so the file looks like this:

	(...)
	dnl
	dnl If you use IPv6 only, change [127.0.0.1] to [IPv6:::1]
	define(`SMART_HOST', `postfix')
	FEATURE(`msp', `[127.0.0.1]')dnl

And finally run the command to complete the voodoo:

make all install restart

Configure sendmail to start automatically at system/jail boot by adding these lines to /etc/rc.conf:

sendmail_enable="YES"
sendmail_msp_queue_enable="YES"

And in the .env file at /usr/local/www/firefly-iii, configure your MAIL settings like this:

MAIL_DRIVER=sendmail
MAIL_HOST=postfix
MAIL_PORT=25
MAIL_FROM=<your e-mail>
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

changing the values according with your setup.

If you follow my instructions correctly (and I supposed that I wrote them right), your Firefly III installation will be able to send e-mails to you. Test it at the Options -> Administration page.

If you don't receive any message, check the logs at /var/log/maillog.

Here is the official documentation for the mail setup.

Acknowledgments

I appreciate any feedback and contributions in order to make this guide more precise.

Many thanks to danb35 from FreeNAS forum for pointing out several mistakes in the original edition of this guide.

Happy Fireflying!

@krowvin
Copy link

krowvin commented Feb 15, 2021 •
edited
Loading

Removing the versions off of the pkg install commands prompts for you to install the latest of each of the pkgs

i.e. pkg install mysql80-server

edit #1: php73-pear-MDB2_Driver_mysqli-1.5.0.b4 was required in full

edit #2: I had an issue running the firefly install command with the replaced with 5.4.6. Per this post I was able to remove the latest version and it installed 5.2.8 automagically.

edit #3: Nginx's config was located here in my jail vi /usr/local/etc/nginx/nginx.conf

@louwe
Copy link

louwe commented Jan 3, 2024

Composer is now available through ports as php83-composer.
However, I now get this error when trying to install Firefly:

Creating a "grumpydictator/firefly-iii" project at "./firefly-iii"
Cannot use grumpydictator/firefly-iii's latest version v6.1.1 as it requires ext-fileinfo * which is missing from your platform.

In CreateProjectCommand.php line 421:
                                                                                                                  
  Could not find package grumpydictator/firefly-iii with version 6.1.1 in a version installable using your PHP v  
  ersion, PHP extensions and Composer version.                                                                    
                                                                                                                  

create-project [-s|--stability STABILITY] [--prefer-source] [--prefer-dist] [--prefer-install PREFER-INSTALL] [--repository REPOSITORY] [--repository-url REPOSITORY-URL] [--add-repository] [--dev] [--no-dev] [--no-custom-installers] [--no-scripts] [--no-progress] [--no-secure-http] [--keep-vcs] [--remove-vcs] [--no-install] [--no-audit] [--audit-format AUDIT-FORMAT] [--ignore-platform-req IGNORE-PLATFORM-REQ] [--ignore-platform-reqs] [--ask] [--] [<package> [<directory> [<version>]]]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment