# Firefly-iii Service {#services-firefly-iii}

Defined in [`/modules/services/firefly-iii.nix`](@REPO@/modules/services/firefly-iii.nix).

This NixOS module is a service that sets up a [Firefly-iii](https://www.firefly-iii.org/) instance.

Compared to the stock module from nixpkgs,
this one sets up, in a fully declarative manner,
LDAP and SSO integration
and has a nicer option for secrets.
It also sets up the Firefly-iii data importer service
and nearly automatically links it to the Firefly-iii instance using a Personal Account Token.
Instructions on how to do so is given in the next section.

## Features {#services-firefly-iii-features}

- Integration with the [dashboard contract](contracts-dashboard.html) for displaying user facing application in a dashboard. [Manual](#services-firefly-iii-usage-applicationdashboard)

## Usage {#services-firefly-iii-usage}

### Initial Configuration {#services-firefly-iii-usage-configuration}

The following snippet assumes a few blocks have been setup already:

- the [secrets block](usage.html#usage-secrets) with SOPS,
- the [`shb.ssl` block](blocks-ssl.html#usage),
- the [`shb.lldap` block](blocks-lldap.html#blocks-lldap-global-setup).
- the [`shb.authelia` block](blocks-authelia.html#blocks-sso-global-setup).

```nix
shb.firefly-iii = {
  enable = true;
  debug = false;

  appKey.result = config.shb.sops.secret."firefly-iii/appKey".result;
  dbPassword.result = config.shb.sops.secret."firefly-iii/dbPassword".result;

  domain = "example.com";
  subdomain = "firefly-iii";
  siteOwnerEmail = "mail@example.com";
  ssl = config.shb.certs.certs.letsencrypt.${domain};

  smtp = {
    host = "smtp.eu.mailgun.org";
    port = 587;
    username = "postmaster@mg.example.com";
    from_address = "firefly-iii@example.com";
    password.result = config.shb.sops.secret."firefly-iii/smtpPassword".result;
  };

  sso = {
    enable = true;
    authEndpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
  };

  importer = {
    # See note hereunder.
    # firefly-iii-accessToken.result = config.shb.sops.secret."firefly-iii/importerAccessToken".result;
  };
};
shb.sops.secret."firefly-iii/appKey".request = config.shb.firefly-iii.appKey.request;
shb.sops.secret."firefly-iii/dbPassword".request = config.shb.firefly-iii.dbPassword.request;
shb.sops.secret."firefly-iii/smtpPassword".request = config.shb.firefly-iii.smtp.password.request;
# See not hereunder.
# shb.sops.secret."firefly-iii/importerAccessToken".request = config.shb.firefly-iii.importer.firefly-iii-accessToken.request;
```

Secrets can be randomly generated with `nix run nixpkgs#openssl -- rand -hex 64`.
Note that for `appKey`, the secret length must be exactly 32 characters.

The [user](#services-firefly-iii-options-shb.firefly-iii.ldap.userGroup)
and [admin](#services-firefly-iii-options-shb.firefly-iii.ldap.adminGroup)
LDAP groups are created automatically.
Only admin users have access to the Firefly-iii data importer.
On the Firefly-iii web UI, the first user to login will be the admin.
We cannot yet create multiple admins in the Firefly-iii web UI.

On first start, leave the `shb.firefly-iii.importer.firefly-iii-accessToken` option empty.
To fill it out and connect the data importer to the Firefly-iii instance,
you must first create a personal access token then fill that option and redeploy.

### Backup {#services-firefly-iii-usage-backup}

Backing up Firefly-iii using the [Restic block](blocks-restic.html) is done like so:

```nix
shb.restic.instances."firefly-iii" = {
  request = config.shb.firefly-iii.backup;
  settings = {
    enable = true;
  };
};
```

The name `"firefly-iii"` in the `instances` can be anything.
The `config.shb.firefly-iii.backup` option provides what directories to backup.
You can define any number of Restic instances to backup Firefly-iii multiple times.

You will then need to configure more options like the `repository`,
as explained in the [restic](blocks-restic.html) documentation.

### Certificates {#services-firefly-iii-certs}

For Let's Encrypt certificates, add:

```nix
{
  shb.certs.certs.letsencrypt.${domain}.extraDomains = [
    "${config.shb.firefly-iii.subdomain}.${config.shb.firefly-iii.domain}"
    "${config.shb.firefly-iii.importer.subdomain}.${config.shb.firefly-iii.domain}"
  ];
}
```

### Impermanence {#services-firefly-iii-impermanence}

To save the data folder in an impermanence setup, add:

```nix
{
  shb.zfs.datasets."safe/firefly-iii".path = config.shb.firefly-iii.impermanence;
}
```

### Declarative LDAP {#services-firefly-iii-declarative-ldap}

To add a user `USERNAME` to the user and admin groups for Firefly-iii, add:

```nix
shb.lldap.ensureUsers.USERNAME.groups = [
  config.shb.firefly-iii.ldap.userGroup
  config.shb.firefly-iii.ldap.adminGroup
];
```

### Application Dashboard {#services-firefly-iii-usage-applicationdashboard}

Integration with the [dashboard contract](contracts-dashboard.html) is provided
by the [dashboard option](#services-firefly-iii-options-shb.firefly-iii.dashboard).

For example using the [Homepage](services-homepage.html) service:

```nix
{
  shb.homepage.servicesGroups.Finance.services.Firefly-iii = {
    sortOrder = 1;
    dashboard.request = config.shb.firefly-iii.dashboard.request;
    settings.widget.type = "firefly";
  };
}
```

The widget type needs to be set manually otherwise it is not displayed correctly.

An API key can be set to show extra info:

```nix
{
  shb.homepage.servicesGroups.Finance.services.Firefly-iii = {
    apiKey.result = config.shb.sops.secret."firefly-iii/homepageApiKey".result;
  };

  shb.sops.secret."firefly-iii/homepageApiKey".request =
    config.shb.homepage.servicesGroups.Finance.services.Firefly-iii.apiKey.request;
}
```

## Database Inspection {#services-firefly-iii-database-inspection}

Access the database with:

```nix
sudo -u firefly-iii psql
```

Dump the database with:

```nix
sudo -u firefly-iii pg_dump --data-only --inserts firefly-iii > dump
```

## Mobile Apps {#services-firefly-iii-mobile}

This module was tested with the [Abacus iOS](https://github.com/victorbalssa/abacus) mobile app
using a Personal Account Token.

## Options Reference {#services-firefly-iii-options}

```{=include=} options
id-prefix: services-firefly-iii-options-
list-id: selfhostblocks-service-firefly-iii-options
source: @OPTIONS_JSON@
```