diff options
| -rw-r--r-- | content/posts/2022-07-18-firefly-install.md | 222 |
1 files changed, 222 insertions, 0 deletions
diff --git a/content/posts/2022-07-18-firefly-install.md b/content/posts/2022-07-18-firefly-install.md new file mode 100644 index 0000000..4dfd008 --- /dev/null +++ b/content/posts/2022-07-18-firefly-install.md @@ -0,0 +1,222 @@ +--- +title: "Running firefly3 on alpine" +date: 2022-07-18 +tags: ['alpine', 'linux', 'php', 'nginx'] +--- + +**Disclaimer:** before starting be aware that I'm not a sysadmin nor I have a +deep knowledge in security. This is me reporting the steps I did as a learning +experiment, so take this tutorial as your own risk. + +I have a pretty decent knowledge in container tecnology, I maintain several +container on my local server for many applications. However I've decided to +take a step back and learn a bit more how those applications are really +deployed and kept without containers, and first candidate being firefly3[^1]. I +have it currently running on container but let's install in a disctributions. + +For the distro of choice I'll pick alpine, for its small footprint and the use +of OpenRC (nothing against systemd though). + +*I don't want to extend this tutorial to cover every single part, so for the +next steps I'll assume that you have a running instance of PostgreSQL and +Alpine.* + +## Dependencies + +First we need to install all the necessary packages to get firefly running. +Let's go through them and check are they are used for. + +```shell +apk add curl tar gzip +``` + +cURL is needed to download the source code from Github and tar gzip are for +extracting the compressed code. + +```shell +apk add composer +``` + + Composer is a dependency manager for PHP. It is required to download the + dependencies of the project. + + Now we need to download the list of dependencies list in the site[^2]. + +``` + 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 whatever database you're gonna use. +``` + +For those we have the following alpine packages: + +```shell +apk add \ + php8 \ + php8-curl \ + php8-zip \ + php8-sodium \ + php8-gd \ + php8-xml \ + php8-mbstring \ + php8-bcmath \ + php8-pgsql +``` + +But that is not everything, I don't If I lack knowledge in the PHP stack but +the applicatoin will later complain about a lot of missing dependencies, those +being: + +```shell +apk add \ + php8-fileinfo \ + php8-intl \ + php8-session \ + php8-simplexml \ + php8-tokenizer \ + php8-xmlwriter \ + php8-dom \ + php8-pdo_pgsql \ + php8-shmop +``` + +A tip that may as well help you later. Some of those not listed packages are +described in the their project for the docker image[^3] and its base image[^4]. +It can also help with describing the necessary steps. + +As the next step we need to install the pieces of software that will actually +run the project: + +```shell +apk add nginx php8-fpm +``` +Nginx will act as reverse proxy and php8-fpm will actually run the project. You +can use lighttpd as well as some others. + +## Deploying the code + +Now we have all necessary packages, lets download the project into on server, +grab the latest release from Github, at the time of this writing is `5.7.9`. +Download into the `/var/www/firefly`. The folder location is kinda up you, I +think nginx itself has another default folder for its sites, but I always use +www folder to store the projects. + +```shell +mkdir -p /var/www/firefly +``` + +Create the folder then download/extract the source code: + +```shell +curl -SL https://github.com/firefly-iii/firefly-iii/archive/refs/tags/5.7.9.tar.gz | \ + tar zxC /var/www/firefly --strip-components 1 +``` + +This piece of code was taken from the dockerfile[^5]. + +Now move to the `/var/www/firefly` and install its dependencies with composer: +```shell +cd /var/www/firefly +composer install --prefer-dist --no-dev --no-scripts +``` + +## Config files + +### Firefly + +Firefly makes the process of setting up the connection strings and other +configuration quite easy. We'll only need to create an `.env` file with all the +information needed. Fill the information according with your setup: + +```ini +# /var/wwww/firefly/.env + +DB_CONNECTION=pgsql +DB_HOST=localhost +DB_PORT=5432 +DB_DATABASE=firefly +DB_USERNAME=admin +DB_PASSWORD=admin +APP_KEY=<RANDON_KEY> +``` + +To generate a random key just run: + +```shell +head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo +``` + +Once you have set it up we need to bootstrap the project: + +```shell +php artisan config:cache +``` + +To update the cached configuration. If everything is setup properly the process +finish successfully. + +```shell +php artisan firefly-iii:create-database +php artisan migrate:refresh --seed +php artisan firefly-iii:upgrade-database +``` + +To bootstrap the database. + +### Nginx + +We will need to edit the nginx config file to find and run the project, add +the following server inside of `/etc/nginx/http.d/`, by default nginx will read +all `.config` inside of that folder. Just like the www folder this is more a +personal choice, you have some room to choose where you want to config this +server. + +```shell +# /etc/nginx/http.d/firefly.conf +server { + listen 8080; + server_name localhost; + + + root /var/www/firefly/public; + + location ~ \.php$ { + try_files $uri $uri/ =404; + fastcgi_split_path_info ^(.+\.php)(/.+)$; + fastcgi_pass 127.0.0.1:9000; + include fastcgi.conf; + } + + location / { + try_files $uri /index.php$is_args$args; + } +} +``` + +This will set up the process in the port 8080. It is just an exemple, adapt it +to your needs. + +### Services + +Now that we have everything set up we can start the service to serve firefly: + +```shell +rc-service php-fpm8 start +rc-service nginx start +``` + +`http://localhot:8080/` (or your server's hostname) should be up and running. + +[^1]: https://www.firefly-iii.org/ +[^2]: https://docs.firefly-iii.org/firefly-iii/installation/self_hosted/?mtm_campaign=docu-internal&mtm_kwd=self_hosted +[^3]: https://dev.azure.com/Firefly-III/_git/MainImage +[^4]: https://dev.azure.com/firefly-iii/_git/BaseImage +[^5]: https://dev.azure.com/Firefly-III/MainImage/_git/MainImage?path=/Dockerfile&version=GC520b8f865ea623a8625fe64e9f583406849be91a&line=14&lineEnd=15&lineStartColumn=1&lineEndColumn=1&lineStyle=plain&_a=contents |