Skip to content
BSWEN
Blog

How to Set Up Firefly III Automatic Bank Sync with SimpleFIN

Cowrie
Cowrie
Dev @ Bswen

Problem

Manual transaction entry in personal finance software is tedious. I tried keeping up with daily expenses in Firefly III, but the friction was real:

  • Logging into multiple bank accounts to download CSVs
  • Importing and deduplicating transactions manually
  • Categorizing hundreds of transactions each month
  • Forgetting to track small purchases entirely

After two weeks of enthusiasm, I abandoned the effort. My budget was only as good as my memory - which is to say, not very good.

The real problem: personal finance tools require consistent input to be useful, but consistent input requires effort that scales linearly with every account and transaction.

Environment

I run Firefly III in Docker on my home server. Here’s my setup:

docker-compose.yml
version: '3.8'


services:
  fireflyiii:
    image: fireflyiii/core:latest
    container_name: fireflyiii
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - APP_KEY=SomeRandomStringOf32CharsExactly
      - APP_URL=http://localhost:8080
      - TRUSTED_PROXIES=**
      - DB_CONNECTION=pgsql
      - DB_HOST=db
      - DB_PORT=5432
      - DB_DATABASE=firefly
      - DB_USERNAME=firefly
      - DB_PASSWORD=secret_password
    volumes:
      - firefly_iii_upload:/var/www/html/storage/upload
    depends_on:
      - db


  db:
    image: postgres:15
    container_name: fireflyiii-db
    restart: unless-stopped
    environment:
      - POSTGRES_DB=firefly
      - POSTGRES_USER=firefly
      - POSTGRES_PASSWORD=secret_password
    volumes:
      - firefly_iii_db:/var/lib/postgresql/data


volumes:
  firefly_iii_upload:
  firefly_iii_db:

This gets Firefly III running, but transactions still need to be entered manually. That’s where SimpleFIN Bridge comes in.

Solution

SimpleFIN Bridge connects Firefly III to your bank accounts through the SimpleFIN cloud service. The architecture looks like this:

Architecture Overview
[Banks] --> [SimpleFIN Cloud] --> [SimpleFIN Bridge (Docker)] --> [Firefly III (Docker)]

Your bank data flows through SimpleFIN’s secure cloud to standardize the format, then into your locally-hosted SimpleFIN Bridge, which pushes transactions to Firefly III. Your data stays on your infrastructure after the initial sync.

Step 1: Deploy SimpleFIN Bridge

Add SimpleFIN Bridge to your Docker Compose:

docker-compose.yml (addition)
  simplefin:
    image: aperfco/simplefin:latest
    container_name: simplefin-bridge
    restart: unless-stopped
    ports:
      - "8081:8080"
    environment:
      - BASE_URL=https://beta.simplefin.org
      - MANAGER_URL=https://beta.simplefin.org
    volumes:
      - simplefin_data:/app/data
    depends_on:
      - fireflyiii


volumes:
  simplefin_data:

Step 2: Connect Your Bank Accounts

  1. Create an account at SimpleFIN
  2. In the SimpleFIN Bridge UI (http://localhost:8081), authenticate with your SimpleFIN account
  3. Add your bank credentials through SimpleFIN’s secure connection flow
  4. Map each bank account to the corresponding Firefly III account

SimpleFIN supports thousands of financial institutions. I connected 13 accounts: checking accounts, credit cards, savings, and investment accounts (RRSP, LIRA, TFSA).

Step 3: Configure Scheduled Syncs

The key insight: sync frequency should match your spending patterns. I set up twice-daily syncs using a simple cron job:

sync script
#!/bin/bash
# /opt/firefly/sync.sh


# Morning sync at 6 AM
# Evening sync at 6 PM


curl -X POST http://simplefin-bridge:8080/sync
crontab
# Sync transactions twice daily
0 6,18 * * * /opt/firefly/sync.sh >> /var/log/firefly-sync.log 2>&1

With 2x daily syncs, I rarely wait more than 12 hours for transactions to appear.

Step 4: Set Up Auto-Categorization Rules

This is the critical gotcha: auto-categorization rules are what make automation actually hands-off.

Without rules, you’ll have automatic transactions but still need to categorize everything manually. I created 65+ rules covering:

  • Recurring bills (Netflix, utilities, subscriptions)
  • Common merchants (grocery stores, gas stations)
  • Income sources (salary, transfers)
  • Investment transactions

Here’s how to create a rule in Firefly III:

  1. Navigate to Rules > Create new rule
  2. Set trigger conditions (description contains “Netflix”)
  3. Set actions (set category to “Entertainment”)
Example Rules Structure
Rule 1: Netflix Subscription
  Trigger: description contains "NETFLIX"
  Action: set category "Entertainment"
  Action: set budget "Fun Money"


Rule 2: Grocery Store
  Trigger: description contains "WHOLE FOODS" OR "TRADER JOE" OR "COSTCO"
  Action: set category "Groceries"
  Action: set budget "Food"


Rule 3: Gas Station
  Trigger: description matches regex /^(SHELL|CHEVRON|76|MOBIL)/
  Action: set category "Transportation"
  Action: set budget "Auto"

The regex-based rules are powerful for catching variations in merchant names.

Step 5: (Optional) Add Visualization with InfluxDB and Grafana

For deeper insights, I push Firefly III data to InfluxDB and visualize in Grafana:

docker-compose.yml (visualization addition)
  influxdb:
    image: influxdb:2.7
    container_name: influxdb
    restart: unless-stopped
    ports:
      - "8086:8086"
    volumes:
      - influxdb_data:/var/lib/influxdb2


  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana


volumes:
  influxdb_data:
  grafana_data:

I wrote a Python script that queries Firefly III’s API and pushes metrics to InfluxDB every hour. Now I can answer questions like:

  • “How much did I spend on restaurants this month?”
  • “Am I over budget on AI tools?”
  • “Summarize my top 5 expense categories for Q1 2026”

Key Insights

After running this setup for 50 days, here’s what I learned:

1. Sync frequency matters for cash flow awareness. Twice daily is enough for most use cases. Real-time would be overkill and might hit rate limits.

2. Rules need maintenance. New merchants appear, subscription names change. I review my categorization rules monthly and add 2-3 new ones.

3. The initial setup takes time. Connecting accounts and creating rules took me about 2 hours. But that’s a one-time cost that pays dividends indefinitely.

4. Privacy is preserved. Transaction data only leaves my network during the SimpleFIN sync. After that, it stays local.

5. Budget tracking finally works. With automatic categorization, I can set budgets and actually track against them without manual effort.

Summary

Setting up automatic bank sync between Firefly III and SimpleFIN Bridge eliminates the friction of manual transaction entry. The key components:

  • Docker deployment for both services with persistent volumes
  • SimpleFIN Bridge as the connector between banks and Firefly III
  • Scheduled syncs (2x daily works well) via cron
  • Auto-categorization rules to make the automation truly hands-off
  • Optional visualization with InfluxDB and Grafana for advanced analytics

The result: I track 13 accounts across checking, savings, credit cards, and investments with zero manual entry. 65+ categorization rules handle the heavy lifting. Budget tracking finally works because the data is accurate and current.

The upfront investment was about 2 hours. The return is permanent: a personal finance system that actually reflects reality.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: