Introduction

NB: To proceed with migrating to v8, make sure you have both v7 and v8 installed on the same server. If you don't have WebMail Lite installed yet, check the installation instructions.

You can download v8 of WebMail Lite at: https://afterlogic.org/download/webmail-lite-php-8

If you have v7 of the product installed on cPanel, please use the other tool: Migration from v7 - console tool

WebMail Lite comes with a migration script dev/migrate_from_p7.php you can use to migrate user accounts, settings, contacts from version 7 of the product to v8 installation.

To prevent unauthorized access to the script, so that it can only be called by the installation owner, the script can only be run with password specified.

What is being migrated

The migration script converts system-level data from v7 installation as well as data of user accounts:

• Common settings
  Language, Refresh every, Date format, Time format, Enable desktop notifications, Messages per page, Contacts per page

• Accounts
  Incoming Mail Login, Incoming Mail Password, Enable threading, Save Replies To Current Folder, System folders, etc.
• Identities
  FriendlyName, Email, Signature
• Social Accounts
• Contacts

• Groups

• Domains (Mail Servers in v8)

Prerequisites and limitations

1. Data migration procedure assumes that both v7 and v8 installations are on the same server. You need to have WebMail Lite installed, with database set up and tables created.

2. The script has been tested with the latest 7.7 release of the product. If you're migrating from at an older version of the product, it's recommended to upgrade first.

3. Currently, WebMail Lite supports MySQL database backend only.

Migration setup

dev/migrate_from_p7.php script contains the following line:

$sP7ProductPath = "PATH_TO_YOUR_WEBMAIL_V7_INSTALLATION";

You need to replace that value with the actual path of your v7 installation.

Also, you need to supply a password as $sPassword value, for example:

$sPassword = 'p54321p';

Migrating all user accounts

In the simplest case, if you wish to migrate all the user accounts, you need to navigate to dev/migrate_from_p7.php script in web browser, supply the password via ?pass URL parameter, for example:

https://yourdomain.com/webmail/dev/migrate_from_p7.php?pass=p54321p

It will prepare database and filesystem structures for copying data and will proceed with migrating user accounts to your v8 installation. After copying each user, the script restarts itself so you can observe the process.

Migrating selected users

If you only need to migrate specific user accounts rather than all of them, start the script with ?user_list URL parameter, additionally to ?pass URL parameter like this:

https://yourdomain.com/webmail/dev/migrate_from_p7.php?user_list&pass=p54321p

The script will create user_list file under data directory, it will contain a complete list of user accounts found on v7 installation. Review the list and remove users you don't need to be migrated. After that, run the script without ?user_list parameter, to migrate those users listed in user_list file.

Troubleshooting

During the migration, script creates a number of files under data directory:

• user_list is generated to maintain complete list of user accounts to be migrated;
• migrated-users lists user accounts migrated successfully;
• not-migrated-users lists accounts migration has failed for;
  (if all accounts migrated successfully, the file is not created)
• migration contains information on the current script run iteration.

Also, if logging was enabled in admin area, log files are created under data/logs directory, their filenames start with migration-.

Restarting migration

If there was an error during the migration and you start the script again, it will proceed from the point where the error has occured. But if you wish to run the migration process from scratch, you need to perform the following steps:

1. Delete migration, migrated-users and not-migrated-users files under data directory.
2. Delete and recreate database tables used by v8 installation.
3. Restart migration script.

Alternative migration approach

You may need to use this approach if the standard one fails for you - for example, when the script isn't able to call underlying scripts due to server configuration. And prior to running a migration script, you will need to run several scripts from command line first.

One of the cases when it's necessary is getting an error: "Error during upgrade DB process. Failed migration from a pre-2.0 database to 2.0."

Step 1.

In dev/migrate_from_p7.php script, specify v7 installation path and a password. Make sure v8 database is blank, with the tables created, then run the script as follows:

http://your-lite-domain/dev/migrate_from_p7.php?pass=12345&stop_before_sabredav_migrate

Step 2.

Please run the following command in console:

cd /P8_INSTALLATION_DIR/vendor/sabre/dav/bin
php migrateto20.php "mysql:host=P8_DB_HOST;dbname=P8_DB_NAME" 'P8_DB_LOGIN' 'P8_DB_PASSWORD'

Be sure to replace P8_INSTALLATION_DIR, P8_DB_HOST etc. with their actual values.

If it reports as successful, repeat the same steps with v2.1 of schema:

php migrateto21.php "mysql:host=P8_DB_HOST;dbname=P8_DB_NAME" 'P8_DB_LOGIN' 'P8_DB_PASSWORD'

If successful, upgrade to v3.0 schema:

php migrateto30.php "mysql:host=P8_DB_HOST;dbname=P8_DB_NAME" 'P8_DB_LOGIN' 'P8_DB_PASSWORD'

If successful, upgrade to v3.2 schema:

cd /P8_INSTALLATION_DIR/vendor/afterlogic/dav/bin
php migrateto32.php "mysql:host=P8_DB_HOST;dbname=P8_DB_NAME" "" 'P8_DB_LOGIN' 'P8_DB_PASSWORD'

Step 3.

If the above step is completed successfully, run the migration script with skip_sabredav_migrate parameter, for example:

http://your-lite-domain/dev/migrate_from_p7.php?pass=12345&skip_sabredav_migrate

Migrating Collected Addresses

This migration script does not migrate Collected Addresses, but it can be done using a separate script:

Migration from v7 to v8 - Collected Addresses