1---
2title: "Running firefly3 on alpine"
3date: 2022-07-18
4tags: ['alpine', 'linux', 'php', 'nginx']
5---
6
7**Disclaimer:** before starting be aware that I'm not a sysadmin nor I have a
8deep knowledge in security. This is me reporting the steps I did as a learning
9experiment, so take this tutorial as your own risk.
10
11I have a pretty decent knowledge in container tecnology, I maintain several
12container on my local server for many applications. However I've decided to
13take a step back and learn a bit more how those applications are really
14deployed and kept without containers, and first candidate being firefly3[^1]. I
15have it currently running on container but let's install in a disctributions.
16
17For the distro of choice I'll pick alpine, for its small footprint and the use
18of OpenRC (nothing against systemd though).
19
20*I don't want to extend this tutorial to cover every single part, so for the
21next steps I'll assume that you have a running instance of PostgreSQL and
22Alpine.*
23
24## Dependencies
25
26First we need to install all the necessary packages to get firefly running.
27Let's go through them and check are they are used for.
28
29```shell
30apk add curl tar gzip
31```
32
33cURL is needed to download the source code from Github and tar gzip are for
34extracting the compressed code.
35
36```shell
37apk add composer
38```
39
40 Composer is a dependency manager for PHP. It is required to download the
41 dependencies of the project.
42
43 Now we need to download the list of dependencies list in the site[^2].
44
45```
46 Extra packages
47 Install the following PHP modules:
48 PHP BCMath Arbitrary Precision Mathematics
49 PHP Internationalization extension
50 PHP Curl
51 PHP Zip
52 PHP Sodium
53 PHP GD
54 PHP XML
55 PHP MBString
56 PHP whatever database you're gonna use.
57```
58
59For those we have the following alpine packages:
60
61```shell
62apk add \
63 php8 \
64 php8-curl \
65 php8-zip \
66 php8-sodium \
67 php8-gd \
68 php8-xml \
69 php8-mbstring \
70 php8-bcmath \
71 php8-pgsql
72```
73
74But that is not everything, I don't If I lack knowledge in the PHP stack but
75the applicatoin will later complain about a lot of missing dependencies, those
76being:
77
78```shell
79apk add \
80 php8-fileinfo \
81 php8-intl \
82 php8-session \
83 php8-simplexml \
84 php8-tokenizer \
85 php8-xmlwriter \
86 php8-dom \
87 php8-pdo_pgsql \
88 php8-shmop
89```
90
91A tip that may as well help you later. Some of those not listed packages are
92described in the their project for the docker image[^3] and its base image[^4].
93It can also help with describing the necessary steps.
94
95As the next step we need to install the pieces of software that will actually
96run the project:
97
98```shell
99apk add nginx php8-fpm
100```
101Nginx will act as reverse proxy and php8-fpm will actually run the project. You
102can use lighttpd as well as some others.
103
104## Deploying the code
105
106Now we have all necessary packages, lets download the project into on server,
107grab the latest release from Github, at the time of this writing is `5.7.9`.
108Download into the `/var/www/firefly`. The folder location is kinda up you, I
109think nginx itself has another default folder for its sites, but I always use
110www folder to store the projects.
111
112```shell
113mkdir -p /var/www/firefly
114```
115
116Create the folder then download/extract the source code:
117
118```shell
119curl -SL https://github.com/firefly-iii/firefly-iii/archive/refs/tags/5.7.9.tar.gz | \
120 tar zxC /var/www/firefly --strip-components 1
121```
122
123This piece of code was taken from the dockerfile[^5].
124
125Now move to the `/var/www/firefly` and install its dependencies with composer:
126```shell
127cd /var/www/firefly
128composer install --prefer-dist --no-dev --no-scripts
129```
130
131## Config files
132
133### Firefly
134
135Firefly makes the process of setting up the connection strings and other
136configuration quite easy. We'll only need to create an `.env` file with all the
137information needed. Fill the information according with your setup:
138
139```ini
140# /var/wwww/firefly/.env
141
142DB_CONNECTION=pgsql
143DB_HOST=localhost
144DB_PORT=5432
145DB_DATABASE=firefly
146DB_USERNAME=admin
147DB_PASSWORD=admin
148APP_KEY=<RANDON_KEY>
149```
150
151To generate a random key just run:
152
153```shell
154head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo
155```
156
157Once you have set it up we need to bootstrap the project:
158
159```shell
160php artisan config:cache
161```
162
163To update the cached configuration. If everything is setup properly the process
164finish successfully.
165
166```shell
167php artisan firefly-iii:create-database
168php artisan migrate:refresh --seed
169php artisan firefly-iii:upgrade-database
170```
171
172To bootstrap the database.
173
174### Nginx
175
176We will need to edit the nginx config file to find and run the project, add
177the following server inside of `/etc/nginx/http.d/`, by default nginx will read
178all `.config` inside of that folder. Just like the www folder this is more a
179personal choice, you have some room to choose where you want to config this
180server.
181
182```shell
183# /etc/nginx/http.d/firefly.conf
184server {
185 listen 8080;
186 server_name localhost;
187
188
189 root /var/www/firefly/public;
190
191 location ~ \.php$ {
192 try_files $uri $uri/ =404;
193 fastcgi_split_path_info ^(.+\.php)(/.+)$;
194 fastcgi_pass 127.0.0.1:9000;
195 include fastcgi.conf;
196 }
197
198 location / {
199 try_files $uri /index.php$is_args$args;
200 }
201}
202```
203
204This will set up the process in the port 8080. It is just an exemple, adapt it
205to your needs.
206
207### Services
208
209Now that we have everything set up we can start the service to serve firefly:
210
211```shell
212rc-service php-fpm8 start
213rc-service nginx start
214```
215
216`http://localhot:8080/` (or your server's hostname) should be up and running.
217
218[^1]: https://www.firefly-iii.org/
219[^2]: https://docs.firefly-iii.org/firefly-iii/installation/self_hosted/?mtm_campaign=docu-internal&mtm_kwd=self_hosted
220[^3]: https://dev.azure.com/Firefly-III/_git/MainImage
221[^4]: https://dev.azure.com/firefly-iii/_git/BaseImage
222[^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