WebMail Lite Documentation

Upgrading instructions

Please use the following instructions to upgrade from previous v9.* of WebMail Lite to the latest version.

If you need to upgrade from from v8 of WebMail Lite, please see Upgrading from v8 section below.

  1. Create complete backup of your existing installation and the database. You can use tools like PhpMyAdmin or mysqldump to get a database backup.

  2. Remove all the installation files except for data/ subdirectory.

  3. Download and extract new product package, copy all the subdirectories and files where the previous installation was located; data/ subdirectory must however remain intact.

NB: The package includes .htaccess file with adjustment directives to make CSRF protection work; getting Error 500 may mean you have mod_rewrite disabled. Read more on this at CSRF protection documentation page.

  1. Log into /adminpanel/ as superadmin, navigate to Database Settings screen, click "Create/Update tables" and "Update configuration" buttons.

If you have an installation with large number of users, contacts etc., it's recommended to update tables via command line instead:

php system/bin/console migrate
  1. NB: In version 9.7.7 database structure was significantly changed with regard to contacts. If you're upgrading from a version prior to 9.7.7, be sure to run the following script to migrate the contacts:
php dev/migrate-contacts-to-dav-cards.php 
Version 9.8 of the product brings several security improvements. Though the product will keep functioning correctly upon performing the standard upgrade, we strongly recommend to update encryption key.

To update encryption key, run the following script:

php ./dev/update-encryption-key.php

and follow the on-screen instructions. The script will update encrypted passwords stored in the database (account passwords, SMTP server relay passwords etc.) as well as encrypted values in configuration files of several modules.

Upgrading from v8

If you need to upgrade from v8 to v9, the approach is very similar to standard upgrading instructions above.

NB 1: The migration was only tested with the latest v8 release, so be sure you're on the latest 8.8 version, if not - upgrade it first, per the above guidelines. You can download the latest v8 at: https://afterlogic.org/download/webmail-lite-php-8

NB 2: Migration from v8 should be performed by upgrading to version 9.6.2 first, and then to the latest one. You can download v9.6.2 at: https://afterlogic.org/download/webmail_php-962.zip

If you're on v7, you'll need to migrate to v8 first.

  1. Create complete backup of your existing installation (including data/ directory) and the database (this is just in case, as database will still be usable by v8 upon the migration).

  2. It is very important that users don't access the upgraded installation before the migration is done. We recommend to create a new directory for v9 installation, with some complex name user can't guess and cannot access.
    Download and extract new product package, copy all the subdirectories and files where the installation is located - except for the data/ directory, that one should be copied from v8 installation.

It's recommended to do the migration from console. If you don't have access to command line, see Web-based migration section below.

  1. Do NOT create/update tables in Database Settings screen of AdminPanel. Instead, run the following command from within main WebMail Lite installation directory:
php system/bin/console migrate
  1. Run the migration using the following command while in main WebMail Lite directory:
php system/bin/console migrate:eav-to-sql

Migration progress will be displayed in console. Should the migration get interrupted for any reason, run it again and it will resume from the last item successfully migrated.

Logs and other relevant information will be placed under data/migration-eav-to-sql/ directory.

If, for any reason, you need to restart the migration, wipe v9 database tables with:

php system/bin/console migrate:eav-to-sql -w

and remove data/migration-eav-to-sql/ directory, then run the migration again.

  1. Once the migration is completed successfully, you can move/rename the existing v8 installation directory and replace it with the new v9. It's also safe to delete all the database tables which aren't used by v9:
  • au_eav_attributes_bigint
  • au_eav_attributes_bool
  • au_eav_attributes_datetime
  • au_eav_attributes_double
  • au_eav_attributes_int
  • au_eav_attributes_mediumblob
  • au_eav_attributes_string
  • au_eav_attributes_text
  • au_eav_entities

Web-based migration

  1. If running migration from console isn't an option for some reason, you can use a web-based migration script for that. First, backup the installation and make sure users cannot access the upgraded installation, per above guidelines.

  2. In v9 installation, configure database connection details - but do NOT create tables from there. Instead, download the script, unpack it into dev/ subdirectory and run it from the browser, it should create all the database tables required. For example:
https://webmail.yourdomain.com/dev/db_init.php
  1. Modify dev/migrate.php file and specify $sPassword value there, then run the script from browser with that value specified, for example:
https://webmail.yourdomain.com/dev/migrate.php?pass=mypasshere

Should the migration get interrupted for any reason, run it again and it will resume from the last item successfully migrated.

Logs and other relevant information will be placed under data/migration-eav-to-sql/ directory. If you encounter issues, be sure to provide us with that directory content as well as console output via HelpDesk.

  1. If, for any reason, you need to restart the migration, wipe v9 database tables with:
https://webmail.yourdomain.com/dev/migrate.php?pass=mypasshere&wipe=1

and remove data/migration-eav-to-sql/ directory, then run the migration again.

  1. Once the migration is completed successfully, you can move/rename the existing v8 installation directory and replace it with the new v9.