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 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.
Navigate to Settings > Account Management and scroll down until you see the Start Migration button.
Start migration, you'll get another screen, simply select the self-host radio button and continue.
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
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
If you experience an error at this point, most likely either your credentials are wrong, or the URL you have entered is not correct.
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:
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.
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.
When you have completed the migration and are happy with the configuration of your v4 installation, it is time to forward your users with existing v4 invitations to your v5 installation.
In v4 navigate to Settings > Account Management - Forward customers to v5.
Enter in the URL for your v5 installation and click save. When your users use existing v4 links, they will be transparently forwarded to your v5 installation.
For hosted users, you can discover your full URL by navigating in v5 to Settings > Client Portal. The Subdomain field will be whatever the subdomain value is with invoicing.co on the end. ie.
If you are experiencing issues with the migration not running as expected please run through the following checklist:
jobstable in the database, it should be empty
EXPANDED_LOGGING=true Then attempt the migration again and afterwards inspect the log file in storage/logs/invoiceninja.log * If using `https://` ensure you are using a signed SSL certificate, you may get authentication errors if you attempt to use a self signed certificate. Free ssl's are available from [lets encrypt](https://letsencrypt.org) * Still having troubles? search the [forum](https://forum.invoiceninja.com) or come and chat with us on [slack](https://invoiceninja.slack.com) ## Migration Failed notifications The app will do its best to report back a human readable error if the migration fails for some reason. Some known issues when migrating to our hosted platform include:
"This user is unable to be attached to this company. Perhaps they have already registered a user on another account?" ```
If you see this error it indicates that one of your users has already registered their own account on the hosted platform. We do not support cross account users for security purposes. You'll need to change the user's email address in your v4 installation to a different email address for the migration to succeed.
Migration from version 4 to version 5 is only allowed between accounts with the same e-mail address. This is requirement, and before starting the migration, make sure you are using the same e-mail address on both version 4 and version 5 for the user.Want to contribute? Edit this page on GitHub!