ansible/roles/firefly/README.md

# Ansible Role Firefly

Ansible role to manage a [Firefly III](https://firefly-iii.org/) instance.

## Table of content

<!-- ANSIBLE DOCSMITH TOC START -->
* [Role variables](#variables)
  * [`firefly_version`](#variable-firefly_version)
  * [`firefly_port`](#variable-firefly_port)
  * [`firefly_static_cron_token`](#variable-firefly_static_cron_token)
  * [`firefly_home`](#variable-firefly_home)
  * [`firefly_site_owner`](#variable-firefly_site_owner)
  * [`firefly_app_key`](#variable-firefly_app_key)
  * [`firefly_language`](#variable-firefly_language)
  * [`firefly_tz`](#variable-firefly_tz)
  * [`firefly_db_database`](#variable-firefly_db_database)
  * [`firefly_db_username`](#variable-firefly_db_username)
  * [`firefly_db_password`](#variable-firefly_db_password)
  * [`firefly_manage_iptables`](#variable-firefly_manage_iptables)
  * [`firefly_allowed_sources`](#variable-firefly_allowed_sources)
<!-- ANSIBLE DOCSMITH TOC END -->
<!-- ANSIBLE DOCSMITH MAIN START -->

## Role variables<a id="variables"></a>

The following variables can be configured for this role:

| Variable | Type | Required | Default | Description (abstract) |
|----------|------|----------|---------|------------------------|
| `firefly_version` | `str` | No | `"latest"` | Version of the docker image. |
| `firefly_port` | `int` | No | `8080` |  |
| `firefly_static_cron_token` | `str` | Yes | N/A | Token used by the cron job (sensitive). |
| `firefly_home` | `path` | No | `"/var/lib/firefly"` | Directory where to store data files. |
| `firefly_site_owner` | `str` | No | `"root@localhost"` | E-mail address of the site owner. |
| `firefly_app_key` | `str` | Yes | N/A | Application key (sensitive). |
| `firefly_language` | `str` | No | `"en_US"` | Language of the web interface. |
| `firefly_tz` | `str` | No | `"Etc/UTC"` | Time zone of the web interface. |
| `firefly_db_database` | `str` | No | `"firefly"` | Name of the database. |
| `firefly_db_username` | `str` | No | `"firefly"` | Name of the user to connect to the database. |
| `firefly_db_password` | `str` | Yes | N/A | Password to connect to the database (sensitive). |
| `firefly_manage_iptables` | `bool` | No | `false` | Configure iptables rules. |
| `firefly_allowed_sources` | `list` | No | N/A | List of IP ranges to allow when `firefly_manage_iptables` is enabled. |

### `firefly_version`<a id="variable-firefly_version"></a>

[*⇑ Back to ToC ⇑*](#toc)

Version of the docker image.

- **Type**: `str`
- **Required**: No
- **Default**: `"latest"`



### `firefly_port`<a id="variable-firefly_port"></a>

[*⇑ Back to ToC ⇑*](#toc)



- **Type**: `int`
- **Required**: No
- **Default**: `8080`



### `firefly_static_cron_token`<a id="variable-firefly_static_cron_token"></a>

[*⇑ Back to ToC ⇑*](#toc)

Token used by the cron job (sensitive).

- **Type**: `str`
- **Required**: Yes



### `firefly_home`<a id="variable-firefly_home"></a>

[*⇑ Back to ToC ⇑*](#toc)

Directory where to store data files.

- **Type**: `path`
- **Required**: No
- **Default**: `"/var/lib/firefly"`



### `firefly_site_owner`<a id="variable-firefly_site_owner"></a>

[*⇑ Back to ToC ⇑*](#toc)

E-mail address of the site owner.

- **Type**: `str`
- **Required**: No
- **Default**: `"root@localhost"`



### `firefly_app_key`<a id="variable-firefly_app_key"></a>

[*⇑ Back to ToC ⇑*](#toc)

Application key (sensitive).

- **Type**: `str`
- **Required**: Yes



### `firefly_language`<a id="variable-firefly_language"></a>

[*⇑ Back to ToC ⇑*](#toc)

Language of the web interface.

- **Type**: `str`
- **Required**: No
- **Default**: `"en_US"`



### `firefly_tz`<a id="variable-firefly_tz"></a>

[*⇑ Back to ToC ⇑*](#toc)

Time zone of the web interface.

- **Type**: `str`
- **Required**: No
- **Default**: `"Etc/UTC"`



### `firefly_db_database`<a id="variable-firefly_db_database"></a>

[*⇑ Back to ToC ⇑*](#toc)

Name of the database.

- **Type**: `str`
- **Required**: No
- **Default**: `"firefly"`



### `firefly_db_username`<a id="variable-firefly_db_username"></a>

[*⇑ Back to ToC ⇑*](#toc)

Name of the user to connect to the database.

- **Type**: `str`
- **Required**: No
- **Default**: `"firefly"`



### `firefly_db_password`<a id="variable-firefly_db_password"></a>

[*⇑ Back to ToC ⇑*](#toc)

Password to connect to the database (sensitive).

- **Type**: `str`
- **Required**: Yes



### `firefly_manage_iptables`<a id="variable-firefly_manage_iptables"></a>

[*⇑ Back to ToC ⇑*](#toc)

Configure iptables rules.

- **Type**: `bool`
- **Required**: No
- **Default**: `false`



### `firefly_allowed_sources`<a id="variable-firefly_allowed_sources"></a>

[*⇑ Back to ToC ⇑*](#toc)

List of IP ranges to allow when `firefly_manage_iptables` is enabled.

- **Type**: `list`
- **Required**: No




<!-- ANSIBLE DOCSMITH MAIN END -->

## Configuration

See [Variable
precedence](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#ansible-variable-precedence)
to find where you should put your own variables.

Then define at least `firefly_static_cron_token`, `firefly_db_password` and
`firefly_app_key` variables with a strong and secure password, encrypted using
[ansible-vault](https://docs.ansible.com/ansible/latest/cli/ansible-vault.html).

See list of [default variables](defaults/main.yml).


## Usage

Example of a basic firefly.yml playbook:

```yaml
hosts:
  - firefly

roles:
  - firefly
```

Then run the playbook:

```
ansible-playbook firefly.yml
```

## Donate

As we all love FOSS projects, you should consider [sponsoring and/or
contribute](https://github.com/firefly-iii/firefly-iii).