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.
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.
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
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
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.
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>
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.
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.
1.) First, modify the environment files for deployment on a server.
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:cronMade with ♥ in Los Angeles CA.