Skip to main content

Firefly III with Docker Compose

Firefly III runs as one container (fireflyiii/core, port 8080) next to a database. It needs a 32-character APP_KEY, a persistent volume for uploads at /var/www/html/storage/upload, and a daily cron call for recurring transactions, auto-budgets, subscription warnings and exchange rates. The official Compose file uses MariaDB. Firefly III also works with MySQL, PostgreSQL and SQLite.

Below is a minimal Compose setup, then the one-click template on Hostim.

If you're new to Docker Compose, check out our guide on how to self-host a Docker Compose app. More stacks are in our Docker Compose library.

Self-host Firefly III with Docker Compose (minimal)​

This follows the official firefly-iii/docker repository: one app container, one MariaDB container and one small cron container.

services:
  app:
    image: fireflyiii/core:latest
    restart: always
    ports:
      - "80:8080"
    environment:
      - APP_KEY=CHANGE_ME_TO_EXACTLY_32_CHARS_00 # exactly 32 characters
      - APP_URL=http://localhost
      - TRUSTED_PROXIES=**
      - TZ=Europe/Berlin
      - STATIC_CRON_TOKEN=CHANGE_ME_ALSO_EXACTLY_32_CHARS0 # exactly 32 characters
      - DB_CONNECTION=mysql
      - DB_HOST=db
      - DB_PORT=3306
      - DB_DATABASE=firefly
      - DB_USERNAME=firefly
      - DB_PASSWORD=changeme
    volumes:
      - firefly_upload:/var/www/html/storage/upload
    depends_on:
      - db

  db:
    image: mariadb:lts
    restart: always
    environment:
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
      - MYSQL_DATABASE=firefly
      - MYSQL_USER=firefly
      - MYSQL_PASSWORD=changeme
    volumes:
      - firefly_db:/var/lib/mysql

  cron:
    image: alpine
    restart: always
    environment:
      - STATIC_CRON_TOKEN=CHANGE_ME_ALSO_EXACTLY_32_CHARS0 # same value as the app
    command: ["sh", "-c", "echo \"0 3 * * * wget -qO- http://app:8080/api/v1/cron/$$STATIC_CRON_TOKEN\" | crontab - && crond -f -L /dev/stdout"]
    depends_on:
      - app

volumes:
  firefly_upload:
  firefly_db:

🔑 Generate both 32-character values with tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32; echo. APP_KEY must not change after the first start, or Firefly III cannot read its encrypted data.

Deploy Firefly III on Hostim.dev (One-Click)​

Firefly III is a free, open-source personal finance manager. It tracks accounts, budgets, bills and recurring transactions, and has a full REST API. On Hostim.dev the template deploys Firefly III with a managed MySQL database and a persistent volume for uploads, with HTTPS on a free subdomain.

Try it Yourself

Guest project runs for 1 hour. Log in to save and extend to 5 days.

What's included​

ResourceDetails
Appfireflyiii/core image
DatabaseManaged MySQL
Volume/var/www/html/storage/upload
DomainFree *.hostim.dev subdomain
SSLLet’s Encrypt (auto-enabled)
Port8080

How to Deploy​

  1. Go to your Hostim.dev dashboard.
  2. Click Create Project → Use a Template.
  3. Select Firefly III.
  4. Choose a resource plan.
  5. Deploy.

APP_URL, APP_KEY, STATIC_CRON_TOKEN and the database connection are set automatically.

First login​

Open /register on your app URL and create the first user. This user becomes the admin. The password must be at least 16 characters.

Daily cron job​

Recurring transactions, auto-budgets, subscription warnings and exchange rates only run when something calls the cron endpoint once a day. The template does not include a cron container. Set up the call yourself:

  1. In the Hostim dashboard, open the firefly app and copy the value of STATIC_CRON_TOKEN from its environment variables.
  2. Call this URL once a day from any scheduler (a cron job on your own machine, a scheduled GitHub Actions workflow, or a free web cron service):
curl -fsS https://<your-app-domain>/api/v1/cron/<STATIC_CRON_TOKEN>

A successful call returns HTTP 200 and a JSON summary. Keep the token secret: anyone with the URL can trigger the job. One call runs the job for all users.

FAQ​

Frequently asked questions

Which database does Firefly III need?

Firefly III works with MySQL, MariaDB, PostgreSQL and SQLite. The official Docker Compose file uses MariaDB. The Hostim template uses a managed MySQL database.

How long must the Firefly III APP_KEY be?

Exactly 32 characters. Generate it once and never change it, because Firefly III uses it to encrypt data. On Hostim the key is generated for you.

What does the Firefly III cron job do?

It runs recurring transactions, auto-budgets, subscription (bill) warnings and exchange-rate updates. Without a daily call to /api/v1/cron/<token>, those features do nothing.

What is STATIC_CRON_TOKEN in Firefly III?

A fixed 32-character token that lets an external scheduler call the cron URL without logging in. The alternative is the personal 'Command line token' from the /profile page.

Why does Firefly III reject my password at registration?

Firefly III requires passwords of at least 16 characters. Shorter passwords send you back to the /register page with an error.

Where does Firefly III store uploaded files?

Attachments are stored in /var/www/html/storage/upload inside the container. All other data is in the database. Back up both.

How do I update Firefly III in Docker?

Pull the newer fireflyiii/core image and recreate the container. Database migrations run at container start. On Hostim, redeploy the app to pull the latest image.

Alternatives​

  • Actual Budget — local-first envelope budgeting (guide)
  • Sure — privacy-first personal finance and budgeting app (guide)

Source + Docs​

Looking for something else? Browse all templates →

Try it now​

Deploy Firefly III Now – in less than 60 seconds