Firefly III on VPS: Installation, Configuration, and Maintenance

Installing Firefly III on a VPS via Docker/Docker Compose is the optimal way to gain full control over your finances, requiring a VPS with a minimum of 2 vCPU, 2 GB RAM, and a 20 GB NVMe disk, which will cost approximately $5-10 per month.

Firefly III is a powerful, open-source, self-hosted personal finance management tool. It provides detailed control over your income, expenses, budgets, and assets, allowing you to make informed financial decisions. Unlike many cloud solutions, self-hosted Firefly III guarantees complete privacy and security of your data, as it is stored on your own server. This approach is especially valuable for those who prioritize privacy and do not wish to entrust their financial data to third-party services. In this article, we will delve into how to install Firefly III on a VPS using Docker and Docker Compose, configure it for secure internet access, and ensure reliable maintenance.

What is Firefly III and why is it ideal for self-hosting on a VPS?

Firefly III is a free and open-source web platform for personal finance management. It is designed to help users track their income and expenses, plan budgets, manage assets and liabilities, and gain deep insights into their financial situation through detailed reports and graphs. The main advantage of Firefly III lies in its flexibility and full customizability to individual needs, making it an ideal candidate for deployment on your own server.

Key features and benefits of Firefly III

Firefly III offers a wide range of features that make it one of the most advanced tools for personal finance:

• Transaction Tracking: Detailed logging of all incoming and outgoing cash flows with the ability to categorize, add tags, and notes.
• Budgeting: Creation of flexible budgets for various expense categories, tracking their execution, and receiving notifications about exceeding limits.
• Account Management: Support for multiple account types (bank, cash, credit cards, savings, investments) with automatic data import from CSV, QIF, OFX, MT940 files.
• Rules and Automation: Setting up rules for automatic categorization and processing of transactions, which significantly simplifies record-keeping.
• Reports and Analytics: In-depth reports on income, expenses, net worth, balance, and budgets with clear graphs and charts.
• Planning: Ability to plan future transactions and recurring payments.
• Currency Support: Multi-currency support with conversion capabilities.
• Security: Support for two-factor authentication (2FA) for added protection.

These features, combined with its open-source nature, make Firefly III a powerful and transparent tool for financial management.

Firefly III self-hosted: complete control over your data

Choosing Firefly III self-hosted on your own VPS server provides several critical advantages compared to cloud-based or desktop solutions:

1. Data Privacy: Your financial data remains solely with you. It is not stored on third-party servers, eliminating the risk of leakage or unauthorized access by companies. This is especially important in light of growing concerns about internet privacy.
2. Full Control: You control the server, operating system, database, and the Firefly III application itself. This allows you to customize the system to your unique requirements, implement your own security measures, and manage updates as you see fit.
3. Accessibility: Deployed on a VPS, Firefly III is accessible from anywhere in the world via the internet, while you maintain full control over the infrastructure, unlike third-party cloud services.
4. Flexibility: Ability to integrate with other self-hosted services on your VPS. For example, you can use the same reverse proxy as for other applications, such as Wallabag on VPS or Karakeep on VPS.
5. No Subscriptions: After purchasing a VPS (which you can also use for other purposes), you don't need to pay monthly subscriptions for using Firefly III, making it cost-effective in the long run.

Deploying Firefly III on a server using Docker simplifies the installation and management process, isolating the application from the main system and ensuring its portability.

System requirements for Firefly III: which VPS to choose?

Choosing the right VPS server is a crucial step to ensure stable and fast operation of Firefly III. While Firefly III is not an extremely resource-intensive application for a single user, the correct VPS configuration ensures comfortable operation and scalability.

Minimum and recommended configurations for Firefly III on a server

Firefly III requires a database (PostgreSQL or MySQL/MariaDB) and a cache server (Redis), which will run in Docker containers along with the application itself. This affects the overall resource requirements.

• Minimum configuration (for a single user or a small number of transactions):
  • Processor (vCPU): 1-2 cores. Firefly III is written in PHP (Laravel), and initial setup and periodic transaction imports may require computational power.
  • RAM: 2 GB. This is sufficient for the Docker daemon, Firefly III, PostgreSQL, Redis containers, and the operating system.
  • Disk Space: 20 GB NVMe SSD. NVMe drives are significantly faster than regular SSDs, which is critical for database performance and overall system responsiveness. 20 GB is enough for the OS, Docker images, and several years of Firefly III data.
  • Operating System: Ubuntu 22.04 LTS (recommended) or another modern Linux distribution.
  • Network Bandwidth: 100 Mbps.
• Recommended configuration (for a family, active use, large volume of transactions):
  • Processor (vCPU): 2-4 cores.
  • RAM: 4 GB. This will ensure smoother operation when opening multiple reports simultaneously, importing large CSV files, or using additional integrations.
  • Disk Space: 40-60 GB NVMe SSD. A larger disk volume will provide room for data growth and backups.
  • Network Bandwidth: 1 Gbps.

Table: Comparison of VPS configurations for Firefly III

Valebyte offers various tariff plans that are ideally suited for deploying Firefly III. Below is a table with approximate configurations and their applicability:

VPS Configuration	vCPU	RAM	Disk (NVMe SSD)	Approx. Cost/Month	Applicability for Firefly III
Entry-level	1 core	2 GB	20 GB	$5 - $7	Minimum, for personal use with small data volumes. May be slow during import.
Optimal	2 cores	4 GB	40 GB	$8 - $12	Recommended, for active personal use, family, or a small number of users. Good performance.
Advanced	4 cores	8 GB	80 GB	$15 - $25	For very active users, large data volumes, integrations, or if other applications will be hosted on the VPS.

Choosing the optimal configuration depends on your needs. For most users, the "Optimal" plan will be the best choice, providing a balance between performance and cost.

Preparing the VPS for Firefly III Docker installation

Before proceeding directly to the Firefly III installation, you need to prepare your VPS. This stage includes selecting an operating system, basic security configuration, and installing Docker with Docker Compose.

Operating system selection and initial setup

For Firefly III deployment, we recommend using Ubuntu Server 22.04 LTS (Long Term Support). It provides stability, long-term support, and has a large community, which simplifies finding solutions to problems.

After gaining SSH access to your VPS (usually with the root login), perform the following initial steps:

1. System Update:

   sudo apt update && sudo apt upgrade -y

   This will update the package list and install all available updates, which is important for security and stability.

2. Create a regular user (optional, but recommended):

   Working as the root user is insecure. Create a new user and grant them sudo privileges.

   sudo adduser your_user
   sudo usermod -aG sudo your_user

   Then log out of the root session and log in as the new user.

3. Configure UFW firewall:

   UFW (Uncomplicated Firewall) is an easy-to-use firewall for Linux. Open the necessary ports:

   • 22/tcp: For SSH access.
   • 80/tcp: For HTTP (will later be redirected to HTTPS).
   • 443/tcp: For HTTPS.

   sudo ufw allow OpenSSH
   sudo ufw allow http
   sudo ufw allow https
   sudo ufw enable

   Confirm firewall activation by typing y.

4. Set timezone:

   sudo timedatectl set-timezone Europe/Moscow # or your timezone

Installing Docker and Docker Compose

To install Firefly III Docker images, we will need Docker Engine and Docker Compose. Docker simplifies application deployment by isolating them in containers, and Docker Compose allows managing multi-container applications with a single configuration file.

1. Install Docker Engine:

   Remove old Docker versions (if any):

   for pkg in docker.io docker-doc docker-compose docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin; do sudo apt remove $pkg; done

   Install necessary packages to install Docker over HTTPS:

   sudo apt install ca-certificates curl gnupg lsb-release -y

   Add Docker's official GPG key:

   sudo mkdir -p /etc/apt/keyrings
   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

   Add the Docker repository:

   echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

   Update package list and install Docker Engine:

   sudo apt update
   sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

2. Add user to docker group:

   To run Docker commands without sudo, add your user to the docker group:

   sudo usermod -aG docker your_user

   Log out and log back into your SSH session for the changes to take effect.

3. Verify Docker installation:

   docker run hello-world

   You should see the message "Hello from Docker!".

Your VPS is now ready to install Firefly III using Docker Compose.

Step-by-step Firefly III installation on VPS with Docker Compose

Installing Firefly III on a VPS with Docker Compose is the most recommended and convenient method. It allows you to deploy all necessary components (Firefly III, PostgreSQL database, and Redis cache) as isolated containers, managed by a single docker-compose.yml file.

Creating the docker-compose.yml file for Firefly III

Create a new directory for Firefly III and navigate into it:

mkdir ~/firefly-iii
cd ~/firefly-iii

Then create the docker-compose.yml file:

nano docker-compose.yml

Paste the following content. This is the standard configuration recommended by Firefly III developers. Be sure to change YOUR_APP_KEY, POSTGRES_PASSWORD, FIREFLY_DB_PASSWORD to random, strong passwords. You can generate APP_KEY with the command php artisan key:generate --show inside the Firefly III container after it starts, but for simplicity, you can use any long random string of characters now and change it later if needed.

version: "3.8"
services:
  firefly-iii:
    image: fireflyiii/core:latest
    container_name: firefly-iii
    volumes:
      - firefly_upload:/var/www/html/storage/upload
      - firefly_export:/var/www/html/storage/export
    env_file: .env
    depends_on:
      - db
      - redis
    restart: always
    ports:
      - "8080:8080" # The port on which Firefly III will be accessible within the VPS.
    networks:
      - firefly_network

  db:
    image: postgres:15-alpine
    container_name: firefly-db
    volumes:
      - firefly_db:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: firefly
      POSTGRES_USER: firefly
      POSTGRES_PASSWORD: YOUR_POSTGRES_PASSWORD # Change to a strong password
    restart: always
    networks:
      - firefly_network

  redis:
    image: redis:7-alpine
    container_name: firefly-redis
    restart: always
    networks:
      - firefly_network

volumes:
  firefly_upload:
  firefly_export:
  firefly_db:

networks:
  firefly_network:
    driver: bridge

Now create a .env file in the same directory, which will contain environment variables for Firefly III. This allows you to store sensitive data separately from docker-compose.yml.

nano .env

Paste the following content, replacing the placeholders with your values:

# Firefly III Application Key
APP_KEY=YOUR_APP_KEY # Generate with `php artisan key:generate --show` or use a long random string

# Database Configuration
DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432
DB_DATABASE=firefly
DB_USERNAME=firefly
DB_PASSWORD=YOUR_POSTGRES_PASSWORD # Must match POSTGRES_PASSWORD in docker-compose.yml

# Redis Configuration
REDIS_HOST=redis
REDIS_PORT=6379

# Firefly III Specific Settings
TRUSTED_PROXIES=** # Important for working with a reverse proxy, later change to your Nginx/Caddy container IP or Docker subnet

# Other optional settings
TZ=Europe/Moscow # Your timezone
DEFAULT_LOCALE=ru_RU # Or en_US, fr_FR, etc.
DEFAULT_CURRENCY=RUB # Or EUR, USD, etc.

Important: Ensure that YOUR_APP_KEY is a long, random string. You can generate it by temporarily running the Firefly III container, executing the command docker exec firefly-iii php artisan key:generate --show, and then updating the .env file.

Starting and initial setup of Firefly III

After creating the docker-compose.yml and .env files, you can start Firefly III. Navigate to the ~/firefly-iii directory if you are not already there, and execute the command:

docker compose up -d

This command will download the necessary Docker images (if not available locally), create the firefly-iii, firefly-db, firefly-redis containers, and start them in the background (-d). The process may take several minutes depending on your internet connection speed and VPS performance.

You can check the status of the containers:

docker compose ps

Ensure that all containers are in the "Up" state.

Initial Access:

Firefly III is now accessible via your VPS's IP address and port 8080. Open a web browser and go to http://YOUR_VPS_IP:8080.

You will see the Firefly III welcome page, where you will be prompted to create the first user and configure basic settings. Follow the instructions of the setup wizard.

Attention: Direct access via port 8080 is not secured with HTTPS and does not use your domain name. In the next step, we will configure a reverse proxy for secure access.

Configuring Reverse Proxy and HTTPS for Firefly III on the server

Direct access to Firefly III via an IP address and port 8080 is not a secure or professional solution. Configuring a reverse proxy with HTTPS support allows you to provide access to Firefly III via your domain name, encrypt traffic, and, if necessary, host multiple web services on a single IP address. We will consider two popular options: Nginx and Caddy.

For these steps, you will need:

• A registered domain (e.g., firefly.yourdomain.com).
• An A-type DNS record pointing to your VPS's IP address.

Nginx as a Reverse Proxy for Firefly III

Nginx is a high-performance web server and reverse proxy, widely used for deploying web applications. We will configure Nginx to redirect traffic from port 80/443 to Firefly III's port 8080 and obtain a free SSL certificate from Let's Encrypt using Certbot.

1. Install Nginx:

   sudo apt install nginx -y

2. Create Nginx configuration file for Firefly III:

   Create a new configuration file for your domain:

   sudo nano /etc/nginx/sites-available/firefly.conf

   Paste the following content, replacing firefly.yourdomain.com with your domain:

   server {
               listen 80;
               listen [::]:80;
               server_name firefly.yourdomain.com; # Replace with your domain
   
               location / {
                   proxy_pass http://127.0.0.1:8080; # Redirect to Firefly III port
                   proxy_set_header Host $host;
                   proxy_set_header X-Real-IP $remote_addr;
                   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                   proxy_set_header X-Forwarded-Proto $scheme;
               }
           }

3. Activate configuration:

   Create a symbolic link to the configuration file in sites-enabled:

   sudo ln -s /etc/nginx/sites-available/firefly.conf /etc/nginx/sites-enabled/

   Check Nginx syntax and reload it:

   sudo nginx -t
   sudo systemctl reload nginx

   Firefly III should now be accessible via http://firefly.yourdomain.com.

4. Install Certbot and obtain an SSL certificate:

   sudo apt install certbot python3-certbot-nginx -y

   Obtain a Let's Encrypt certificate and automatically configure Nginx:

   sudo certbot --nginx -d firefly.yourdomain.com

   Follow Certbot's instructions. It will ask if you want to redirect HTTP to HTTPS (recommended) and provide options for certificate renewal. After successful configuration, Firefly III will be accessible via https://firefly.yourdomain.com.

5. Update TRUSTED_PROXIES in .env:

   For Firefly III to correctly identify client IP addresses through Nginx, update the TRUSTED_PROXIES variable in the .env file.

   nano ~/firefly-iii/.env

   Change TRUSTED_PROXIES=** to TRUSTED_PROXIES=172.16.0.0/12 or TRUSTED_PROXIES=10.0.0.0/8 to cover the entire Docker Bridge subnet, or to the IP address of your Nginx container if Nginx is also running in Docker. If Nginx is installed directly on the VPS, you can leave ** or specify 127.0.0.1.

   After changing .env, restart the Firefly III container:

   cd ~/firefly-iii
   docker compose restart firefly-iii

Caddy: an easy way to get HTTPS for Firefly III

Caddy is a modern web server that automatically manages Let's Encrypt SSL/TLS certificates. It is significantly simpler to configure for HTTPS than Nginx with Certbot.

1. Install Caddy:

   Add GPG key:

   sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
   curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

   Add repository:

   curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

   Update and install Caddy:

   sudo apt update
   sudo apt install caddy -y

2. Create Caddyfile:

   Create or edit the main Caddy configuration file:

   sudo nano /etc/caddy/Caddyfile

   Remove all content and paste the following, replacing firefly.yourdomain.com with your domain:

   firefly.yourdomain.com {
               reverse_proxy 127.0.0.1:8080 {
                   header_up Host {host}
                   header_up X-Real-IP {remote_ip}
                   header_up X-Forwarded-For {remote_ip}
                   header_up X-Forwarded-Proto {scheme}
               }
           }

   Caddy will automatically obtain and renew SSL certificates for firefly.yourdomain.com.

3. Check and start Caddy:

   sudo caddy validate --config /etc/caddy/Caddyfile
   sudo systemctl reload caddy

   Firefly III should now be accessible via https://firefly.yourdomain.com.

4. Update TRUSTED_PROXIES in .env:

   Similar to Nginx, update TRUSTED_PROXIES in ~/firefly-iii/.env. If Caddy is installed directly on the VPS, you can leave ** or 127.0.0.1.

   cd ~/firefly-iii
   docker compose restart firefly-iii

Your self-hosted Firefly III is now accessible via a secure HTTPS connection through your domain name.

Maintaining Firefly III: backups, updates, and monitoring

Regular maintenance is critical for any self-hosted installation, and Firefly III is no exception. It includes creating backups, timely updates, and performance monitoring.

Firefly III data backup strategies

Loss of financial data can be catastrophic. Therefore, it is crucial to regularly create backups. In our case, Firefly III's main data is stored in a PostgreSQL database and in files located in Docker volumes.

Recommended backup strategy:

1. Backup PostgreSQL database:

   This is the most important component. You can create a database dump using pg_dump from inside the firefly-db container.

   docker exec firefly-db pg_dump -U firefly -d firefly > ~/firefly-iii/backups/firefly_db_$(date +%Y%m%d%H%M%S).sql

   Ensure that the ~/firefly-iii/backups/ directory exists: mkdir -p ~/firefly-iii/backups/.

2. Backup Docker volumes:

   The firefly_upload and firefly_export volumes contain uploaded files (e.g., statements) and exported reports. These should also be regularly copied.

   You can copy the contents of the volumes using a helper container or directly from the VPS file system if you know where Docker stores volumes (usually /var/lib/docker/volumes/).

   Example of copying the firefly_upload volume:

   docker run --rm --volumes-from firefly-iii -v $(pwd)/backups:/backup alpine tar cvf /backup/firefly_upload_$(date +%Y%m%d%H%M%S).tar /var/www/html/storage/upload

3. Automate backups with Cron:

   Create a script that performs both backup commands and configure it to run via Cron. For example, daily backup at 3 AM:

   crontab -e

   Add the line (make sure the paths are correct):

   0 3 * * * /bin/bash -c "cd /home/your_user/firefly-iii && docker exec firefly-db pg_dump -U firefly -d firefly > /home/your_user/firefly-iii/backups/firefly_db_$(date +%Y%m%d%H%M%S).sql && docker run --rm --volumes-from firefly-iii -v $(pwd)/backups:/backup alpine tar cvf /backup/firefly_upload_$(date +%Y%m%d%H%M%S).tar /var/www/html/storage/upload"

4. Off-site backup storage:

   The most important aspect of backups is to store them off the VPS. Use rsync, scp, sftp, or cloud storage (S3, Backblaze B2) to move backups from your VPS to another secure location. This will protect you in case of VPS failure or data loss.

Updating Firefly III Docker containers

Firefly III developers regularly release updates that include new features, bug fixes, and security improvements. Updating Firefly III via Docker Compose is very simple:

cd ~/firefly-iii
docker compose pull # Downloads the latest images for all services
docker compose up -d # Recreates containers with new images, preserving data volumes
docker image prune -f # Removes old, unused Docker images to save space

It is always recommended to read the changelog on the official Firefly III website before updating to be aware of possible changes or database migration requirements (although Docker Compose usually handles this automatically).

Monitoring VPS performance for Firefly III

Monitoring your VPS will help you ensure that Firefly III is running efficiently and there are no resource issues. You can use various tools:

• htop or top: Simple command-line utilities for viewing CPU, RAM usage, and processes.
• df -h: Check disk space usage.
• docker stats: Shows resource usage by individual Docker containers.
• Monitoring systems: For more advanced monitoring, consider tools like Netdata on VPS. Netdata provides detailed real-time graphs and metrics for the entire system and Docker containers, helping to identify bottlenecks or anomalies in operation.

Regular monitoring will help you respond to problems in a timely manner and, if necessary, scale your VPS so that Firefly III always runs fast and stably.

Optimal VPS configuration for Firefly III under real load

Choosing the optimal VPS configuration for Firefly III depends on your individual needs and anticipated load. We have already covered the minimum and recommended requirements, but let's delve into what VPS configuration would be ideal for various Firefly III usage scenarios under real load.

Scaling recommendations and tariff selection

1. For individual use (1-2 users, up to 1000 transactions per month):
   • vCPU: 2 cores. This will provide sufficient performance for quick startup, rule processing, and importing small amounts of data.
   • RAM: 2-4 GB. 2 GB will suffice, but 4 GB will provide more headroom for caching and background tasks.
   • Disk: 20-40 GB NVMe SSD. NVMe speed is critical for the database, and 20-40 GB will last for many years.
   • Approximate cost: $7-10/month.
   • Note: If you plan to host other lightweight self-hosted applications on the same VPS, such as Miniflux on VPS or FreshRSS on VPS, choose closer to the upper limit of RAM and disk recommendations.
2. For a family or small team (3-5 users, up to 5000 transactions per month):
   • vCPU: 4 cores. This will ensure comfortable operation for multiple users simultaneously, as well as fast generation of complex reports.
   • RAM: 4-8 GB. 4 GB is a good start, 8 GB will provide maximum performance without delays.
   • Disk: 60-80 GB NVMe SSD. A larger disk volume is necessary for a growing database, files, and backups.
   • Approximate cost: $15-25/month.
   • Note: In this scenario, disk subsystem stability and speed are important, so an NVMe SSD is mandatory.
3. For extended use / integrations (more than 5 users, over 5000 transactions, API integrations):
   • vCPU: 6-8 cores.
   • RAM: 8-16 GB.
   • Disk: 100+ GB NVMe SSD.
   • Approximate cost: $30+/month.
   • Note: If you actively use the Firefly III API for integration with other systems or process a very large volume of data, this configuration will provide the necessary power.

When choosing a VPS for Firefly III on a server from Valebyte, pay attention to the following aspects:

• Disk type: Always choose NVMe SSD for maximum database performance.
• Server location: Choose a data center located closer to you for minimal latency (ping).
• Scalability: Ensure that your provider allows easy scaling of resources (CPU, RAM, disk) in the future if your needs grow.
• Support: The availability of qualified technical support can be very helpful, especially if you are new to self-hosted solutions.

Overall, for most Firefly III users, a VPS with 2-4 CPU cores, 4 GB RAM, and a 40-60 GB NVMe disk will be the optimal choice. This will provide an excellent balance between performance and cost, allowing you to effectively manage your finances.

Conclusion

Installing Firefly III on a VPS using Docker Compose is a reliable and flexible way to gain full control over your financial data. This approach ensures a high degree of privacy, ease of maintenance, and scalability. For most users, a VPS with 2-4 vCPU, 4 GB RAM, and a 40-60 GB NVMe disk will be the optimal choice, which Valebyte offers at competitive prices, while ensuring stability and performance.