Skip to main content

​
Choose your installation method

Firefly III offers multiple installation options to fit your technical setup and preferences. Choose the method that works best for you.

Docker

Recommended - Quick setup with Docker Compose. Perfect for most users.

Self-hosted

Install directly on your server with PHP, web server, and database.

Kubernetes

Deploy in a Kubernetes cluster with Helm charts and manifests.

Cloud platforms

One-click install on Cloudron, YunoHost, and other platforms.

​
System requirements

Before installing Firefly III, ensure your system meets these requirements:

​
For Docker installation

  • Docker Engine 20.10 or newer
  • Docker Compose 2.0 or newer
  • At least 512 MB RAM available
  • 1 GB free disk space (more for your data)
  • Port 80 or 8080 available (configurable)

​
For self-hosted installation

Firefly III requires PHP 8.5 or higher with these extensions:
# Required PHP extensions
php-bcmath
php-curl
php-fileinfo
php-iconv
php-intl
php-json
php-mbstring
php-openssl
php-pdo
php-session
php-simplexml
php-sodium
php-tokenizer
php-xml
php-xmlwriter
These extensions are typically included in standard PHP installations but may need to be enabled.
Choose one of these database systems:MySQL / MariaDB (recommended)
  • MySQL 8.0 or newer
  • MariaDB 10.6 or newer
PostgreSQL
  • PostgreSQL 12 or newer
SQLite
  • SQLite 3.35 or newer
  • Suitable for development and small installations
For PostgreSQL 15+, you may need to grant schema privileges due to security changes.
Firefly III works with:
  • Apache 2.4+ with mod_rewrite enabled
  • Nginx 1.18+ with PHP-FPM
  • Caddy 2.0+ (automatic HTTPS)
Ensure the web server has:
  • Write permissions to storage/ and bootstrap/cache/ directories
  • Access to PHP execution
  • Proper URL rewriting configured

​
Installation comparison

Not sure which method to choose? Here’s a quick comparison:
FeatureDockerSelf-hostedKubernetesCloud Platforms
Ease of setup⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
MaintenanceEasyModerateComplexVery easy
CustomizationHighVery highVery highLimited
PerformanceExcellentExcellentExcellentGood
Resource usageLowVery lowMediumVaries
Best forMost usersAdvanced usersEnterpriseBeginners
New to self-hosting? Start with Docker or a cloud platform. You can always migrate to a different setup later.

​
Quick start options

The fastest way to get started: 
# Create directories
mkdir -p firefly-iii && cd firefly-iii

# Download sample docker-compose.yml and .env
wget https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/docker-compose.yml
wget https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example -O .env

# Edit .env with your settings
nano .env

# Start Firefly III
docker-compose up -d

Complete Docker guide

Follow the detailed Docker installation guide with all configuration options.

​
Option 2: Self-hosted with Composer

For full control over your installation: 
# Clone the repository
git clone https://github.com/firefly-iii/firefly-iii.git
cd firefly-iii

# Install dependencies
composer install --no-dev --no-scripts

# Copy and configure environment
cp .env.example .env
php artisan key:generate

# Set up database
php artisan migrate --seed
php artisan passport:install

Complete self-hosted guide

Follow the detailed self-hosted installation guide with web server configuration.

​
Option 3: One-click platforms

Install with a single click on these platforms:

Cloudron

Install on Cloudron with automatic updates and backups

YunoHost

Install via YunoHost package manager

Softaculous

Auto-installer for cPanel and Plesk

AMPPS

Local development stack with Firefly III

​
Configuration essentials

After installation, you’ll need to configure these core settings:
1

Generate application key

The APP_KEY is critical for security. Generate a random 32-character string:
# For Docker
docker-compose exec firefly_iii_app php artisan key:generate

# For self-hosted
php artisan key:generate
Or generate manually:
head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo
Never share your APP_KEY. If compromised, regenerate it immediately.
2

Configure database connection

Set these environment variables in your .env file:
.env
DB_CONNECTION=mysql  # or 'pgsql' or 'sqlite'
DB_HOST=localhost    # or your database host
DB_PORT=3306        # 5432 for PostgreSQL
DB_DATABASE=firefly
DB_USERNAME=firefly
DB_PASSWORD=your_secure_password
For Docker, use the service name (e.g., firefly_iii_db) as DB_HOST.
3

Set your timezone and locale

Configure your preferences:
.env
# Timezone (see https://www.php.net/manual/en/timezones.php)
TZ=America/New_York

# Language and locale
DEFAULT_LANGUAGE=en_US
DEFAULT_LOCALE=equal
4

Configure email (optional)

For notifications and password resets:
.env
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_FROM=[email protected]
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
Email is optional but recommended for password recovery and notifications.

​
Post-installation steps

After installation, complete these steps:
  1. Open Firefly III in your browser
  2. Register a new account (first user becomes administrator)
  3. Set a strong password
  4. Enable two-factor authentication for security
Enable HTTPS
  • Use a reverse proxy (nginx, Caddy, Traefik)
  • Obtain SSL certificates (Let’s Encrypt recommended)
  • Force HTTPS redirects
Configure firewall
  • Only expose necessary ports (80, 443)
  • Restrict database access to localhost
  • Consider VPN access for extra security
Set proper permissions
# For self-hosted installations
sudo chown -R www-data:www-data storage/ bootstrap/cache/
sudo chmod -R 775 storage/ bootstrap/cache/
Firefly III needs a cron job for recurring transactions and maintenance:For Docker: The cron job runs automatically in the container.For self-hosted: Add this to your crontab:
# Run every day at 3 AM
0 3 * * * cd /var/www/firefly-iii && php artisan schedule:run >> /dev/null 2>&1
Or use the static cron token:
0 3 * * * curl https://your-firefly-url/cron/[YOUR_TOKEN] >> /dev/null 2>&1
Database backups:
# MySQL
mysqldump -u firefly -p firefly > firefly-backup-$(date +%Y%m%d).sql

# PostgreSQL
pg_dump -U firefly firefly > firefly-backup-$(date +%Y%m%d).sql
Docker volume backups:
docker-compose down
docker run --rm -v firefly_iii_db:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/firefly-db-backup.tar.gz /data
docker-compose up -d
Test your backups regularly. A backup you can’t restore is useless!

​
Updating Firefly III

​
Docker updates

# Pull the latest image
docker-compose pull

# Restart with new image
docker-compose up -d

​
Self-hosted updates

# Back up first!
mysqldump -u firefly -p firefly > backup-before-update.sql

# Update code
git pull
composer install --no-dev

# Run migrations
php artisan migrate
php artisan cache:clear
php artisan view:clear

Configuration guide

Learn about all available configuration options and advanced settings.

​
Troubleshooting

  1. Check PHP error logs
  2. Verify file permissions on storage/ and bootstrap/cache/
  3. Ensure all PHP extensions are installed
  4. Run php artisan config:clear and php artisan cache:clear
  1. Verify database credentials in .env
  2. Check database server is running
  3. Ensure database exists: CREATE DATABASE firefly;
  4. Test connection: mysql -u firefly -p -h localhost firefly
  1. Check logs: docker-compose logs firefly_iii_app
  2. Verify port is not already in use
  3. Ensure .env file has APP_KEY set
  4. Wait for database initialization (can take 60 seconds)
  1. Clear browser cache and cookies
  2. Check session driver in .env (use file for simple setups)
  3. Verify permissions on storage/framework/sessions/
  4. Create new user: php artisan firefly-iii:create-user

Need more help?

Visit the troubleshooting guide for more solutions and debugging tips.

​
Next steps

Quick start guide

Set up your first account and transaction

Import data

Import existing financial data from your bank

API access

Generate API tokens for integrations

Security setup

Configure 2FA and security settings

Build docs developers (and LLMs) love

Get started for freeTalk to us