Setting up a Firefly III cronjob: creating recurring transactions

Setup

Step by step

1. Pick a token

   The simplest way: open your profile in Firefly III (/profile) and copy the value under "Command line token". Alternatively, set STATIC_CRON_TOKEN in your .env or in the container environment. This value must be exactly 32 characters long, otherwise Firefly III does not accept it. After changing the .env, restart the application.

   STATIC_CRON_TOKEN=abcdefghij0123456789abcdefghij01

2. Check the address in a browser once

   The token belongs in the path, not as a parameter behind it. A JSON response with sections such as recurring_transactions, auto_budgets and bill_notifications is correct. On the first run they show "job_fired": true.

   https://your-domain.com/api/v1/cron/abcdefghij0123456789abcdefghij01

3. Create an account at Cronjob.de

   Registration takes a minute and is free. Five cronjobs stay free forever, the first 14 days run on the Unlimited plan.

   Start for free 14 days of Unlimited included, no payment details

4. Create the cronjob, once a day

   The examples in the Firefly III docs run daily at 3 am. The day's recurring transactions are then in the account early in the morning. You can also just type "every day at 3 am" and the schedule is set for you.

   0 3 * * *

   You can enter this expression at Cronjob.de exactly as it is – the schedule field understands crontab notation. But you do not have to know it: simply click the schedule together instead.

5. Switch on error notifications

   Enter an email address under Notifications. In a household overview a missing transaction otherwise often only surfaces at reconciliation. Failure notifications by email are included from the Plus plan, and free during the first 14 days.

What the five fields of an expression like */5 * * * * mean is explained in the crontab reference – with examples and the most common pitfalls. You can build the expression in the crontab generator. Whether you need an outside service at all is shown in the comparison of the three ways.

Verification

Is it actually running?

In Firefly III open the recurring transactions page. If the note that the cron job has never run, or not for over 36 hours, is gone, the call is arriving. From Plus, the Cronjob.de call log also shows the JSON response with "job_fired" and "job_succeeded" for each part.

FAQ

Common questions about Firefly III

How often does the Firefly III cronjob have to run?

Once a day. All examples in the official docs use 0 3 * * *, i.e. 3 am. More often gains nothing: if the last run was less than twelve hours ago, Firefly III skips the recurring transactions, for example, and reports "job_fired": false.

What happens with two calls shortly after each other?

Nothing is duplicated. Firefly III remembers the time of the last run and only runs the recurring transactions again after twelve hours at the earliest. The docs also say it is fine if several users set up their own cron runs.

My STATIC_CRON_TOKEN is not accepted.

Usually the length is wrong. It has to be exactly 32 characters. Also check that the environment variable actually reached the container after the restart. For a test you can use the "Command line token" from your profile; if that works, the problem is the static token.

Is the token in the address not insecure?

The token in the address is the route Firefly III provides for this. According to the docs it prevents others from calling your cron address at will. Treat it like a password and only call the address over https.

I get a 404 on the address.

Then the installation sits in a subfolder, or the web server does not pass the path on to Firefly III. First check whether the normal Firefly III interface is reachable under the same address, then append /api/v1/cron/ with the token.

Do I need this for the Data Importer as well?

The Data Importer is a separate service. For automatic imports it has its own addresses such as /autoimport, called by POST. It needs its own secret in AUTO_IMPORT_SECRET (at least 16 characters) and further settings according to its docs. If you use it, set up a second cronjob for it.