Self-Hosted Installation

This guide covers installing Firefly III directly on a Linux server. This method gives you full control over your installation but requires more technical knowledge.

System Requirements

PHP Requirements

Firefly III is built with Laravel and requires:

PHP 8.5 or higher
Required PHP extensions:
- bcmath - Arbitrary precision mathematics
- curl - HTTP client
- fileinfo - File information
- iconv - Character encoding conversion
- intl - Internationalization
- json - JSON processing
- mbstring - Multibyte string handling
- openssl - Cryptographic functions
- pdo - Database abstraction
- session - Session handling
- simplexml - XML parsing
- sodium - Modern cryptography
- tokenizer - PHP tokenizer
- xml - XML processing
- xmlwriter - XML writing

Database Requirements

One of the following:

MySQL 8.0 or higher
MariaDB 10.5 or higher
PostgreSQL 13 or higher
SQLite 3.35 or higher

Web Server

One of:

Apache 2.4+ with mod_rewrite enabled
Nginx 1.18+
Any web server that supports PHP-FPM

Additional Requirements

Composer 2.0 or higher
At least 512MB RAM
1GB+ disk space

Installation Steps

Install system dependencies

Ubuntu/Debian
CentOS/RHEL
Arch Linux

sudo apt update
sudo apt install -y \
  php8.5 \
  php8.5-cli \
  php8.5-fpm \
  php8.5-bcmath \
  php8.5-curl \
  php8.5-fileinfo \
  php8.5-intl \
  php8.5-mbstring \
  php8.5-mysql \
  php8.5-pgsql \
  php8.5-sqlite3 \
  php8.5-xml \
  php8.5-zip \
  composer \
  git

If PHP 8.5 is not available in your distribution, you may need to add a PPA like ondrej/php:

sudo add-apt-repository ppa:ondrej/php
sudo apt update

sudo dnf install -y \
  php \
  php-cli \
  php-fpm \
  php-bcmath \
  php-intl \
  php-mbstring \
  php-mysqlnd \
  php-pdo \
  php-pgsql \
  php-sodium \
  php-xml \
  composer \
  git

sudo pacman -S \
  php \
  php-fpm \
  php-intl \
  php-sodium \
  composer \
  git

Create a database

MySQL/MariaDB
PostgreSQL
SQLite

sudo mysql -u root -p

CREATE DATABASE firefly;
CREATE USER 'firefly'@'localhost' IDENTIFIED BY 'secure_password_here';
GRANT ALL PRIVILEGES ON firefly.* TO 'firefly'@'localhost';
FLUSH PRIVILEGES;
EXIT;

sudo -u postgres psql

CREATE DATABASE firefly;
CREATE USER firefly WITH PASSWORD 'secure_password_here';
GRANT ALL PRIVILEGES ON DATABASE firefly TO firefly;
\q

For PostgreSQL 15+, you also need to grant schema permissions:

sudo -u postgres psql firefly

GRANT ALL ON SCHEMA public TO firefly;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO firefly;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO firefly;
\q

Download Firefly III

Clone the repository to your web server directory:

cd /var/www
sudo git clone https://github.com/firefly-iii/firefly-iii.git
cd firefly-iii
sudo git checkout main

For production, use a tagged release instead of main:

sudo git checkout tags/v6.1.0  # Use the latest version

Install dependencies

Install PHP dependencies using Composer:

cd /var/www/firefly-iii
composer install --no-dev --optimize-autoloader

This will download all required packages. It may take a few minutes.

Configure environment

Copy the example environment file:

cp .env.example .env

Edit the .env file with your settings:

nano .env

Required settings:

.env

# Set to production
APP_ENV=production
APP_DEBUG=false

# Your email address (shown in error messages)
SITE_OWNER=your-email@example.com

# Will be generated in next step
APP_KEY=

# Your timezone
TZ=America/New_York

# Your public URL
APP_URL=https://firefly.example.com

# Database settings (MySQL example)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=firefly
DB_USERNAME=firefly
DB_PASSWORD=secure_password_here

See the Configuration Reference for all available options.

Generate application key

Generate a secure encryption key:

php artisan key:generate

This will automatically update your .env file with a secure APP_KEY.

Initialize the application

Run the installation commands:

# Clear caches
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear

# Run database migrations
php artisan migrate --seed

# Generate OAuth keys for API
php artisan passport:install

# Optimize for production
php artisan config:cache
php artisan route:cache
php artisan view:cache

Set file permissions

Set correct ownership and permissions:

# For Ubuntu/Debian (Apache)
sudo chown -R www-data:www-data /var/www/firefly-iii
sudo chmod -R 775 /var/www/firefly-iii/storage

# For Nginx (may use different user)
sudo chown -R nginx:nginx /var/www/firefly-iii
sudo chmod -R 775 /var/www/firefly-iii/storage

The storage and bootstrap/cache directories must be writable by the web server.

Configure web server

Nginx
Apache

Create a new site configuration:

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

Add the following configuration:

/etc/nginx/sites-available/firefly

server {
    listen 80;
    server_name firefly.example.com;
    root /var/www/firefly-iii/public;

    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.5-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_param HTTP_PROXY "";
    }

    location ~ /\.ht {
        deny all;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/firefly /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Create a new site configuration:

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

Add the following configuration:

/etc/apache2/sites-available/firefly.conf

<VirtualHost *:80>
    ServerName firefly.example.com
    DocumentRoot /var/www/firefly-iii/public

    <Directory /var/www/firefly-iii/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/firefly_error.log
    CustomLog ${APACHE_LOG_DIR}/firefly_access.log combined
</VirtualHost>

Enable required modules and the site:

sudo a2enmod rewrite
sudo a2enmod php8.5
sudo a2ensite firefly.conf
sudo apache2ctl configtest
sudo systemctl reload apache2

The document root must point to the /public directory, not the application root!

Set up SSL (recommended)

Use Let’s Encrypt for free SSL certificates:

Nginx
Apache

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d firefly.example.com

sudo apt install certbot python3-certbot-apache
sudo certbot --apache -d firefly.example.com

Update APP_URL in your .env file to use https://.

Configure cron jobs

Firefly III needs a daily cron job for recurring transactions:

sudo crontab -e -u www-data

Add this line:

0 3 * * * php /var/www/firefly-iii/artisan schedule:run >> /dev/null 2>&1

Access Firefly III

Navigate to your domain (e.g., https://firefly.example.com) and create your first user account.

Post-Installation

Enable Audit Logging (Optional)

To track financial events:

.env

AUDIT_LOG_LEVEL=info
AUDIT_LOG_CHANNEL=audit_daily

Configure Email (Optional)

For notifications and password resets:

.env

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_FROM=firefly@example.com
MAIL_USERNAME=your-smtp-username
MAIL_PASSWORD=your-smtp-password
MAIL_ENCRYPTION=tls

Performance Optimization

Redis Cache (Recommended)

Install Redis:

sudo apt install redis-server
sudo systemctl enable redis-server

Update .env:

.env

CACHE_DRIVER=redis
SESSION_DRIVER=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB="0"
REDIS_CACHE_DB="1"

Clear and rebuild cache:

php artisan config:clear
php artisan cache:clear
php artisan config:cache

PHP-FPM Tuning

Edit PHP-FPM pool configuration:

sudo nano /etc/php/8.5/fpm/pool.d/www.conf

Adjust these values based on your server resources:

pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
pm.max_requests = 500

Restart PHP-FPM:

sudo systemctl restart php8.5-fpm

Updating Firefly III

Backup your installation

# Backup database
mysqldump -u firefly -p firefly > firefly_backup_$(date +%Y%m%d).sql

# Backup files
tar -czf firefly_files_$(date +%Y%m%d).tar.gz /var/www/firefly-iii/storage/upload

# Backup .env
cp /var/www/firefly-iii/.env /var/www/firefly-iii/.env.backup

Put site in maintenance mode

cd /var/www/firefly-iii
php artisan down

Update the code

git fetch --all
git checkout tags/v6.1.0  # Use latest version

Update dependencies

composer install --no-dev --optimize-autoloader

Run upgrade commands

php artisan config:clear
php artisan cache:clear
php artisan migrate --force
php artisan firefly-iii:upgrade-database
php artisan passport:install
php artisan config:cache
php artisan route:cache
php artisan view:cache

Restore site

php artisan up

Troubleshooting

500 Internal Server Error

Check the Laravel logs:

tail -f /var/www/firefly-iii/storage/logs/laravel.log

Common causes:

Incorrect file permissions on storage/ directory
Missing PHP extensions
Invalid .env configuration

Database Connection Errors

Test the connection:

php artisan tinker

Then run:

DB::connection()->getPdo();

Page Shows “Public” Warning

Your document root is set incorrectly. It should point to /var/www/firefly-iii/public, not /var/www/firefly-iii.

CSS/JS Not Loading

Run:

php artisan view:clear
php artisan cache:clear

Check file permissions:

sudo chown -R www-data:www-data /var/www/firefly-iii

Security Hardening

Disable Directory Listing

Already configured in the provided .htaccess file:

Options All -Indexes

Firewall Configuration

Allow only HTTP/HTTPS:

sudo ufw allow 'Nginx Full'
# or
sudo ufw allow 'Apache Full'

Regular Updates

Keep your system updated:

sudo apt update && sudo apt upgrade

Self-Hosted Installation

System Requirements

PHP Requirements

Database Requirements

Web Server

Additional Requirements

Installation Steps

Post-Installation

Enable Audit Logging (Optional)

Configure Email (Optional)

Performance Optimization

Redis Cache (Recommended)

PHP-FPM Tuning

Updating Firefly III

Troubleshooting

500 Internal Server Error

Database Connection Errors

Page Shows “Public” Warning

CSS/JS Not Loading

Security Hardening

Disable Directory Listing

Firewall Configuration

Regular Updates

Next Steps

Configuration

API Documentation

​System Requirements

​PHP Requirements

​Database Requirements

​Web Server

​Additional Requirements

​Installation Steps

​Post-Installation

​Enable Audit Logging (Optional)

​Configure Email (Optional)

​Performance Optimization

​Redis Cache (Recommended)

​PHP-FPM Tuning

​Updating Firefly III

​Troubleshooting

​500 Internal Server Error

​Database Connection Errors

​Page Shows “Public” Warning

​CSS/JS Not Loading

​Security Hardening

​Disable Directory Listing

​Firewall Configuration

​Regular Updates

​Next Steps

Configuration

API Documentation

System Requirements

PHP Requirements

Database Requirements

Web Server

Additional Requirements

Installation Steps

Post-Installation

Enable Audit Logging (Optional)

Configure Email (Optional)

Performance Optimization

Redis Cache (Recommended)

PHP-FPM Tuning

Updating Firefly III

Troubleshooting

500 Internal Server Error

Database Connection Errors

Page Shows “Public” Warning

CSS/JS Not Loading

Security Hardening

Disable Directory Listing

Firewall Configuration

Regular Updates

Next Steps