[Script request]: Fix error after update Firefly-III

[evkaruna]

Application Name

Firefly-III

Website

https://github.com/firefly-iii/firefly-iii

Description

After updating Firefly-III using the script, an error occurs when accessing the resource. Right now, an error occurred during the update:
file_put_contents(/opt/firefly/storage/framework/cache/data/23/78/2378412ac880c8eb5ff62583c7d16e6bea6a90b8): Failed to open stream: No such file or directory

This error occurred in the file /opt/firefly/vendor/laravel/framework/src/Illuminate/Filesystem/Filesystem.php on line 204 with code 0.

After looking into the problem a little, I came to the following conclusions and fixed the problem myself. I think it would be useful if this problem were taken into account in the future when using the update script.

Issue Report: Cache Directory Permissions Error During Firefly-III Update

Problem Description:
During the Firefly-III update process, the following error occurs when attempting to write to the cache directory:

file_put_contents(/opt/firefly/storage/framework/cache/data/23/78/2378412ac880c8eb5ff62583c7d16e6bea6a90b8): 
Failed to open stream: No such file or directory

This happens at:

Filesystem.php:204 → file_put_contents(...)

Root Cause Analysis:
The error occurs due to permission issues with Laravel's cache directory structure:

1. Missing subdirectories: Laravel requires multi-level cache directories (e.g., cache/data/23/78/), which aren't automatically created during updates
2. Incorrect ownership: After unpacking the update, files are owned by root instead of www-data
3. Insufficient write permissions: The web server process lacks permissions to create new directories in /storage/framework/cache

Reproduction Steps:

1. Run Firefly-III update script as root
2. Observe failure during cache write operations
3. Verify directory structure:

   ls -ld /opt/firefly/storage/framework/cache/data

Solution Implemented:
The following commands resolved the issue:

# 1. Create base cache directory structure
mkdir -p /opt/firefly/storage/framework/cache/data

# 2. Correct ownership
chown -R www-data:www-data /opt/firefly

# 3. Set proper permissions
find /opt/firefly/storage -type d -exec chmod 775 {} \;
find /opt/firefly/storage -type f -exec chmod 664 {} \;

# 4. Clear Laravel cache
sudo -u www-data php artisan cache:clear

Recommendation for Update Script:
To prevent this in future updates, modify the update_script() function in build.func as follows:

# In update_script() after:
rm -rf /opt/firefly/storage
cp /opt/.env /opt/firefly/.env
cp -r /opt/storage /opt/firefly/storage

# ADD THESE LINES:
msg_info "Fixing permissions"
chown -R www-data:www-data /opt/firefly
find /opt/firefly/storage -type d -exec chmod 775 {} \;
find /opt/firefly/storage -type f -exec chmod 664 {} \;
mkdir -p /opt/firefly/storage/framework/cache/data
sudo -u www-data php /opt/firefly/artisan cache:clear
msg_ok "Fixed permissions"

Why This Matters:

1. Permission Consistency: Updates unpack files as root, breaking web server access
2. Laravel Requirements: Cache subdirectories aren't auto-created on first write
3. Stability: Prevents update failures in strict environments (LXC/Proxmox)

Validation:
Confirmed working on:

• Proxmox VE 8.4.5
• Debian 12 LXC containers
• Firefly-III v6.2.20 → v6.2.21 updates

Additional Notes:
Consider adding permission checks to the installation script as well:

# In main install script after:
fetch_and_deploy_gh_release "firefly" "firefly-iii/firefly-iii" ...

# Add:
chown -R www-data:www-data /opt/firefly
chmod -R 775 /opt/firefly/storage
mkdir -p /opt/firefly/storage/framework/{cache/data,sessions,views}

This solution ensures smooth updates while maintaining proper security practices.

I'm new here, so if I've done something that's not in line with the rules, please let me know. I want to help others who are having the same issues I had when updating Firefly-III.

Due Diligence

• I have searched existing scripts and found no duplicates.
• I have searched existing discussions and found no duplicate requests.

[MickLesk]

Next time, you'll probably be 10x faster to just edit the file directly and make a PR with enough description than this long text 😄

PR created: #6119