jaylenw/firefly-iii-docker-setup

Firefly-iii Financial Application with Deployment Environments using Docker Compose and Watchtower.

My Firefly-iii Docker Setup

Goal: Have development and production deployment environments setup with docker-compose for the Firefly-iii application. Have the development environment support automatic updates using Watchtower.

I have the development and production environment running on a server. The development environment will check for updates using Watchtower every week and applies them if a newer Firefly-iii develop image is found. I use the version number of the development environment to confidently upgrade my production environment manually for now when I need to. Watchtower notifies me when it finds a new release. The development environment also gives my users and me opportunities to test things out in the application and not worry about affecting our setup in the production environment. I have also configured Firefly-iii to send out emails using Mailgun.

Local Testing

To get started with this, it is best that you are able to get Firefly-iii running locally first before deploying it to your deployment environment (ex. your server).

This repository has a development and a production folder with each folder corresponding to a different setup described by the docker-compose.yml file in each of them. The production folder is configured to pull the latest stable image of Firefly-iii, while the development folder is configured to pull the latest develop image of Firefly-iii.

Please visit, https://raw.githubusercontent.com/firefly-iii/docker/master/docker-compose.yml to see an example docker-compose.yml file from the developer that maintains Firefly-iii. The docker-compose.yml was used as the basis found in the files in the repository here.

Getting Started

1.) Make sure you have Docker and Docker Compose installed.

2.) Clone this repository.

3.) Create the necessary environment files Docker expects.

The development folder requires the files .db-env, .firefly-env, .pgadmin-env, and .watchtower-env. The production folder requires the files .db-env and .firefly-env.

The directory structure should look like this:

development
---.db-env
---.firefly-env
---.pdadmin-env
---.watchtower-env
---docker-compose.yml
production
---.db-env
---.firefly-env
---docker-compose.yml

.db-env

This file is configured with the following. The application will use the user, password, and database specified.

POSTGRES_USER=<user>
POSTGRES_PASSWORD=<password>
POSTGRES_DB=firefly

.firefly-env

Please visit, https://raw.githubusercontent.com/firefly-iii/firefly-iii/master/.env.example to see an example environment file from the developer that maintains Firefly-iii. I used the example file to help set some, not all configurations for myself. You may need to use the example from the developer, some below, and your own modifications to get the setup you want.

Some, but not all, notable configurations:

APP_ENV=local # we are running locally
APP_DEBUG=true # fine to show debug information in local environment
APP_KEY=<32-random-characters> # you can use online tools to help you generate one

TZ=America/Los_Angeles # changed this to LA

APP_URL=http://localhost # accessing the app over localhost

TRUSTED_PROXIES=** # running with docker

DB_CONNECTION=pgsql
DB_HOST=<db-host> # either fireflyiiidb-dev or fireflyiiidb-prod as indicated in the `docker-compose.yml` file
DB_PORT=5432
DB_DATABASE=firefly
DB_USERNAME=<user> # same user that is set in `.db-env`
DB_PASSWORD=<password> # same password that is set in `.db-env`

MAIL_MAILER=mailgun # configured this because I am using Mailgun for emails
MAIL_FROM=<from-email-address> # this is important, set this using your verified Mailgun domain, example [email protected]
MAILGUN_DOMAIN=<verified-mailgun-domain> # this is important, set your verified Mailgun domain, example firefly.mydomain.com
MAILGUN_SECRET=<your-mailgun-api-key>
MAILGUN_ENDPOINT=api.mailgun.net # this is fine if you are in the U.S.

.pgadmin-env

Below is an example of how you can setup the credentials to login to PGAdmin for database testing locally for the development environment. By default, PGAdmin is commented out in the development's docker-composer.yml file.

PGADMIN_DEFAULT_EMAIL=<your-email-address>
PGADMIN_DEFAULT_PASSWORD=<some-random-password>

.watchtower-env

Below is an example of how I have configured Watchtower to send notifications with Rocket Chat. Please refer to Watchtower's documentation here to see how to configure notifications of your choice.

WATCHTOWER_NOTIFICATIONS=shoutrrr
WATCHTOWER_NOTIFICATION_URL=rocketchat://myserver.example.com/token/channel

4.) Once you have the environment settings set for local development make the necessary changes for local production.

5.) Next, run both the local development and production environments by running docker-compose up in each folder. Visit localhost:8081 for dev and and locahost:8080 for prod.

Deployment Environments

Once you have tested that everything is working well locally for the development and production environments, after minor adjustments you can proceed confidently to deploy them to a server.

Getting Started

1.) First, modify the environment files for deployment on a server.

.firefly-env

Some, but not all notable changes needed for deployment.

APP_ENV=production # we are running in a production environment (both prod and dev deployments)
APP_DEBUG=false # we don't want debug information showing in a production environment (both prod and dev deployments)
APP_URL=<your-domain-for-the site> # example, mydomain.com
SITE_OWNER=<your-email-addres> # best to list your email

2.) Make sure your server has Docker and Docker Compose installed. Clone the repo and add your environment files for the development and production deployments added to the corresponding directories.

3.) I strongly suggest having a proxy server in front of your Firefly-iii docker environments.

Below is an example of a reverse-proxy configuration to get you started using NGNIX. PLEASE CONFIGURE YOUR DEPLOYMENT WITH SSL.

# configuration for firefly dev environment
upstream firefly-dev-backend {
    # the firefly-iii application in firefly-iii container
    server <localhost or whatever IP>:<port>; # ip and use the port specified in the docker-compose.yml
    keepalive 64;
}

server {
    # the virtual host name of this
    listen 80;
    server_name <your-domain-or-subdomain>;

    location / {
        proxy_pass http://firefly-dev-backend$uri$is_args$args;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        client_max_body_size 64M;
    }
}

4.) Start the two environments by running the following command, docker-compose up -d in each folder. This will allow the applications to run in the background. Also note, Docker will restart the containers unless they were explicitly told to shutdown (it will survive server reboots).

5.) Optional - Firefly-iii supports recurring transactions and automatic budgeting. You may want to setup a daily cron job so Firefly-iii may carry out these tasks. Find more information about it here.

Below is the contents of a script that is compatible with this setup to have Firefly-iii carry out daily tasks. Take the content below and add it to a bash script. Then create a cron job on your host to call your script. Modify as needed to match your Docker Compose service and container if you have changed them to something else in your docker-compose.yml file.

#!/bin/bash

# background info, https://docs.firefly-iii.org/advanced-installation/cron#call-the-cron-job-from-the-host-system
# host will call the container so that we can have recurring transactions
docker exec --user www-data production_fireflyiii-prod_1 /usr/local/bin/php /var/www/html/artisan firefly-iii:cron

---

Made with ♥ in Los Angeles CA.

firefly-iii-docker-setup's Issues

Document local and production setup

Problem

Need to update the documentation on running the setup for local testing and production

Solution

Go through the existing configurations and document how things are setup.

Change production listening port from 80 to 8080

Problem

Firefly-iii now listens on port 8080.

Solution

Change the listening port for the production docker-compose.yml file from 80 to 8080.

Update documentation to change MAIL_DRIVER to MAIL_MAILER

Problem

As of Firefly-iii 5.3.0, instead of MAIL_DRIVER, it should be MAIL_MAILER.

Solution

Update the documentation to reflect this change

Implement New Firefly-iii DockerHub repository

Problem

Implement the latest DockerHub repository https://hub.docker.com/r/fireflyiii/core

Implement telemetry

Problem

Consider and implement telemetry for Firefly-iii

Solution

Details are found here, https://docs.firefly-iii.org/support/telemetry.

Re-configure Watchtower notifications due to changes in the latest version

Problem

After doing a docker-compose pull, we fetched the latest Watchtower container at 1.1.6. This introduced a problem where Watchtower would not start as the way it would send notifications to Rocket Chat has changed.

Solution

Implement the necessary changes by implementing the shoutrrr configuration and update the readme.

Prepare docker setup for firefly v5.4.x

Problem

We want to update our setup to support 5.4.x releases of firefly. Looking at the release notes, there are some changes that are required. More details are found here https://github.com/firefly-iii/firefly-iii/releases/tag/5.4.0.

Containers are not updating properly w/ the current Watchtower config

Problem

Watchtower is not updating the containers as it should. The containers specified are incorrect and we should change from an interval to a schedule.

Solution

Specify the correct container names and use the scheduling feature vs. the interval feature.

Interval - https://containrrr.github.io/watchtower/arguments/#poll_interval
Scheduling - https://containrrr.github.io/watchtower/arguments/#scheduling

Implement cron job with firefly-iii

Problem

Configure and document setting up cron jobs for Firefly-iii.

Solution

Look into the cron job on the host, 0 3 * * * docker exec --user www-data <container> /usr/local/bin/php /var/www/firefly-iii/artisan firefly-iii:cron, that calls the container. In my case, modify this so that it calls the docker-compose service. View more info here https://docs.firefly-iii.org/advanced-installation/cron.