firefly-iii-application

Badges

Self-hosted Firefly III personal finance management application with automated deployment, security, and operational workflows.

---

At a Glance

Aspect	What You Get
Application	Firefly III personal finance management
Containerization	Multi-service Docker setup with org-owned images
CI/CD	GitHub Actions pipelines & template sync
Consistency	Automatic sync of core config & workflow files to app repos (opt‑in via topic)
Quality	Conventional Commits + Semantic Versioning scaffolding
Documentation	TechDocs-ready structure for internal/platform portals
Security	Encrypted secrets handling via SOPS + age
Developer UX	Pre-configured editor & workflow automation

Features

• Self-maintained image policy: All services use org-owned images built from official upstream sources
• Firefly III: Complete personal finance management application stack
• Security-first: Official upstream images with exact version pinning
• Port hygiene: Only reverse proxy exposes host ports
• Automated template file synchronization (opt‑in per repo by GitHub topic)
• Semantic release readiness (.releaserc.json included)
• Encrypted secrets workflow (age / SOPS)
• Curated GitHub workflow set (docs changes, source changes)
• Opinionated baseline configs: EditorConfig, VSCode settings, .gitignore
• Structured test categories (unit, integration, functional, contract, e2e, smoke, performance, behavioral)

Description

Self-hosted Firefly III personal finance management application with comprehensive containerization following WebGrip's self-maintained image policy. Every service uses org-owned images built from pinned official upstream sources for enhanced security and supply chain control.

Containerization Architecture:

• Application: Firefly III core application (fireflyiii/core:version-6.1.21)
• Data Importer: Firefly III data importer (fireflyiii/data-importer:version-1.5.4)
• Reverse Proxy: Nginx (nginx:1.26.2-alpine3.20)
• Database: MariaDB (mariadb:12.0.2-noble)
• Cache: Redis (redis:8.2.1-alpine3.20)

All images are rebuilt and tagged as webgrip/firefly-iii-application.<service>:latest with minimal overlays for project-specific configuration.

Template Synchronization

This repository serves as a template that can automatically sync certain files to application repositories. To enable template sync for your application repository, add the application topic to your repository.

Synced Files Include:

Category	Files
Workflows	.github/workflows/*.yml (selected core automation)
Config	.editorconfig, .gitignore, .releaserc.json
Dev UX	.vscode/settings.json

These represent the "source of truth"; local divergent changes in target repos will be overwritten (review PRs carefully).

For detailed information, see the Template Sync Documentation.

Getting Started

Encrypted secrets

make init-encrypt

Creates:

• age.agekey → add to repo secret SOPS_AGE_KEY
• age.pubkey → used for encryption

Add plaintext secrets to:

ops/secrets/firefly-iii-application-secrets/values.dec.yaml

Encrypt them:

make encrypt-secrets SECRETS_DIR=./ops/secrets/firefly-iii-application-secrets

This produces values.sops.yaml (commit this).

---

Docker

Start the full Firefly III stack:

make start

Stop and clean up:

make stop

The application will be available at http://localhost:8080

Services:

• Nginx: Reverse proxy exposing the application (port 8080)
• Firefly III Application: Personal finance management application
• Firefly III Data Importer: Data import and synchronization service
• MariaDB: Database backend
• Redis: Cache and session storage

Port Policy:

• Only the nginx reverse proxy exposes host ports (8080)
• Internal application services communicate via Docker network
• Database and Redis are only accessible within the container network

---

Kubernetes (Helm)

For production deployment to Kubernetes using Helm charts:

Prerequisites

• Kubernetes cluster with Traefik ingress controller
• Helm 3.x installed
• kubectl configured for your cluster

Quick Start

1. Configure secrets (see ops/secrets/firefly-iii-application-secrets/values.dec.yaml.example):

   cp ops/secrets/firefly-iii-application-secrets/values.dec.yaml.example \
      ops/secrets/firefly-iii-application-secrets/values.dec.yaml
   # Edit values.dec.yaml with your secrets

2. Install secrets chart:

   helm upgrade --install firefly-iii-application-secrets \
     ops/secrets/firefly-iii-application-secrets \
     --values ops/secrets/firefly-iii-application-secrets/values.dec.yaml \
     -n firefly-iii-application --create-namespace

3. Install main application:

   helm upgrade --install firefly-iii-application \
     ops/helm/firefly-iii-application \
     -n firefly-iii-application

Required Secrets:

• app-key: Laravel application encryption key
• db-password: Database password
• redis-password: Redis password
• api-secret: API authentication token
• update-secret: Webhook authentication token
• webcron-secret: Scheduled task authentication token

For detailed documentation, see ops/helm/README.md.

---

Contributing

Contributions welcome! Please:

1. Open an issue describing the change
2. Use Conventional Commits for branch + commit messages
3. Add / adjust tests where behavior changes
4. Update docs (README / TechDocs / ADRs) when altering architecture

Roadmap (Excerpt)

• Add coverage reporting & badge
• Introduce example service code scaffolding
• Provide k6 performance test harness
• Optional Terraform module integration

License

Distributed under the terms of the MIT license. See LICENSE for details.