Restarting/upgrading docker container causes personal access tokens to become invalid

[benradey]

Support guidelines

• I've read the support guidelines

I've found a bug and checked that ...

• ... the documentation does not mention anything about my problem
• ... there are no open or closed issues that are related to my problem
• ... it's definitely a Firefly III issue, not me

Description

When creating a personal access token in containerized Firefly, the token becomes invalid after the container restarts (assuming it is configured to be ephemeral, so "restart" means that the old container is deleted and a new one is generated). The same is true for upgrading the docker image.

This is because the docker-compose.yml file in the docker repo advises to only mount /var/www/html/storage/upload as a persistent volume, but the oauth-private.key and oauth-public.key are written to /var/www/html/storage, which is lost upon container restart.

Changing the persistent volume to /var/www/html/storage solves the problem. I am about to open a PR with the change.

Debug information

Debug information generated at 2025-06-08 15:41:18 for Firefly III version v6.2.16.

System information
Item	Value
Firefly III	v6.2.16 / #25 (expects #25)
PHP version	8.4.7 (64bits) / fpm-fcgi / Linux x86_64
BCscale	12
Error reporting	Display: Off, reporting: ALL errors
Max upload	104857600 (100 MB)
Database drivers	*mysql*, pgsql, sqlite,

Firefly III information
Item	Value
Timezone	UTC + America/New_York
App environment	production, debug: false
Layout	v1
Logging	info, stack / (empty)
Cache driver, session driver	file, file
Default language and locale	en_US + equal
Trusted proxies	**
Login provider & user guard	eloquent / remote_user_guard
Login headers	HTTP_X_AUTHENTIK_EMAIL +
Stateful domains
Last cron job	2025-03-16 04:08:43 (2 months ago)
Mailer	smtp
Exchange rates	Disabled, downloads disabled
RB-column	Disabled

User-specific information
Item	Value
User	#1 of 1
User flags	💳 🕜 📑 📧
Native currency	USD
Convert to native currency?	Disabled
Session start	2025-03-10 00:00:00
Session end	2025-06-08 23:59:59
View range	last90
User language	en_US
User locale	en_US
Locale(s) supported	en_US.utf8: ✅ en_US.UTF-8: ✅
User agent	Mozilla/5.0 (X11; Linux x86_64; rv:138.0) Gecko/20100101 Firefox/138.0

Expected behaviour

Personal access tokens should remain valid after container restarts/upgrades.

Steps to reproduce

No response

Additional info

No response

[benradey]

PR: firefly-iii/docker#24

[JC5]

Hey, thanks for opening an issue.

This is not a bug, and I can't merge your PR.

Although it is true that Firefly III loses both key files upon container restart, they are backed up in the database and restored during the boot process of the container.

You can witness this during boot time:

      Now executing command "correction:restore-oauth-keys"
  [i] Restored OAuth keys from database.

I am not sure why your keys are not restored during boot, but I can assure this is not an issue, or I would have fixed it 7 years ago. Let me know more about your setup, so I can help you fix whatever the issue is.

Cheers,
James

[benradey]

Thank you for the speedy response. Given your reply, I went back and undid my changes, and... it's still working. I can restart the container and the token is still valid. Quite perplexing, but I won't complain.

Anyway, can you teach me why it's preferable to re-create the files on container restart rather than persisting them in a volume?

And generally, thanks for maintaining this software. It's awesome. 👍

[JC5]

Anyway, can you teach me why it's preferable to re-create the files on container restart rather than persisting them in a volume?

On the whole, it isn't. But persisting the entire storage directory means you also persist all caches. These include views, app data and generated php files. At the time it was easier (and less error prone) to backup and restore just the key files. Plus, it prevents financial data being cached in external storage. Less of an argument since the database is also stored externally, but still.

These days, Laravel's cache:clear routine is a little more robust, so in theory I could change it up. But that also means supporting both ways for eternity, because a lot of users will not change their Docker compose files anyway. So it's less of a maintenance burden to keep it as it is.

Thanks for the compliments, I appreciate it :)