Firefly III on AWS User Guide

Overview

Firefly III is an open source self-hosted personal finance manager. It uses double-entry bookkeeping to give you a precise, honest picture of your money: where it comes from, where it goes, and what is left. You record expenses and income, organise them into budgets, categories and tags, set savings goals with piggy banks, and let automatic rules tidy everything up, all while keeping your financial data private on infrastructure you control. This image runs Firefly III, a Laravel application, behind nginx with PHP FPM 8.5 and OPcache enabled.

Firefly III stores its data in SQLite, so the appliance is fully self-contained: there is no separate database server to install, secure or back up. The application code, configuration, the SQLite database, uploads and storage live under /var/www/firefly-iii on a dedicated, independently resizable EBS volume, so you can grow your finance store without touching the operating system disk. The database schema is migrated and seeded in the image, so Firefly III is ready the moment the instance boots.

The application encryption key and the cron token are generated on the first boot of every deployed instance, and a fresh administrator password is set at the same time. Two instances launched from the same Amazon Machine Image never share credentials. The initial administrator email and password are written to /root/firefly-iii-credentials.txt with mode 0600 so that only the root user can read it.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users will reach Firefly III from
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Firefly III. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users will use. Leave the root and data volumes at their default sizes or larger.

Select Launch instance. First boot initialisation takes approximately one minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Firefly III Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=firefly-iii-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve Initial Credentials

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

For the Ubuntu 24.04 variant, connect with ssh -i <path-to-key.pem> ubuntu@<instance-public-ip>.

Firefly III generates a unique administrator password on first boot and writes it, along with the administrator email, to a root only file. Retrieve it with:

sudo cat /root/firefly-iii-credentials.txt

The file lists the administrator email (admin@example.com), the generated password, and the instance URL. This account is the owner of the Firefly III installation. Keep these credentials somewhere safe and change the password after your first sign in.

You can confirm the web server and PHP FPM are running, that the data volume is mounted, and that Firefly III answers on port 80, with the following checks.

systemctl is-active nginx php8.5-fpm

df -h /var/www/firefly-iii | tail -1

curl -s -o /dev/null -w 'Firefly III login HTTP %{http_code}\n' http://127.0.0.1/login

Each command should report the service as active, show the dedicated data volume mounted at /var/www/firefly-iii, and return HTTP 200 for the login page.

Step 4: Sign In to Firefly III

Open a web browser and browse to the instance address:

http://<instance-public-ip>/

You are taken to the Firefly III sign-in page. Enter the administrator email and the password from /root/firefly-iii-credentials.txt and select Sign in.

The first time you sign in, Firefly III shows a short welcome screen that asks for the name of your bank and the balance of your main checking account. Enter those details, or accept the defaults, and select Submit to reach the dashboard.

Step 5: Create Accounts, Budgets and Transactions

The dashboard summarises your net worth, your spending for the current period, and the balances of your asset accounts. From the left hand menu you can:

• Open Accounts to manage your asset accounts (checking, savings, cash), expense accounts (the shops and services you pay), revenue accounts (your sources of income) and liabilities (loans, credit cards).
• Open Budgets to set monthly spending limits per category and track how much you have left to spend.
• Open Transactions to record withdrawals, deposits and transfers. Because Firefly III is double-entry, every transaction moves money from one account to another, which is what keeps your net worth accurate.
• Open Piggy banks to set savings goals and allocate money towards them.

To change the administrator password, select the email address at the top right of any page, choose Profile, and update the password under the Change your password section.

Step 6: Enable Recurring Transactions (Cron)

Firefly III runs recurring transactions and other scheduled work through a command that is triggered by a cron token. A unique STATIC_CRON_TOKEN is generated on first boot and stored in the application environment file at /var/www/firefly-iii/.env. To run the scheduled tasks once per day, add a cron entry on the instance that calls the Firefly III cron endpoint with that token.

Retrieve the token value with:

sudo grep '^STATIC_CRON_TOKEN=' /var/www/firefly-iii/.env

Then add a daily cron entry (for example using sudo crontab -e) that requests http://localhost/cron/<token> once per day, replacing <token> with the value above. Recurring transactions and bill reminders are not required for day to day use, so you can defer this step until you start using those features.

Step 7: Enable HTTPS with Let's Encrypt

The image serves Firefly III over HTTP on port 80 so that it works immediately behind the instance's public address. For production use you should put it behind HTTPS. The simplest approach is to point a DNS name at the instance and use Certbot.

Install Certbot and the nginx plugin, then request a certificate for your domain. Replace your-domain.example.com with the DNS name that resolves to the instance:

sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx

After the packages are installed, run sudo certbot --nginx -d your-domain.example.com and follow the prompts. Certbot obtains a certificate, updates the nginx configuration to serve Firefly III over HTTPS, and sets up automatic renewal. Once HTTPS is working, update APP_URL in /var/www/firefly-iii/.env to the https:// address and run sudo -u www-data php /var/www/firefly-iii/artisan config:cache so Firefly III generates correct links.

Step 8: Back Up and Maintain Your Instance

All of Firefly III's data is contained in the SQLite database and the application tree on the dedicated /var/www/firefly-iii volume. To back up your finances, either snapshot the EBS data volume with the AWS Console or CLI, or copy the SQLite database file at /var/www/firefly-iii/storage/database/database.sqlite to a safe location.

To take an EBS snapshot, find the volume ID attached to the instance and create a snapshot:

aws ec2 create-snapshot --volume-id <data-volume-id> --description "Firefly III data backup"

Apply operating system security updates regularly with sudo apt-get update && sudo apt-get upgrade. Because the data lives on its own volume, you can resize it independently in the AWS Console if your finance store grows.

Architecture Summary

Support

This image is published and supported by cloudimg. Support covers Firefly III deployment, upgrades, importing data, budgeting rules, performance tuning, and storage administration, 24/7 by email and chat. For help, contact cloudimg support through the channel listed on your AWS Marketplace subscription.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.