Migrating to V5

Preparing V4.

The first step needed to prepare to migrate your data across to your new V5 installation is to update your V4 installation to the latest version available. This is a critical step and you will see problems migrating your data if you do not update to the latest V4.

Installing V5.

Installing V5 is covered in detail here with resources to cover your needs for Docker / Shared Hosting or Ubuntu/Centos installations.

An important detail with your V5 installation is that your initial user login is identical to your V4 installation.

The migration relies heavily on the Laravel queue system, so you will need to ensure that you have configured the cron scheduler which boots the laravel queue for you. If you do not configure the cron scheduler, the migration will not work and you will end up with a blank company with no content.

Starting the migration

alt text

Navigate to Settings > Account Management and scroll down until you see the Start Migration button.

alt text

After clicking Start migration, you'll get another screen, simply select the self-host radio button and continue.

alt text

The next screen asks for the full qualified domain name of your V5 installation, enter this including the http:// or https:// in your URL, ie

http:://ninja.test

alt text

The next screen requires you to enter your login credentials, remembering that these should be identical between your V4 and V5 installation. You'll also notice an additional field API_SECRET this can be ignore if you do not have a value set for this in your .env file.

If you experience an error at this point, most likely either your credentials are wrong, or the URL you have entered is not correct.

alt text

If you successfully authenticate you'll see the next screen which allows you to select the companies you wish to migrate.

Important points at this stage:

alt text

V5 Migration Process

With a little luck, you should have already received an email notification advising the migration has completed!

There are a couple of things you will want to check to ensure the data has come across correctly:

php artisan ninja:check-data

A series of checks are run and if you see 0 issues, that means your data has come across correctly.

storage/logs/laravel.log

Inside here you will see output such as this:

[2021-01-30 10:46:04] development.INFO: Importing account  
[2021-01-30 10:46:04] development.INFO: Importing company  
[2021-01-30 10:46:04] development.INFO: Importing users  
[2021-01-30 10:46:04] development.INFO: Importing payment_terms  
[2021-01-30 10:46:04] development.INFO: Importing tax_rates  
[2021-01-30 10:46:04] development.INFO: Importing clients  
[2021-01-30 10:46:04] development.INFO: Importing company_gateways  
[2021-01-30 10:46:04] development.INFO: Importing client_gateway_tokens  
[2021-01-30 10:46:04] development.INFO: Importing vendors  
[2021-01-30 10:46:04] development.INFO: Importing projects  
[2021-01-30 10:46:04] development.INFO: Importing products  
[2021-01-30 10:46:04] development.INFO: Importing credits  
[2021-01-30 10:46:04] development.INFO: Importing invoices  
[2021-01-30 10:46:06] development.INFO: Importing recurring_invoices  
[2021-01-30 10:46:06] development.INFO: Importing quotes  
[2021-01-30 10:46:07] development.INFO: Importing payments  
[2021-01-30 10:46:08] development.INFO: Importing expense_categories  
[2021-01-30 10:46:08] development.INFO: Importing task_statuses  
[2021-01-30 10:46:08] development.INFO: Importing expenses  
[2021-01-30 10:46:08] development.INFO: Importing tasks  
[2021-01-30 10:46:08] development.INFO: Importing documents  
[2021-01-30 10:46:09] development.INFO: CompletedπŸš€πŸš€πŸš€πŸš€πŸš€ at 2021-01-30 
[2021-01-30 10:46:09] development.INFO: latest version = 5.0.56  

This example output would indicate that each entity was successfully brought across, if a problem is detected early the migration will fail early and return an error. A Laravel error will also be thrown indicating the exact issue.

Troubleshooting

If you are experiencing issues with the migration not running as expected please run through the following checklist:

Want to contribute? Edit this page on GitHub!