Firefly III es un gestor de finanzas personales de código abierto que autoalojas con Docker para llevar el control de tu dinero sin ceder tus datos bancarios a ninguna aplicación externa. En esta guía levantas la aplicación junto a una base de datos MariaDB y el importador de datos con un solo archivo docker-compose.yml, generas la APP_KEY de 32 caracteres que es obligatoria, importas transacciones desde tu banco y programas copias de seguridad. La misma explicación está disponible en inglés.

Puntos clave

  • Firefly III es una aplicación web de finanzas personales escrita en PHP con Laravel, publicada bajo licencia AGPL-3.0, que sustituye a servicios de agregación bancaria comerciales y guarda tus datos en tu propio servidor.
  • La versión estable actual es la 6.6.6, publicada en julio de 2026; conviene fijar la etiqueta fireflyiii/core:version-6.6.6 en lugar de :latest.
  • Necesitas una APP_KEY de exactamente 32 caracteres: si falta o tiene otra longitud, la aplicación no arranca.
  • El contenedor escucha en el puerto 8080 interno y requiere una base de datos externa; MariaDB o PostgreSQL, nunca SQLite para uso serio.
  • El importador de datos (imagen fireflyiii/data-importer) es un segundo contenedor que conecta con más de 6.000 bancos a través de GoCardless (Nordigen) y también importa archivos CSV.

¿Qué es Firefly III?

Firefly III es una herramienta de código abierto para gestionar tus finanzas personales: registras ingresos y gastos, defines presupuestos, creas cuentas de activo y pasivo, programas facturas recurrentes y visualizas a dónde va tu dinero con informes y gráficos. Todo ello en un servidor que controlas tú, sin cuotas mensuales ni datos alojados en la nube de un tercero.

Está construida con PHP sobre el framework Laravel y se distribuye bajo licencia AGPL-3.0, lo que garantiza que el código permanece libre. A diferencia de aplicaciones como Mint o los agregadores de tu banco, Firefly III no vende tus datos ni te muestra publicidad, porque los datos nunca salen de tu máquina. Ofrece una API REST completa, autenticación en dos pasos y reglas automáticas que clasifican las transacciones por categoría a medida que entran, de modo que el mantenimiento diario se reduce al mínimo.

¿Qué necesitas antes de empezar?

Necesitas una máquina Linux con Docker y el plugin Compose ya instalados. Si aún no lo tienes, sigue primero la guía para instalar Docker en Ubuntu 24.04. Con 1 GB de RAM y un núcleo va sobrado para un uso personal.

Firefly III no incluye base de datos propia: guarda todo en un motor externo, así que el montaje mínimo son dos contenedores, la aplicación y la base de datos. En esta guía usamos MariaDB, aunque PostgreSQL funciona igual de bien. Para no escribir las contraseñas directamente en el archivo, conviene repasar antes cómo funcionan las variables de entorno y los secretos en Docker, que es justo el patrón que aplicaremos aquí.

El docker-compose.yml con base de datos y el importador de datos

Crea una carpeta para el proyecto y guarda dentro este docker-compose.yml. Antes de arrancar, sustituye la clave de la base de datos, pega tu APP_KEY (la generamos en el apartado siguiente) y cambia el token del cron por una cadena aleatoria de 32 caracteres:

services:
  app:
    image: fireflyiii/core:version-6.6.6
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8085:8080"
    volumes:
      - firefly_upload:/var/www/html/storage/upload
    environment:
      APP_KEY: pega_aqui_una_clave_de_exactamente_32_car
      APP_URL: "http://localhost:8085"
      TZ: "Europe/Madrid"
      STATIC_CRON_TOKEN: cambia_este_token_de_32_caracteres_exacto
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: "3306"
      DB_DATABASE: firefly
      DB_USERNAME: firefly
      DB_PASSWORD: cambia_esta_clave_db

  db:
    image: mariadb:lts
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: firefly
      MARIADB_USER: firefly
      MARIADB_PASSWORD: cambia_esta_clave_db
      MARIADB_RANDOM_ROOT_PASSWORD: "yes"
    volumes:
      - firefly_db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 30s
      timeout: 5s
      retries: 5

  importer:
    image: fireflyiii/data-importer:version-2.3.4
    restart: unless-stopped
    depends_on:
      - app
    ports:
      - "8086:8080"
    environment:
      FIREFLY_III_URL: "http://app:8080"
      VANITY_URL: "http://localhost:8085"

  cron:
    image: alpine:3.21
    restart: unless-stopped
    command: >
      sh -c "echo '0 3 * * * wget -qO- http://app:8080/api/v1/cron/cambia_este_token_de_32_caracteres_exacto'
      | crontab - && crond -f -L /dev/stdout"

volumes:
  firefly_upload:
  firefly_db:

Fíjate en algunos detalles del archivo. La aplicación no arranca hasta que MariaDB pasa su healthcheck, gracias a depends_on con la condición service_healthy. El servicio app escucha en el puerto 8080 interno y lo publicamos en el 8085 del anfitrión para no chocar con otros servicios; el importer queda en el 8086. El contenedor cron es una imagen alpine mínima que cada día, a las tres de la madrugada, llama al endpoint de tareas programadas de Firefly III para procesar facturas recurrentes y avisos; su token debe ser idéntico al STATIC_CRON_TOKEN de la aplicación.

APP_KEY y variables obligatorias

La APP_KEY cifra las sesiones y los datos sensibles de Firefly III y es el requisito que más quebraderos de cabeza causa, porque debe medir exactamente 32 caracteres. Si es más corta o más larga, el contenedor entra en un bucle de reinicios. Genera una cadena válida con este comando y pégala en el valor APP_KEY del Compose:

head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo

Evita los caracteres =, # y similares en la clave, porque pueden romper la interpretación del archivo. Estas son las variables que no puedes dejar sin revisar:

  • APP_KEY: la clave de 32 caracteres que acabas de generar. No la compartas ni la subas a un repositorio.
  • APP_URL: la dirección pública desde la que accederás a Firefly III. En tu equipo es http://localhost:8085; en producción, la URL completa con HTTPS.
  • DB_CONNECTION, DB_HOST, DB_DATABASE, DB_USERNAME y DB_PASSWORD: los datos de conexión a la base de datos, que deben coincidir con los del servicio db.
  • STATIC_CRON_TOKEN: un token de 32 caracteres que protege el endpoint de tareas programadas; el contenedor cron lo usa para autenticarse.

Con el archivo y la clave listos, arranca la pila en segundo plano y comprueba que los servicios están sanos:

docker compose up -d
docker compose ps
docker compose logs -f app

La primera vez, la aplicación ejecuta las migraciones de la base de datos, así que el arranque tarda algo más. Cuando el registro deje de moverse, abre http://localhost:8085 en el navegador, registra la primera cuenta (será la de administrador) e indica la divisa con la que trabajas.

¿Cómo importar transacciones bancarias?

El importador de datos es lo que convierte a Firefly III en una herramienta cómoda de usar cada día. Es importante entender que no se conecta a tu banco directamente: se apoya en dos servicios intermediarios, GoCardless (antes Nordigen) para más de 6.000 bancos europeos y SaltEdge para el resto del mundo, además de la importación clásica de archivos CSV y camt.053.

Para usar la conexión bancaria automática, entra en http://localhost:8086, la interfaz del importer, y sigue el asistente. El primer paso es darle un token de acceso de Firefly III (lo creas en Opciones, Perfil, OAuth, Personal Access Tokens) para que el importador pueda escribir en tu instancia. Después eliges GoCardless, introduces las credenciales que obtienes gratis en su portal, seleccionas tu banco y autorizas el acceso de solo lectura a tus cuentas. A partir de ahí, el importador descarga los movimientos y los convierte en transacciones de Firefly III, aplicando tus reglas de categorización.

Si prefieres no depender de terceros, la vía CSV es la más privada: exportas el extracto desde la web de tu banco, lo subes al importador y defines una vez el mapeo de columnas. Ese mapeo se guarda como plantilla, de modo que las siguientes importaciones son cuestión de segundos. Para automatizarlo por completo, el importador expone un endpoint protegido por la variable AUTO_IMPORT_SECRET (mínimo 16 caracteres) que puedes lanzar desde el propio cron.

Copias de seguridad y seguridad

Firefly III guarda dinero, o mejor dicho, el reflejo detallado de tu dinero, así que las copias de seguridad no son opcionales. Solo hay dos piezas que respaldar: el volcado de la base de datos y el volumen de subidas, donde viven los adjuntos (recibos, facturas escaneadas) que asocias a cada transacción. Con MariaDB, un backup completo cabe en dos comandos:

docker compose exec db mariadb-dump -u firefly -p firefly > firefly-db.sql
docker run --rm -v firefly_upload:/data -v "$PWD":/backup alpine \
  tar czf /backup/firefly-upload.tar.gz -C /data .

En cuanto a la seguridad, nunca expongas Firefly III a Internet por HTTP plano: transporta datos financieros y necesita cifrado. Ponlo detrás de un proxy inverso que gestione TLS, como Traefik con Docker Compose, y activa la autenticación en dos pasos desde tu perfil. Guarda la APP_KEY y las contraseñas en un archivo .env con permisos restringidos, el mismo enfoque que veíamos en variables de entorno y secretos en Docker, y no vuelvas a cambiar la APP_KEY una vez la base de datos esté en uso, porque invalidaría los datos cifrados.

Preguntas frecuentes

¿Puedo usar Firefly III sin conexión a mi banco?

Sí, y es una forma perfectamente válida de usarlo. Puedes introducir las transacciones a mano o importar los extractos que descargas de la web de tu banco en formato CSV, sin dar a ningún tercero acceso a tus cuentas. La conexión automática con GoCardless o SaltEdge es una comodidad opcional, no un requisito; muchos usuarios prefieren la ruta CSV precisamente por privacidad.

¿Por qué no debo usar la etiqueta latest de la imagen?

Porque :latest cambia sin avisarte y una actualización mayor podría ejecutar migraciones de base de datos durante un simple reinicio, en un servicio que guarda datos financieros que no quieres arriesgar. Al fijar fireflyiii/core:version-6.6.6 decides tú cuándo actualizas: lees primero las notas de la versión, haces una copia de seguridad y solo entonces subes la etiqueta.

¿Qué base de datos elijo, MariaDB o PostgreSQL?

Ambas están soportadas oficialmente y rinden bien. MariaDB es la que usa la configuración por defecto de Firefly III y la que hemos puesto en el docker-compose.yml de esta guía, así que es la opción más sencilla si empiezas de cero. Si ya tienes una PostgreSQL en marcha para otros servicios, puedes reutilizarla cambiando DB_CONNECTION a pgsql y el puerto a 5432. Lo que Firefly III no admite para uso serio es SQLite.

Conclusión

Con un único docker-compose.yml tienes un gestor de finanzas personales completo y privado: aplicación, base de datos, importador y tareas programadas, con todos tus datos en tu servidor. El siguiente paso lógico es publicarlo con seguridad detrás de Traefik, conectar tu banco o importar tu primer CSV, y programar las copias de seguridad. Si te ha gustado organizar tu dinero de esta forma, echa un vistazo a Vikunja para gestionar tus tareas, otra pieza autoalojada de esta serie.

Fuentes

  1. Documentación oficial de Firefly III
  2. Repositorio firefly-iii en GitHub
  3. Imagen oficial fireflyiii/core en Docker Hub

Ruta: Productividad y documentos self-hosted con Docker