[vitormattos]

Incident and verified cause

On 2026-11-10/11, production returned HTTP 500 on the dashboard and invoice edit pages (including invoice 2368). Laravel logged file_put_contents(storage/framework/cache/data/cf/40/...): Permission denied. The two directory segments were owned by root:root with mode 0755, while PHP-FPM executes as www-data (UID 1000 on the deployment). We restored ownership immediately in production; no financial records were modified.

Permanent fix

• On every PHP container startup, repair only misowned files and directories in storage/framework/cache, instead of recursively chowning application files or the financial ledger.
• Provide scripts/artisan.sh to run administrative Artisan commands under the web worker identity, avoiding new root-owned runtime cache paths.
• Document the operating procedure and cover the new behavior in the entrypoint and CLI Bats tests.

Verification

• 11 relevant Bats tests passed (entrypoint, artisan, update).
• A real container ownership regression test verified that root-owned cache directories become writable by www-data while files outside the runtime cache retain their original owners.
• bash -n and git diff --check passed.
• Full Bats suite in the minimal bats/bats image could not run patches and wait-for-db tests because that image lacks Git and PHP; the corresponding tests were not modified.

Deployment note

The immediate issue has already been resolved on Conceição by correcting the two misowned cache directories. The startup self-healing requires a rebuilt/released PHP image (or equivalent deployment of the entrypoint and helper); this PR is not yet deployed. Never run docker compose exec akaunting.php php artisan ... as root: use bash scripts/artisan.sh ... after deployment.