Firefly III

Self-hosted financial manager.

Ansible Role: firefly

A database backend should already exist with either a pre-existing firefly database, or full permissions to create tables in the database when applying the role. Local storage should be locked down to prevent sensitive data from leaking.

  • firefly_app_url should remain localhost as it does not effect proxied or non-proxied connections. Existing documentation on the web is wrong.

  • firefly_trusted_proxies should be set to the known proxy IP address so all other connections are denied by default. Setting to ** will enable all connections (insecure).

# Firefly
Firefly installation from public release.

## Requirements
No additional requirements.

## Role Variables
Settings have been throughly documented for usage.

[defaults/main.yml](https://github.com/r-pufky/ansible_firefly/blob/main/defaults/main/main.yml).

[defaults/config.yml](https://github.com/r-pufky/ansible_firefly/blob/main/defaults/main/config.yml).

## Dependencies
N/A

## Example Playbook
host_vars/firefly.example.com/vars/firefly.yml
``` yaml
firefly_version: 'latest'
firefly_delete_old_versions: true
firefly_link_storage: '/data'
firefly_proxy_hostname: 'firefly.pufky.com'
```

site.yml
``` yaml
- name:   'firefly server'
  hosts:  'firefly.example.com'
  become: true
  roles:
     - 'r_pufky.firefly'
```

## Issues
Create a bug and provide as much information as possible.

Associate pull requests with a submitted bug.

## License
[AGPL-3.0 License](https://github.com/r-pufky/ansible_firefly/blob/main/LICENSE)

## Author Information
https://keybase.io/rpufky

BLOCKING OS Distribution upgrades REQUIRE: git/php source; confirm php dependency changes.

Role Details: Updated: 2022-10-09 galaxy source service docs

Ports

---
###############################################################################
# Ports Configuration
###############################################################################
# Ports should be managed externally via an OS role.
#
# Reference:
# * https://docs.ansible.com/ansible/latest/collections/community/general/ufw_module.html

ports:
  - {proto: 'tcp', from_ip: 'any', to_port: 80, direction: 'in', comment: 'firefly http'}

Defaults

---
###############################################################################
# Firefly III Configuration
###############################################################################
# Requires a minimum of 512MB RAM.
#
# Reference:
# * https://computingforgeeks.com/setup-firefly-personal-finance-manager-on-ubuntu/
# * https://docs.firefly-iii.org/firefly-iii/installation/self_hosted/
# * https://docs.firefly-iii.org/firefly-iii/installation/upgrade/

# User that firefly will run under. Assumes externally managed.
firefly_user:  'www-data'
firefly_group: 'www-data'

# Create 'www-data' user if not detected? See: vars/main.yml.
firefly_create_user: false

# Version. Default: 'latest'. Changing to a later version will automatically
# apply an upgrade with related DB changes.
firefly_version: 'latest'

# Should old firefly installs be removed automatically on upgrade success?
firefly_delete_old_versions: true

# Force (re)create database. Data destructive. First time installs will not
# create a database and instead run database migrations when false.
firefly_create_database: false

# Link to specificed storage mount point when defined (should contain export,
# upload directories).
firefly_link_storage: '/data/storage'

# Hostname used by the proxy; so proxied requests redirect correctly.
firefly_proxy_hostname: ''

Config

---
###############################################################################
# Firefly Environment Configuration (firefly-iii/.env)
###############################################################################

# You can leave this on "local". If you change it to production most console
# commands will ask for extra confirmation. Never set it to "testing".
#
# Reference:
# * https://dev.azure.com/Firefly-III/_git/MainImage?path=%2Fentrypoint-fpm.sh
firefly_app_env: 'local'

# Set to true if you want to see debug information in error screens.
firefly_app_debug: false

# This should be your email address.
firefly_site_owner: 'mail@example.com'

# The encryption key for your sessions. Keep this very secure. Change it to a
# string of exactly 32 chars or use something like `php artisan key:generate`
# to generate it. Use vault.
# Example format: BTdYH+WjksmT5c0IX6UYB03tb2NmSGlsxDQyaDRK9rE=
firefly_app_key: ''

# Firefly III will launch using this language
firefly_default_language: 'en_US'

# The locale defines how numbers are formatted; by default this value is the
# same as whatever the language is.
firefly_default_locale: 'equal'

# Change this value to your preferred time zone.
firefly_tz: 'America/Los_Angeles'

# TRUSTED_PROXIES is a useful variable when using a reverse proxy.
# Set it to ** and reverse proxies work just fine.
firefly_trusted_proxies: ''

# The log channel defines where your log entries go to.
# Several other options exist. You can use 'single' for one error log (not
# recommended). Also available are 'syslog', 'errorlog' and 'stdout' which will
# log to the system itself. A rotating log option is 'daily', creates 5 files
# that rotate. Default setting 'stack' will log to 'daily' and to 'stdout' at
# the same time.
firefly_log_channel: 'stack'

# Log level. You can set this from least severe to most severe:
# debug, info, notice, warning, error, critical, alert, emergency
# If you set it to debug your logs will grow large, and fast. If you set it to
# emergency probably nothing will get logged, ever.
firefly_app_log_level: 'notice'

# Audit log level; set to "emergency" if you dont want to store audit logs.
# leave on info otherwise.
firefly_audit_log_level: 'info'

# Database credentials. Make sure the database exists. I recommend a dedicated
# user for Firefly III for other database types, please see the faq:
# https://docs.firefly-iii.org/support/faq
# Use "pgsql" for PostgreSQL
# Use "mysql" for MySQL and MariaDB.
# Use "sqlite" for SQLite.
firefly_db_connection: 'mysql'
firefly_db_host:       'db'
firefly_db_port:       3306
firefly_db_database:   'firefly'
firefly_db_username:   'firefly'
firefly_db_password:   'use vault for password'

# MySQL supports SSL. You can configure it here.
firefly_mysql_use_ssl:                false
firefly_mysql_ssl_verify_server_cert: true
# You need to set at least one of these options
firefly_mysql_ssl_capath:             '/etc/ssl/certs/'
firefly_mysql_ssl_ca:                 ''
firefly_mysql_ssl_cert:               ''
firefly_mysql_ssl_key:                ''
firefly_mysql_ssl_cipher:             ''

# PostgreSQL supports SSL. You can configure it here.
firefly_pgsql_ssl_mode:      'prefer'
firefly_pgsql_ssl_root_cert: 'null'
firefly_pgsql_ssl_cert:      'null'
firefly_pgsql_ssl_key:       'null'
firefly_pgsql_ssl_crl_file:  'null'

# If you're looking for performance improvements, you could install memcached.
firefly_cache_driver:   'file'
firefly_session_driver: 'file'

# can be tcp, unix or http
firefly_redis_scheme:   'tcp'

# use only when using 'unix' for REDIS_SCHEME. Leave empty otherwise.
firefly_redis_path:     ''

# use only when using 'tcp' or 'http' for REDIS_SCHEME. Leave empty otherwise.
firefly_redis_host:     '127.0.0.1'
firefly_redis_port:     '6379'

# Use vault for password
firefly_redis_password: 'null'
# always use quotes and make sure redis db "0" and "1" exists. Otherwise change
# accordingly.
firefly_redis_db:       '0'
firefly_redis_cache_db: '1'

# Cookie settings. Should not be necessary to change these.
firefly_cookie_path:     '/'
firefly_cookie_domain:   ''
firefly_cookie_secure:   false
firefly_cookie_samesite: 'lax'

# If you want Firefly III to mail you, update these settings
# for instructions, see:
# https://docs.firefly-iii.org/advanced-installation/email
firefly_mail_mailer:     'log'
firefly_mail_host:       'null'
firefly_mail_port:       '2525'
firefly_mail_from:       'changeme@example.com'
firefly_mail_username:   'null'
firefly_mail_password:   'null'
firefly_mail_encryption: 'null'

# Other mail drivers:
firefly_mailgun_domain:  ''
firefly_mailgun_secret:  ''

# If you are on EU region in mailgun, use api.eu.mailgun.net, otherwise use
# api.mailgun.net
firefly_mailgun_endpoint: 'api.mailgun.net'
firefly_mandrill_secret:  ''
firefly_sparkpost_secret: ''

# Firefly III can send you the following messages
firefly_send_registration_mail:    true
firefly_send_error_message:        true
firefly_send_login_new_ip_warning: true

# These messages contain (sensitive) transaction information:
firefly_send_report_journals:      true

# Set a Mapbox API key here (see mapbox.com) so there might be a map available
# at various places.
# DEPRECATED: It is no longer necessary to set this value, it will be removed.
firefly_mapbox_api_key: ''

# Instead of the mapbox API key, just set this value to true if you want to set
# the location of certain things, like transactions. Since this involves an
# external service, it's optional and disabled by default.
firefly_enable_external_map: false

# The map will default to this location:
firefly_map_default_lat:  51.983333
firefly_map_default_long: 5.916667
firefly_map_default_zoom: 6

# Firefly III has two options for user authentication. "eloquent" is the
# default, and "ldap" for LDAP servers.
# For full instructions on these settings please visit:
# https://docs.firefly-iii.org/advanced-installation/authentication
firefly_login_provider: 'eloquent'

# It's also possible to change the way users are authenticated. You could use
# Authelia for example. Authentication via the REMOTE_USER header is supported.
# Change the value below to "remote_user_guard". This will also allow Windows
# SSO.
#
# If you do this please read the documentation for instructions and warnings:
# https://docs.firefly-iii.org/advanced-installation/authentication
firefly_authentication_guard: 'web'

# If the guard is changed, Firefly III uses the 'REMOTE_USER' header as per RFC
# 3875. You can also use another header, like AUTH_USER when using Windows SSO.
# Some systems use X-Auth headers. In that case, use HTTP_X_AUTH_USERNAME or
# HTTP_X_AUTH_EMAIL. Depending on your system, REMOTE_USER may need to be
# changed to HTTP_REMOTE_USER.
#
# If this header is 'unexpectedly empty', check out the documentation.
# https://docs.firefly-iii.org/advanced-installation/authentication
firefly_authentication_guard_header: 'REMOTE_USER'

# Firefly III uses email addresses as user identifiers. When you're using an
# external authentication guard that doesn't do this, Firefly III is incapable
# of emailing you. Messages sent to "Bill Gates" always fail.
#
# However, if you set this value, Firefly III will store the value from this
# header as the user's backup email address and use it to communicate. So user
# "Bill Gates" could still have the email address "bill@microsoft.com".
#
# example value: firefly_authentication_guard_email: 'HTTP_X_AUTH_EMAIL'
firefly_authentication_guard_email:  ''

# It's impossible to log out users who's authentication is handled by an
# external system. Enter a custom URL here that will force a logout (your
# authentication provider can tell you). setting this variable only works when
# authentication_guard != web
firefly_custom_logout_uri: ''

# LDAP connection configuration: OpenLDAP, FreeIPA or ActiveDirectory
firefly_adldap_connection_scheme: 'OpenLDAP'
firefly_adldap_auto_connect:      true

# LDAP connection settings.
firefly_adldap_controllers:      ''
firefly_adldap_port:             389
firefly_adldap_timeout:          5
firefly_adldap_basedn:           ''
firefly_adldap_follow_refferals: false

# SSL/TLS settings
firefly_adldap_use_ssl:          false
firefly_adldap_use_tls:          false
firefly_adldap_ssl_cacertdir:    ''
firefly_adldap_ssl_cacertfile:   ''
firefly_adldap_ssl_certfile:     ''
firefly_adldap_ssl_keyfile:      ''
firefly_adldap_ssl_cipher_suite: ''
firefly_adldap_ssl_require_cert: ''
firefly_adldap_admin_username:   ''
firefly_adldap_admin_password:   ''
firefly_adldap_account_prefix:   ''
firefly_adldap_account_suffix:   ''

# LDAP authentication settings.
firefly_adldap_password_sync:        false
firefly_adldap_login_fallback:       false

firefly_adldap_discover_field:       'distinguishedname'
firefly_adldap_auth_field:           'distinguishedname'

# field to sync as local username.
firefly_adldap_sync_field:           'userprincipalname'

# You can disable the X-Frame-Options header if it interferes with tools like
# Organizr. This is at your own risk. Applications running in frames run the
# risk of leaking information to their parent frame.
firefly_disable_frame_header:        false

# You can disable the Content Security Policy header when you're using an
# ancient browser or any version of Microsoft Edge / Internet Explorer (which
# amounts to the same thing really) This leaves you with the risk of not being
# able to stop XSS bugs should they ever surface. This is at your own risk.
firefly_disable_csp_header:          false

# If you wish to track your own behavior over Firefly III, set valid analytics
# tracker information here. Do not prepend the TRACKER_URL with http:// or
# https:// The only tracker supported is Matomo.
firefly_tracker_site_id:             ''
firefly_tracker_url:                 ''

# Firefly III can collect telemetry on how you use Firefly III. This is opt-in.
# In order to allow this, change the following variable to true. To read more
# about this feature, see: https://docs.firefly-iii.org/support/telemetry
firefly_send_telemetry:              false

# Firefly III supports webhooks. These are security sensitive and must be
# enabled manually first.
firefly_allow_webhooks:              false

# Use this at your own risk. Disabling certain checks and features may result in
# lost of inconsistent data. However if you know what you're doing you can
# significantly speed up container start times. Set each value to true to
# enable, or false to disable.

# Check if the SQLite database exists. Can be skipped if you're not using
# SQLite. Won't significantly speed up things.
firefly_dkr_check_sqlite:            true

# Run database creation and migration commands. Disable this only if you're
# 100% sure the DB exists and is up to date.
firefly_dkr_run_migration:           true

# Run database upgrade commands. Disable this only when you're 100% sure your DB
# is up-to-date with the latest fixes (outside of migrations!)
firefly_dkr_run_upgrade:             true

# Verify database integrity. Includes all data checks and verifications.
# Disabling this makes Firefly III assume your DB is intact.
firefly_dkr_run_verify:              true

# Run database reporting commands. When disabled, Firefly III won't go over your
# data to report current state. Disabling this should have no impact on data
# integrity or safety but it won't warn you of possible issues.
firefly_dkr_run_report:              true

# Generate OAuth2 keys. When disabled, Firefly III won't attempt to generate
# OAuth2 Passport keys. This won't be an issue, if and only if you had
# previously generated keys already and they're stored in your database for
# restoration.
firefly_dkr_run_passport_install:    true

# Leave the following configuration vars as is. Unless you like to tinker and
# know what you're doing.
firefly_app_name:           'FireflyIII'
firefly_adldap_connection:  'default'
firefly_broadcast_driver:   'log'
firefly_queue_driver:       'sync'
firefly_cache_prefix:       'firefly'
firefly_pusher_key:         ''
firefly_ipinfo_token:       ''
firefly_pusher_secret:      ''
firefly_pusher_id:          ''
firefly_demo_username:      ''
firefly_demo_password:      ''
firefly_is_heroku:          false
firefly_firefly_iii_layout: 'v1'

# This variable is ONLY used in some of the emails Firefly III sends around.
# Nowhere else. So when configuring anything WEB related this variable doesn't
# do anything.
firefly_app_url: 'http://localhost'