Clarification on V5 Software Updates

Self-Hosted | v5
1

Now that I’m nearly finished migrating from v4 to v5, I have some clarification questions about software updates for InvoiceNinja v5. I’m unable to run the built in updater (most likely due to memory limits), so I’m looking into updating the way I always have with v4; the file copy route.

Question 1: Is there a certain stable update version scheme I should wait for?

Are there specific updates, such as, every 5.4.0, 5.5.0, 5.6.0, etc. that are considered the “stable” releases? Or is every release a stable one? The only reason I ask is because looking at the InvoiceNinja repository, there’s an incredible amount of releases in short time spans (six releases in the last 10 days), leading me to wonder which are the most tested versions. Are there certain ones I should wait for, or would you say it’s safe to go ahead and update any time a new version is available?

Question 2: Is upgrading from any v5 version to another v5 version always supported, regardless of gap?

For example, if I want to upgrade to a future release of 5.6.12 (doesn’t exist yet), should I first upgrade to 5.6.0, and then to 5.6.12? Or is any path okay, such as 5.5.102 to 5.6.12?

Question 3: When updating, should I download the InvoiceNinja.zip file or one of the Source Code files (zip or tar.gz)?

I’ve read the Self Host Updating guide here, which says:

The 2 “Source code” files are the correct ones, the other is the fully built package which includes the “.env” file, if that file is overwritten, then your configuration is also gone

This seems odd to me for a couple reasons:

  • Neither the InvoiceNinja.zip or the Source Code files have a .env file, just the .env.example file, so nothing will ever be overwritten.
  • When comparing the InvoiceNinja.zip file to the Source Code files, it appears the full InvoiceNinja.zip file contains the Vendor folder, where as the Source Code files do not. If I download the full InvoiceNinja.zip file for version 5.5.102, and the InvoiceNinja.zip file for a release from a couple weeks ago, the vendor folder is a different size and contains different amounts of files. Would this not indicate there were changes to the vendor folder as well, and therefore, when updating, I should always use the InvoiceNinja.zip full install file and replace everything (leaving behind the .env file with my configurations)?

Any clarification would be greatly appreciated!

2

Hi,

  1. We recommend using the latest available version
  2. You should be able to update between any v5 versions
  3. The v5 app provides a built-in app update process
3
  1. We recommend using the latest available version
  2. You should be able to update between any v5 versions

Great, thanks!

  1. The v5 app provides a built-in app update process

It does, but I’m still curious about the file method if the in-app update process fails, for example, due to the host having low memory allocated. I just want to ensure the instructions on the upgrade page here are correct, due to the concerns I have above. Right now, it doesn’t make sense why I wouldn’t want to use the InvoiceNinja.zip file since the contents of the Vendor directory have changed between versions. Would one not want that directory to be updated as well between versions? The .env file also doesn’t exist in either the InvoiceNinja.zip or the Source Code downloads, so I’m thinking the instructions must be outdated, or I’m not understanding something. Just want to make sure they’re accurate.

4

@david can you please advise?

5

For the record, I also just bumped up my PHP memory limit and ran the updater from 5.5.99 to 5.5.102. The update ran for a little bit and then said “Update complete” at the end, and then the web interface refreshed. I still have a blue warning triangle in the bottom left telling me I’m on 5.5.99 and that 5.5.102 is available.

So far, the file method (once we figure out what the proper way of doing that is) is looking the most reliable.

EDIT

Simply ran the update again, and it worked the second time. It now shows version 5.5.102. Not sure what happened the first time since both times ended with “Update Complete” and an automatic refresh of the page.

6

@link470

The update process pulls in the invoiceninja.zip file prebundled and built ( the exact same one you would download from the release section)

We then just unzip this and overwrite all the files, run the migrations and update the cache and that is the update process completed.

.env file does not get carried over as you don’t want that file to be overwritten.

7

Gotcha, thanks very much David. This makes sense. I think the documentation here should be updated to say to overwrite the whole codebase using the InvoiceNinja.zip file (ensuring to preserve the .env file; as in not delete it), instead of one of the source code files. Otherwise, the vendor directory will never get updated if someone does a manual update (not using the built-in updater).

8

@david - I’ve been trying unsuccessfully to go from 5.5.102 to 5.5.104 for the last little while using the built in updater. PHP has a 512MB memory limit, as I believe was the recommended amount by InvoiceNinja. But still, server resources skyrocket for a few minutes, and then php-fpm crashes.

If the auto updater won’t work reliably without allocating more resources, I think I’m back to doing the manual file update route. However, this then brings me back to my concern above. You say what the auto updater is doing is:

The update process pulls in the invoiceninja.zip file prebundled and built ( the exact same one you would download from the release section).

We then just unzip this and overwrite all the files, run the migrations and update the cache and that is the update process completed.

But the update documentation here says:

If the update button does not work, you can alternatively download the “Source code” and overwrite the folder of your installation, note that there are 3 files always:

invoiceninja.zip - 170 MB or 500 MB roughly
Source code (zip) - 15 MB roughly
Source code (tar.gz) - 14 MB roughly

The 2 “Source code” files are the correct ones

So, if I’m understanding this correctly, the auto update method uses the invoiceninja.zip file, but the documentation says use one of the other two files (the source code ones). This seems conflicting to me. The source code files don’t contain the vendor directory, so how will I ever get a full update if I use the source code files only, and if the vendor directory contains changes between versions? It seems to me like one should always use the invoiceninja.zip file to update, because the source code directory doesn’t contain all the changes.

The other question is what happens if I’ve downloaded snappdf (which I have)? Can I safely update my installation without accidentally removing snappdf and requiring me to reinstall it? Is snappdf safely installed outside of the installation directory when using the InvoiceNinja documentation to install it, and therefore won’t be affected? I installed with sudo -u www-data vendor/bin/snappdf download

Here’s my plan:

  • Backup my current Invoice Ninja root path, and then delete all files in the root path except .env
  • Download the invoiceninja.zip file and extract it to the Invoice Ninja root path (safe, because invoiceninja.zip doesn’t contain.env, only the example/dusk/travis files).
  • Ensure all the files have the correct permissions (owned by the web server user)
  • Run https://example.com/update?secret= where example.com is my InvoiceNinja directory, and the update secret ends with the update secret from my .env file.

Does this sound right, and will this retain snappdf?

This would essentially be what I did with InvoiceNinja v4, but without the last step (with v4, the database upgrade happened automatically when you visited the web app afterwards).

Also, the documentation says nothing about stopping Supervisor or pausing/commenting out the cron that runs every minute. Should this be done too while swapping the files?

9

@link470

I’ve updated the self upgrade docs to specify invoiceninja.zip as the correct file.

Snappdf should survive any updates as the system only overrwrites files, without deleting old ones.

The only other requirement would be once the file have been copied over is to run /update?secret= so that the migration runs, and then finally restart the queue to update the in memory version of the application that the queue uses to run tasks.

No need to do anything with the cron at all.

10

Thanks very much @david , that helps a lot. A couple more clarification questions.

Snappdf should survive any updates as the system only overrwrites files, without deleting old ones.

Ah, so, my first step in my plan was to “Backup my current Invoice Ninja root path, and then delete all files in the root path except .env” which worked fine in v4, and then I’d copy in the new files/directories, leaving only .env from my previous set of files. This makes me think snappdf wouldn’t survive, because I’m copying down a brand new set of files every time, with the exception of keeping my old .env file. Should I be instead just leaving all the existing files in place and overwriting them, instead of deleting them all? My concern I had with not deleting them all and instead just overwriting was that if, say, files were removed from a future version release, they’d never be deleted from my installation, which would leave potentially outdated/insecure files in a web accessible directory.

If, after second thought, you think this would indeed be destructive to my installation for snappdf or other elements, should there be other files or directories I exclude from deletion (along with .env) before copying over the new files/upgrading? I’m thinking something similar to how in WordPress installations, you delete everything except wp-config.php and the wp-content directory, but copy over all the new files otherwise, and overwrite the wp-content directory so only changed files are updated but everything else stays in place. That leaves all your plugins and themes untouched, but upgraded/replaced if a newer version exists in the new version’s files.

The only other requirement would be once the file have been copied over is to run /update?secret=

Gotcha, that makes sense; I saw that in the documentation. Looking in the .env file, my update secret is just ‘secret’, but I don’t recall seeing anywhere in the setup that I should change this. In fact, the whole v5 self hosted installation page doesn’t mention the word ‘secret’ once. Should this be changed to a random string? I’m assuming now I’d just run /update?secret=secret.

11

It shouldn’t hurt to leave existing files, and instead just copy over the old ones. It makes the upgrade path simpler.

The self host update page has a small snippet on /update?secret

12

Thanks @david !

It shouldn’t hurt to leave existing files, and instead just copy over the old ones. It makes the upgrade path simpler.

Ok, if that’s the supported/recommended method, I’ll do that. It’s different than v4, and still feels a bit odd to me to leave potentially old or unused files behind and not cleaned up. But, as you say, if that’s how the built-in updater is working anyways, I’ll do that.

The self host update page has a small snippet on /update?secret

I see on this page at the very end that it mentions to access that URL and that the value of UPDATE_SECRET can be found in the .env file, but it doesn’t specify if I should change the value or not. That makes me think a bunch of v5 installations out there are simply running with a secret of ‘secret’. Is this by design, or should this be changed? If it should be changed by the user, I think that should be documented somewhere as well in the installation guide. Otherwise I’ll leave it as ‘secret’ if that’s intended.

13

Hi @david , just looking for confirmation/clarification on the above two things when you have a moment. Thanks again!

14

There is no huge security issue leaving the update secret as the default, however the option is there to protect it for those that prefer to lock down everything.

15

Thanks @david . I’m still a little unsure of leaving all the files behind and simply overwriting every time, especially seeing as just overwriting leaves rather large files behind.

In /InvoiceNinjaDirectory/storage/app, I found the invoiceninja.zip files that Invoice Ninja had tried to download when PHP FPM crashed during my last few update attempts:

invoiceninja.zip
invoiceninja.zip.temp643b405739621
invoiceninja.zip.temp643b4cb3b41ee

I’m assuming these are safe to delete?

Also, in /InvoiceNinjaDirectory/storage/logs, the laravel.log file is in here and is currently a gigantic 5GB in size, after hardly using the application at all over the last couple weeks since it’s been installed. Does this ever get trimmed down during any sort of automatic task? Is there a way to not make the log so chatty, or disable logging except when I need it for troubleshooting? Or does the app itself rely on log data for things and this isn’t safe to delete?

16

The files would never be very large, as they would only be the php files themselves of the application

The .zip files can be deleted, no issues with those being deleted.

I made a configuration change recently for the log files, they will be rotated daily and only a 7 day history will be kept, this should improve the storage considerations.

17

Perfect, thanks @david ! I’ll go ahead and try an update and see how it goes.

I made a configuration change recently for the log files

What version was that introduced? I’m on 5.5.102 and will be going to 5.5.104.

18

@link470

On review the changes won’t be available unless you change the logging from stack to daily on the .env file

19

changes won’t be available unless you change the logging from stack to daily on the .env file

Thanks @david , just to confirm, I’m changing LOG_CHANNEL=stack to LOG_CHANNEL=daily, is that correct? Once that’s done, do I need to do anything else for the changes to take effect, or does simply saving the file cause the logging to change immediately?

20

You may need to update the cache/config by running /update?secret=

I believe in .104 and onwards the need to run /update?secret= is no longer necessary after changing the config.