{"id":2792,"date":"2026-04-15T20:19:20","date_gmt":"2026-04-15T20:19:20","guid":{"rendered":"https:\/\/www.serverspan.com\/blog\/"},"modified":"2026-04-15T20:19:21","modified_gmt":"2026-04-15T20:19:21","slug":"firefly-iii-on-a-vps-own-your-financial-data-before-your-banks-app-owns-you","status":"publish","type":"post","link":"https:\/\/www.serverspan.com\/en\/blog\/firefly-iii-on-a-vps-own-your-financial-data-before-your-banks-app-owns-you\/","title":{"rendered":"Firefly III on a VPS: Own Your Financial Data Before Your Bank’s App Owns You"},"content":{"rendered":"\n

You can self-host Firefly III on a VPS in under 20 minutes using Docker Compose. The result is a fully private personal finance manager running on your own server, with transaction data stored in a MariaDB container, accessible over HTTPS behind Nginx, and connected to the Data Importer for CSV bank exports. This guide covers the complete setup and the one configuration mistake that silently corrupts your encrypted data on every version upgrade.<\/p>\n\n\n\n

What Firefly III actually does<\/h2>\n\n\n\n

Firefly III is an open-source personal finance manager built for people who want a real double-entry transaction ledger, not a bank app’s filtered view of their spending. You define accounts (checking, savings, credit cards, cash wallets, investment accounts), record transactions manually or import them from CSV files or bank connections, and build budgets, categories, and reports on top. The application runs entirely on your own infrastructure. No third-party service touches your financial data.<\/p>\n\n\n\n

The practical workflow on a VPS is straightforward: export a CSV from your bank’s online portal once a week, feed it to the Data Importer container, and Firefly III categorizes and stores the transactions. Over time you get accurate spending history, multi-currency support, recurring transaction automation, and financial reports that would otherwise require a paid subscription to a cloud app that stores your data on someone else’s server. On a ct.Steady plan (4 cores, 4GB RAM, 50GB SSD), Firefly III runs alongside other services without noticeable resource pressure.<\/p>\n\n\n\n

What you need before you start<\/h2>\n\n\n\n

You need a VPS running Debian 12 or Ubuntu 22.04\/24.04 with Docker and the Compose plugin installed. Firefly III’s stated minimum is 512MB RAM, but with MariaDB and the cron container also running, a 1GB instance becomes tight under normal operation. Plan for 2GB to give yourself comfortable headroom. You also need a domain or subdomain pointed at your server’s IP address before setting up the Nginx reverse proxy. The default SMTP block on new VPS instances does not affect Firefly III since email is optional configuration.<\/p>\n\n\n\n

If Docker is not yet installed, run:<\/p>\n\n\n\n

curl -fsSL https:\/\/get.docker.com | sh\nsystemctl enable --now docker<\/code><\/pre>\n\n\n\n
Verify that the Compose plugin is available:<\/p>\n\n\n\n
docker compose version<\/code><\/pre>\n\n\n\n
If the command returns a v2.x version number, proceed. If it fails, install the plugin manually:<\/p>\n\n\n\n
apt install docker-compose-plugin -y<\/code><\/pre>\n\n\n\n
Directory setup and file downloads<\/h2>\n\n\n\n
Create a dedicated directory and move into it:<\/p>\n\n\n\n
mkdir -p \/opt\/firefly-iii && cd \/opt\/firefly-iii<\/code><\/pre>\n\n\n\n
Download the three required files directly from the official Firefly III repositories:<\/p>\n\n\n\n
curl -O https:\/\/raw.githubusercontent.com\/firefly-iii\/docker\/main\/docker-compose.yml\ncurl -o .env https:\/\/raw.githubusercontent.com\/firefly-iii\/firefly-iii\/main\/.env.example\ncurl -o .db.env https:\/\/raw.githubusercontent.com\/firefly-iii\/docker\/main\/database.env<\/code><\/pre>\n\n\n\n
The filenames are not arbitrary. The compose file contains env_file: .env<\/code> and env_file: .db.env<\/code> as literal references. Renaming the files requires editing the compose file to match. Download the raw files with curl<\/code> rather than copy-pasting from a browser, since YAML is whitespace-sensitive and rendered pages may introduce invisible formatting changes.<\/p>\n\n\n\n
The Docker Compose file<\/h2>\n\n\n\n
The default compose file from the Firefly III Docker repository defines three core services: the main application (app<\/code>), the database (db<\/code> running MariaDB LTS), and a lightweight Alpine cron container that triggers recurring transaction processing each night. A minimal compose file configured for a production VPS deployment looks like this:<\/p>\n\n\n\n
services:\n  app:\n    image: fireflyiii\/core:latest\n    hostname: app\n    container_name: firefly_iii_core\n    restart: always\n    volumes:\n      - firefly_iii_upload:\/var\/www\/html\/storage\/upload\n    env_file: .env\n    networks:\n      - firefly_iii\n    ports:\n      - \"127.0.0.1:8080:8080\"\n    depends_on:\n      - db\n\n  db:\n    image: mariadb:lts\n    hostname: db\n    container_name: firefly_iii_db\n    restart: always\n    env_file: .db.env\n    networks:\n      - firefly_iii\n    volumes:\n      - firefly_iii_db:\/var\/lib\/mysql\n\n  cron:\n    image: alpine\n    container_name: firefly_iii_cron\n    restart: always\n    command: >\n      sh -c \"echo '0 3 * * * wget -qO- http:\/\/app:8080\/api\/v1\/cron\/REPLACE_WITH_CRON_TOKEN' | crontab - && crond -f -L \/dev\/stdout\"\n    networks:\n      - firefly_iii\n\nvolumes:\n  firefly_iii_upload:\n  firefly_iii_db:\n\nnetworks:\n  firefly_iii:\n    driver: bridge<\/code><\/pre>\n\n\n\n
The port binding uses 127.0.0.1:8080:8080<\/code> instead of 0.0.0.0:8080:8080<\/code>. This restricts direct container access to the loopback interface. The only path into Firefly III from outside the server is through your Nginx reverse proxy. Binding to 0.0.0.0<\/code> is a routine mistake on new VPS deployments that bypasses any firewall rules you have in place for port 8080.<\/p>\n\n\n\n
Configuring .env and why APP_KEY is the most important variable in the file<\/h2>\n\n\n\n
Open .env<\/code> and set these values before the containers ever start. The database password must match exactly between .env<\/code> and .db.env<\/code>:<\/p>\n\n\n\n
# .env\nAPP_KEY=                              # Generate this FIRST - see below\nAPP_URL=https:\/\/finance.yourdomain.com\nSITE_OWNER=you@yourdomain.com\nDB_CONNECTION=mysql\nDB_HOST=db\nDB_PORT=3306\nDB_DATABASE=firefly\nDB_USERNAME=firefly\nDB_PASSWORD=a_strong_password_here\nSTATIC_CRON_TOKEN=a32characterrandomtokenstringhere\nTZ=Europe\/Bucharest<\/code><\/pre>\n\n\n\n
# .db.env\nMYSQL_RANDOM_ROOT_PASSWORD=yes\nMYSQL_USER=firefly\nMYSQL_PASSWORD=a_strong_password_here\nMYSQL_DATABASE=firefly<\/code><\/pre>\n\n\n\n
Set the database password in both files before the first docker compose up<\/code>. MariaDB initializes its data directory on the first container start and stores the credentials in the volume. If you start the stack with one password and change it later in the env files, the database volume still holds the original credentials. You will get authentication failures on every subsequent start that require dropping the firefly_iii_db<\/code> volume to fix.<\/p>\n\n\n\n
Generating APP_KEY correctly<\/h3>\n\n\n\n
APP_KEY is Laravel’s application encryption key. Firefly III uses it to encrypt all OAuth tokens, API keys, and sensitive fields written to the database. The key must be exactly 32 characters. Generate one before you start the containers:<\/p>\n\n\n\n
head \/dev\/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo<\/code><\/pre>\n\n\n\n
Copy the output into .env<\/code>:<\/p>\n\n\n\n
APP_KEY=yourgenerated32characterstring<\/code><\/pre>\n\n\n\n
Store this value in a password manager immediately. You will need the original, unchanged key every time you update the container image, rebuild the stack, or migrate the installation to a different server. This key is permanently tied to the encrypted data in your MariaDB volume. It does not rotate. It does not change.<\/p>\n\n\n\n
The failure mode that breaks installations on upgrades<\/h3>\n\n\n\n
In our experience managing Docker deployments, this is the most common Firefly III support pattern: a user wants to upgrade to a new version, re-downloads the .env.example<\/code> from the repository to get clean settings, leaves APP_KEY<\/code> blank or generates a new one, and starts the updated container against the existing database volume. The new key cannot decrypt anything written with the old one. The application throws a Illuminate\\Contracts\\Encryption\\DecryptException<\/code> in the log and all previously created OAuth clients, API tokens, and encrypted account fields are unusable.<\/p>\n\n\n\n
Check the application log inside the running container:<\/p>\n\n\n\n
docker exec -it firefly_iii_core tail -n 50 \/var\/www\/html\/storage\/logs\/laravel.log<\/code><\/pre>\n\n\n\n
If you see DecryptException<\/code> entries, the cause is almost always APP_KEY mismatch. The recovery path is to restore the original key in .env<\/code> and restart the stack. There is no automated re-encryption utility. Changing APP_KEY after data has been written to the database is not recoverable without the original key.<\/p>\n\n\n\n
The STATIC_CRON_TOKEN<\/code> value goes into both the cron container command and your .env<\/code>. Generate it the same way as APP_KEY and keep it stable across upgrades for the same reason.<\/p>\n\n\n\n
Starting the stack and verifying health<\/h2>\n\n\n\n
Start all containers:<\/p>\n\n\n\n
docker compose up -d --pull=always<\/code><\/pre>\n\n\n\n
Watch the application logs until initialization completes:<\/p>\n\n\n\n
docker compose logs -f app<\/code><\/pre>\n\n\n\n
On a first run, Firefly III executes database migrations automatically. On a vm.Entry or ct.Ready plan, this typically finishes within 60 to 90 seconds. The “Thank you for installing Firefly III” line in the log confirms the application is ready. Verify the APP_KEY and database connection are working correctly with:<\/p>\n\n\n\n
docker exec firefly_iii_core php artisan firefly-iii:decrypt-all<\/code><\/pre>\n\n\n\n
If that command returns without error output, the stack is healthy.<\/p>\n\n\n\n
Nginx reverse proxy configuration<\/h2>\n\n\n\n
Install Nginx on the host if it is not already running:<\/p>\n\n\n\n
apt install nginx -y<\/code><\/pre>\n\n\n\n
Create a server block at \/etc\/nginx\/sites-available\/firefly<\/code>:<\/p>\n\n\n\n
server {\n    listen 80;\n    server_name finance.yourdomain.com;\n    return 301 https:\/\/$host$request_uri;\n}\n\nserver {\n    listen 443 ssl;\n    server_name finance.yourdomain.com;\n\n    ssl_certificate \/etc\/letsencrypt\/live\/finance.yourdomain.com\/fullchain.pem;\n    ssl_certificate_key \/etc\/letsencrypt\/live\/finance.yourdomain.com\/privkey.pem;\n\n    client_max_body_size 64M;\n\n    location \/ {\n        proxy_pass         http:\/\/127.0.0.1:8080;\n        proxy_set_header   Host $host;\n        proxy_set_header   X-Real-IP $remote_addr;\n        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header   X-Forwarded-Proto $scheme;\n    }\n}<\/code><\/pre>\n\n\n\n
Enable the site and obtain a certificate from Let’s Encrypt:<\/p>\n\n\n\n
ln -s \/etc\/nginx\/sites-available\/firefly \/etc\/nginx\/sites-enabled\/\napt install certbot python3-certbot-nginx -y\ncertbot --nginx -d finance.yourdomain.com\nnginx -t && systemctl reload nginx<\/code><\/pre>\n\n\n\n
The client_max_body_size 64M<\/code> directive is not optional if you plan to import large CSV files. Nginx rejects uploads above its 1MB default with a 413 error. Firefly III does not surface a helpful message in the UI when this happens, so the request silently fails and the import never starts. If you are running a DirectAdmin or cPanel stack on the same server with an existing Nginx front-end, add the proxy location to the relevant virtual host configuration instead of creating a parallel Nginx instance.<\/p>\n\n\n\n
Adding the Data Importer<\/h2>\n\n\n\n
The Data Importer is a separate container maintained by the Firefly III project. It reads CSV files or connects to supported bank APIs via GoCardless and pushes parsed transactions into Firefly III through the REST API. Running it as an additional service in the same compose file is the cleanest approach on a single VPS.<\/p>\n\n\n\n
Add the importer service to docker-compose.yml<\/code>:<\/p>\n\n\n\n
  importer:\n    image: fireflyiii\/data-importer:latest\n    hostname: importer\n    container_name: firefly_iii_importer\n    restart: always\n    networks:\n      - firefly_iii\n    ports:\n      - \"127.0.0.1:8081:8080\"\n    env_file: .importer.env\n    depends_on:\n      - app<\/code><\/pre>\n\n\n\n
Create .importer.env<\/code>. Two variables are non-negotiable:<\/p>\n\n\n\n
# .importer.env\nFIREFLY_III_URL=http:\/\/app:8080\nVANITY_URL=https:\/\/finance.yourdomain.com\nTZ=Europe\/Bucharest<\/code><\/pre>\n\n\n\n
The FIREFLY_III_URL<\/code> value is the internal Docker bridge network address. The importer communicates with the Firefly III container over the shared firefly_iii<\/code> network, using the container hostname app<\/code> and internal port 8080<\/code>. Setting this to your public domain name will fail because the importer cannot resolve external DNS from inside the Docker network. The VANITY_URL<\/code> is what the importer displays in its own interface to generate correct redirect links pointing at your public domain.<\/p>\n\n\n\n
Creating the OAuth client<\/h3>\n\n\n\n
After bringing up the updated stack with docker compose up -d<\/code>, open Firefly III in your browser and go to your profile page. Scroll to the OAuth section and create a new client:<\/p>\n\n\n\n