Alojar Firefly III en un VPS administrado: sus finanzas en su propio servidor

Qué hace Firefly III

Firefly III es un gestor de finanzas personales pensado para el autoalojamiento. Registra sus gastos y sus ingresos, con presupuestos, categorías y etiquetas, para que vea adónde va su dinero. Su README lo describe como completamente autoalojado y aislado: no contacta con ningún servidor externo hasta que usted se lo indica de forma explícita.

• La contabilidad: partida doble, cuentas de activo, pasivos y todas las divisas que desee.
• La automatización: transacciones periódicas, y reglas que usted escribe para clasificar cada transacción.
• El seguimiento: presupuestos, huchas para ahorrar con un objetivo, informes de ingresos y gastos, gráficos.
• La seguridad: doble autenticación para cada cuenta.
• La apertura: una API REST JSON que cubre casi toda la aplicación, además de webhooks.

Una sola instancia acoge a tantos usuarios como quiera, cada uno con una administración financiera totalmente separada de las demás. La documentación describe un modelo para compartir una misma administración, actualmente en desarrollo.

Lo que permite la licencia AGPL

Firefly III se publica bajo la GNU Affero General Public License, versión 3 o, a su elección, cualquier versión posterior: es el identificador SPDX AGPL-3.0-or-later de su archivo composer.json. El texto afirma un permiso ilimitado para ejecutar el programa sin modificar. Puede, por tanto, usar la imagen publicada por el proyecto para usted, su familia o su empresa, sin ninguna licencia que comprar.

El artículo 13 añade una condición propia de la AGPL: si modifica el programa, su versión debe ofrecer a todos los que la usan a distancia, por la red, el modo de obtener gratuitamente su código fuente. El importador de datos tiene la misma licencia.

La instalación con Docker Compose

La documentación presenta Docker Compose como la forma más sencilla de instalar Firefly III. En un servidor con Docker instalado, cree una carpeta y descargue en ella los tres archivos oficiales, en bruto: sus espacios cuentan, y la documentación pide no copiarlos desde el navegador.

mkdir firefly-iii && cd firefly-iii
curl -o docker-compose.yml https://raw.githubusercontent.com/firefly-iii/docker/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example
curl -o .db.env https://raw.githubusercontent.com/firefly-iii/docker/main/database.env

• docker-compose.yml describe tres servicios: app, la aplicación, db, una base de datos MariaDB, y cron, la tarea programada.
• .env contiene los ajustes de Firefly III, entre ellos la clave de cifrado y el acceso a la base.
• .db.env contiene los ajustes de la base de datos. Conserve los dos nombres: el archivo Compose los cita mediante env_file.

Los ajustes que hay que cambiar antes del primer arranque

Genere dos cadenas de 32 caracteres con el comando que indica el archivo .env: una para la clave y otra para la contraseña de la base.

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

SITE_OWNER=you@example.com
APP_KEY=
DB_PASSWORD=
APP_URL=https://finances.example.com

MYSQL_PASSWORD=

• APP_KEY cifra sus sesiones. Tiene exactamente 32 caracteres, sin caracteres especiales como =, #, < o >, y el archivo pide guardarla en lugar muy seguro.
• DB_PASSWORD en .env y MYSQL_PASSWORD en .db.env llevan el mismo valor.
• SITE_OWNER: su dirección, que aparece en algunos errores mostrados a los usuarios que no son administradores.
• APP_URL: la dirección pública de su instancia. El archivo explica que sirve para validar ciertas peticiones y para construir los enlaces de los correos electrónicos.
• TZ: su zona horaria, en el formato de la base de datos tz, como muestra el ejemplo del archivo.

Elija la contraseña de la base de datos antes del primer arranque. La base la guarda en su volumen en cuanto se crea: si la cambia después, deja de coincidir, y la FAQ de Docker solo ofrece una salida, eliminar los contenedores y los volúmenes y volver a empezar.

Un puerto publicado en local

El archivo oficial publica la aplicación en el puerto 80 de todas las direcciones del servidor. Para servirla en HTTPS detrás de un proxy inverso en la misma máquina, cambie esta única línea del servicio app:

ports:
  - 127.0.0.1:8080:8080

docker compose -f docker-compose.yml up -d --pull=always
docker compose -f docker-compose.yml logs -f

En el primer arranque, el contenedor crea y migra la base de datos por sí mismo. Cuando termina la instalación, Firefly III le da las gracias en el registro por haberlo instalado: pase entonces al proxy inverso.

• La etiqueta latest sigue la última versión estable. Una etiqueta como version-6.7.9 fija una versión; el proyecto retira las antiguas al cabo de unos seis meses.
• Las arquitecturas: las imágenes se compilan para linux/amd64 y linux/arm64.
• Los volúmenes: firefly_iii_upload guarda los archivos adjuntos y firefly_iii_db, la base de datos.

La documentación no da ninguna cifra de memoria; su FAQ de Docker sugiere PHP_MEMORY_LIMIT=512M o más si PHP se queda sin memoria. El tamaño depende del número de usuarios, del volumen de transacciones y del importador de datos. En un VPS administrado, descríbanos su uso y le recomendamos el tamaño adecuado.

HTTPS y el proxy inverso

Firefly III sirve la aplicación en HTTP por el puerto 8080 dentro del contenedor, y HTTPS reside en el proxy inverso colocado delante. La aplicación lee la cabecera X-Forwarded-Proto para saber que el visitante llegó en HTTPS, siempre que confíe en el proxy:

TRUSTED_PROXIES=*

La FAQ de Docker es clara en este punto: sin TRUSTED_PROXIES=*, los enlaces se quedan en http, los formularios y los gráficos dejan de funcionar y fallan las cabeceras de seguridad CSP. Con el puerto publicado en 127.0.0.1, solo el proxy del propio servidor llega a la aplicación. Recree el contenedor después de cada cambio en el archivo .env:

docker compose up -d --force-recreate app

Con Caddy

Caddy obtiene por sí mismo el certificado de Let’s Encrypt, y su directiva reverse_proxy establece por defecto las cabeceras X-Forwarded-For, X-Forwarded-Proto y X-Forwarded-Host:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Con Nginx y Certbot

Este bloque sigue las cabeceras de la FAQ de instalación, y los búferes que esta sugiere contra los errores 502 cuando la aplicación devuelve un token en una cabecera larga. Escucha en el puerto 80 para que Certbot pueda instalar HTTPS:

server {
    listen 80;
    listen [::]:80;
    server_name finances.example.com;

    client_max_body_size 64M;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 300s;
    }
}

Certbot instala después el certificado y se encarga de renovarlo:

sudo certbot --nginx

• Un nombre de dominio propio: sirva Firefly III con su propio nombre, como finances.example.com. La FAQ señala que Laravel no interpreta una dirección IPv6 en bruto dentro de la URL.
• Los errores 431: la FAQ los atribuye a un límite de tamaño de cabeceras demasiado bajo en el proxy, que hace fallar algunas acciones, como el inicio de sesión.

La primera cuenta y los registros

La primera persona que se registra se convierte en propietaria de la instancia. Como medida de seguridad, los registros se cierran entonces por sí solos: la mayoría de la gente instala Firefly III solo para sí misma.

1. Abra su dirección HTTPS en cuanto el proxy responda y cree su cuenta: recibe el rol de propietario.
2. Active la doble autenticación en su perfil y guarde los ocho códigos de respaldo que muestra.
3. Para abrir la instancia a otras personas, vaya a /settings, abra las opciones de configuración de Firefly III, desmarque la opción que desactiva los registros y guarde.

• La doble autenticación depende del reloj: la FAQ indica que un desfase horario entre el teléfono y el servidor la hace fallar.
• El inicio de sesión con su proveedor de identidad: con AUTHENTICATION_GUARD=remote_user_guard, Firefly III confía en un proxy de autenticación colocado delante, como Authelia o Authentik, que le transmite el usuario en una cabecera.
• Los tokens de acceso: los clientes OAuth y los tokens personales de la API se crean desde el perfil.

La tarea cron

Varias funciones solo se ponen en marcha con una tarea programada: los presupuestos automáticos, las transacciones periódicas, los avisos de suscripción y los tipos de cambio actualizados. La imagen Docker no ejecuta cron por sí misma; el archivo oficial añade para ello un pequeño servicio cron, que llama a la aplicación cada día a las 3 de la madrugada.

Se autentica con un token estático. Genere una tercera cadena con el mismo comando y colóquela en .env:

STATIC_CRON_TOKEN=

Este token tiene exactamente 32 caracteres: el código de la versión 6.7.9 no acepta ninguna otra longitud. Este es el servicio tal como lo declara el archivo oficial; el doble $$ es intencionado y remite a las líneas TZ y STATIC_CRON_TOKEN del archivo .env:

cron:
  image: alpine
  restart: always
  container_name: firefly_iii_cron
  env_file: .env
  init: true
  command: ["sh", "-c", "apk add tzdata && \
    (ln -s /usr/share/zoneinfo/$$TZ /etc/localtime || true) && \
    echo \"0 3 * * * wget -qO- http://app:8080/api/v1/cron/$$STATIC_CRON_TOKEN;echo\" \
    | crontab - && \
    exec crond -f -L /dev/stdout"]
  networks:
    - firefly_iii
  depends_on:
    - app

Una sola tarea basta para todos los usuarios de la instancia. Para comprobar que se ha ejecutado, lea el registro del contenedor: cada tarea informa en JSON, con job_fired y job_succeeded.

docker logs firefly_iii_cron

Para lanzarla a mano, la FAQ de Docker pide pasar por el usuario www-data en lugar de root: la FAQ relaciona este error con problemas de permisos en los archivos de registro:

docker exec --user www-data firefly_iii_core /usr/local/bin/php /var/www/html/artisan firefly-iii:cron --force

MariaDB, PostgreSQL o SQLite

El archivo oficial incluye MariaDB, con la imagen mariadb:lts. Firefly III admite también PostgreSQL y SQLite, que se eligen con DB_CONNECTION en .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

Para PostgreSQL, la documentación cambia además el servicio db a la imagen postgres, que instala PostgreSQL 18, y monta su volumen en /var/lib/postgresql. En .db.env, las variables MYSQL_* pasan a ser POSTGRES_USER, POSTGRES_DB y POSTGRES_PASSWORD.

Tome esta decisión antes de introducir sus primeras transacciones. La FAQ indica que pasar de una base de datos a otra sigue siendo posible, sin que Firefly III lo admita oficialmente, y que la exportación de la aplicación no se lleva todos los datos.

El importador de datos

El Firefly III Data Importer es una herramienta aparte, con su propia instalación y sus propias actualizaciones; su versión 2.3.5 salió el 23 de septiembre de 2026. Importa archivos CSV y CAMT.053, y puede también recuperar las transacciones de sus bancos a través de proveedores de datos externos, cada uno con sus propias condiciones.

El repositorio Docker oficial lo ofrece en un segundo archivo, docker-compose-importer.yml, que conserva los mismos servicios y añade importer. Sus ajustes van en un archivo .importer.env, tomado del .env.example del importador. Sírvalo con su propio nombre de dominio, con un puerto publicado en local y un segundo bloque de proxy: la FAQ pide no colocarlo en un subdirectorio.

FIREFLY_III_URL=http://app:8080
VANITY_URL=https://finances.example.com
TRUSTED_PROXIES=*

• FIREFLY_III_URL: la dirección interna de la aplicación, a la que el importador llega por la red Docker.
• VANITY_URL: la dirección pública de Firefly III, la que conocen sus usuarios.
• El cliente OAuth: en su perfil de Firefly III, cree un cliente cuya URL de retorno sea la dirección del importador seguida de /callback, y desmarque «Confidential». El importador le pide después su identificador de cliente.
• Varios usuarios: deje FIREFLY_III_ACCESS_TOKEN vacío y conserve FIREFLY_III_URL; cada usuario se conecta entonces al importador con su propia cuenta.

Los correos electrónicos: la configuración SMTP

Por defecto, MAIL_MAILER=log escribe los mensajes en los registros en lugar de enviarlos. Para recibir las notificaciones, como los avisos de suscripción, configure el envío en .env. La documentación pide cambiar siempre MAIL_FROM y SITE_OWNER; de lo contrario, no saldrá ningún correo.

En un VPS de Simafri, el envío pasa por un relé SMTP autenticado, en el puerto 587: la dirección de una cuenta de correo que ya tenga, o Simafri Suite.

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_FROM=finances@example.com
MAIL_USERNAME=finances@example.com
MAIL_PASSWORD=account_password
MAIL_ENCRYPTION=tls

• MAIL_ENCRYPTION acepta null, ssl, starttls o tls, según su proveedor; el código de la versión 6.7.9 vuelve a tls cuando el valor está vacío.
• La prueba: la página /settings/notifications envía un correo de prueba, una vez recreado el contenedor.
• Otros canales: las notificaciones pueden ir también a Slack, y a Discord o Mattermost mediante su URL de webhook seguida de /slack.

Las copias de seguridad

Firefly III no incluye ninguna rutina de copia de seguridad: la documentación recomienda las herramientas del propio sistema, y precisa que la función de exportación de la aplicación no es una copia de seguridad. Con Docker, esto es lo que hay que conservar:

La base, con el servicio en marcha

Con MariaDB, mariadb-dump exporta la base sin detener el servicio; su opción --single-transaction ofrece una copia coherente de las tablas InnoDB sin bloquearlas. Ejecutado desde la carpeta del archivo Compose, el comando lee los accesos en el entorno del contenedor:

docker exec firefly_iii_db sh -c 'mariadb-dump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > firefly-$(date +%F).sql

Con PostgreSQL, la misma idea pasa por pg_dump:

docker exec firefly_iii_db sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > firefly-$(date +%F).sql

Programe esta exportación en el servidor al menos una vez al día, y haga limpieza entre los archivos, que se acumulan.

Los volúmenes, con el servicio detenido

La documentación archiva cada volumen con un contenedor desechable. Docker Compose antepone a los nombres de los volúmenes el nombre del proyecto, que por defecto es el de la carpeta: compruebe los nombres exactos antes de lanzar el archivado.

docker volume ls
docker compose stop
docker run --rm -v "firefly-iii_firefly_iii_db:/tmp" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -czvf /backup/firefly_db.tar /tmp
docker run --rm -v "firefly-iii_firefly_iii_upload:/tmp" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -czvf /backup/firefly_upload.tar /tmp
docker compose start

Un nombre de volumen mal escrito no produce ningún error: Docker crea un volumen vacío con ese nombre y lo archiva, lo que sobrescribe la copia anterior. La documentación pide comprobar que el volumen existe antes de cada archivado.

Guarde una copia de .env y de estos archivos fuera del servidor, cifrada, ya que contiene la clave y los accesos a la base. Colocados en el disco del servidor, estos archivos entran también en sus copias de seguridad nocturnas.

Restaurar

La documentación restaura un volumen con el comando inverso, con el servicio detenido; el volumen de los archivos adjuntos se restaura del mismo modo:

docker run --rm -v "firefly-iii_firefly_iii_db:/recover" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -xvf /backup/firefly_db.tar -C /recover --strip 1

Una exportación SQL se vuelve a cargar en la base en funcionamiento:

docker exec -i firefly_iii_db sh -c 'mariadb -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < firefly-YYYY-MM-DD.sql

Restaure también .env con su APP_KEY, vuelva a arrancar y abra sus cuentas. La documentación lo repite tras cada método: lo primero que hay que hacer con una copia de seguridad es restaurarla, para comprobar que funciona.

Las actualizaciones y las migraciones

Firefly III se actualiza por sí mismo, incluso desde versiones tan antiguas como la 4.7, y migra su base de datos al arrancar el contenedor. La documentación advierte de que algunas actualizaciones eliminan o depuran datos, y pide una copia de seguridad de la base y de los volúmenes antes de cada una, sobre todo entre versiones mayores. Desde la carpeta del archivo Compose:

docker compose stop
docker compose pull
docker compose -f docker-compose.yml up -d --remove-orphans

• El ritmo: de la 6.7.0, el 14 de septiembre de 2026, a la 6.7.9, el 11 de octubre de 2026, salieron diez versiones en cuatro semanas. Siga las notas de versión: desde la 6.7.8, una ventana de la aplicación resume los principales cambios de la versión instalada.
• La versión 6.7.0 trajo una nueva interfaz; su motor de expresiones para las reglas viene desactivado por defecto y se vuelve a activar en /settings.
• El archivo Compose: si lo descarga de nuevo, compruebe la versión de la base de datos que declara. La documentación advierte de que una nueva versión mayor de MariaDB puede no reconocer el volumen de la anterior.
• Una migración que no se ha aplicado: desde la 6.4.19, php artisan correction:rollback-single-migration retira la última entrada de migración sin tocar los datos, y php artisan migrate la vuelve a ejecutar, dentro del contenedor.
• Versiones firmadas: el proyecto firma sus versiones, algo que puede comprobar con su clave PGP.

El importador se actualiza del mismo modo, con docker compose rm -f entre la parada y la descarga de las imágenes, según su documentación.

Quién hace qué en un VPS administrado

El autoalojamiento exige mantener el servidor además de la aplicación. En un VPS administrado, nuestros equipos se encargan del servidor y siguen su instancia de forma proactiva; Firefly III sigue siendo su software, con sus ajustes y sus datos financieros.

Si prefiere que nuestros equipos intervengan en la propia aplicación, ese servicio se factura por horas o a precio cerrado, con un presupuesto comunicado antes de la intervención.