WebMail PHP ( Client-mode ) Source Installation and Configuration Guide

• 1. WebMail Client introduction and the installallation script
• 1.0 Before you install: requirements and dependencies
• 2. Installation
• 2.0 Download and extract WebMail Client
• 2.0.0 SSH web server access
• 2.0.1 FTP web server access
• 2.1 Installation Wizard
• 2.1.0 WebMail Pre-installation check
• 2.1.1 Select Language and License
• 2.1.2 SQL Server Setup
• 2.1.2.0 Troubleshooting
• 2.1.3 SMTP and Admin Email Configuration
• 2.1.3.0 Troubleshooting
• 2.1.4 Register software license
• 2.1.5 Secure the Webadmin and WebMail
• 2.1.5.0 Troubleshooting
• 2.1.6 Migrating from another WebMail product
• 2.1.7 Installation complete
• 3 Contact Support

1. WebMail Client introduction and the installation script

This document will explain how to install your WebMail Client software utilizing it's simple, web-based, installation script. The WebMail Client should be installed when you wish to use WebMail software with your existing mail services.

NOTE: You must have an existing POP3 and/or IMAP server, and an existing SMTP server to run the WebMail Client software.

1.0 Before you install: requirements and dependencies

• MySQL Libraries - http://www.mysql.com/
  
• Apache Webserver - Usually installed by default with most Linux Distributions and Unix Variants - http://httpd.apache.org/
  
• PHP 4.X or newer - http://www.php.net/
  
• PHP MySQL support - http://us2.php.net/mysql
  
• Mail Parse extension - PECL :: Package :: mailparse. http://pecl.php.net(For Red Hat based systems you can use the php-pecl-mailparse package found in the DAG repository.)
  
• Set Max Filesize Upload PHP variable to 16MB or higher - Set the php.ini variable upload_max_filesize to larger than 16MB (higher for larger attachment support). Usually php.ini is located at /etc/php.ini. You will need to restart the web server to enable this change.
• Set Safe Mode PHP variable to Off - Set the php.ini variable safe_mode to Off. Usually php.ini is located at /etc/php.ini. You will need to restart the web server to enable this change.

Once you have installed any required software, you may proceed to installing WebMail Client on your web server!

2.0 Download and extract WebMail Client

Download the WebMail archive and extract it in a temporary location, such as /tmp.

gunzip webmailphp53.tar.gz
tar xvf webmailphp53.tar

Move the webmail directory under your web server's DocumentRoot, or VirtualHost directory (these can be found in your apache configuration file. Here is a rough guide to a few distribution defaults:

• Red Hat based distributions : /var/www/html(default user is apache)
• SUSE based distributions : /srv/www/htdocs(default user is wwwrun)
• Debian based distributions : /var/www/apache2-default(default user is www-data)

mv /tmp/webmail/ /path/to/documentroot

Next, change the ownership of the directory to the web server user. This is required for WebMail to save configuration files via the web and used during the install process. For example:

chown -R apache /path/to/documentroot/webmail/

2.1 Installation Wizard

You are now ready to access your website and begin the installation process.
Point your browser to your webserver http://yourdomain.com/webmail/ (replace yourdomain.com with your actual domain)

This will bring up the installation wizard screen:

Note:

Please ensure that /var/www/html/webmail is writable by webserver user. See the installation documentation for the complete tutorial on installing WebMail

This is caused when the directory of WebMail is not owned by the web server user, which is required for the installer to be able to save the global configuration file. To change the permissions run on the command-line: chown -R [webserveruser] /var/www/html/webmail Where [webserveruser] is the user which runs Apache ( Generally user apache, nobody or www ) You can try to find out the correct user that your web server runs under with one of these commands:

ps auxw | grep httpd
# or
ps auxw | grep apache

2.1.0 WebMail Pre-installation check

At the WebMail Pre-installation check screen, you will be shown information any problems with needed server software and PHP settings. You may end up needing to make some changes to your /etc/php.ini file, or find that you need to install various software dependencies.

When you are ready, select Continue to proceed with the installation.

2.1.1 Select Language and License

Please select a default language and read through the license agreement. Select Yes I agree to the above license and Continue once you are happy with the license agreement and language.

2.1.2 SQL Server Setup

If possible use a non-privileged mysql account, not the default root user. The default database name is atmail. If this is a new installation, you should see check boxes that allow you to create the WebMail database and it's tables.

NOTE: If you are re-installing WebMail with an existing database make sure to remove any check mark in the database creation options.

Select Continue when you are ready to proceed.

• If you have PHP installed, but without the Mysql database extensions, the installer will alert these are missing. To proceed you must install the PHP mysql extension, for example using Fedora run:

  root# yum install php-mysql

  Once installed, restart Apache for changes to take effect

  service httpd restart

  Then refresh the installer page to continue with the mysql installation.

• If you receive the error message =Can't connect to local MySQL server through socket '/var/lib/mysql/mysql.sock', make sure mysql is installed and running on the localhost or specified server.

  If running RH Fedora, you can validate the mysql-server is installed by running:

  yum install mysql-server

  Then start the service:

  service mysqld start

2.1.3 SMTP and Admin Email Configuration

Next, you must define the SMTP hostname for WebMail to send outgoing messages. By default the localhost SMTP server is used, you may need to define another SMTP server if one is not running on the local server.

Make sure you have access to relay messages via the SMTP server and that the IP address of your server is allowed to send messages.

Next, define the administrative email-address, this address will be used in the WebMail interface to notify end users of who to contact for support.

Select Continue when you are ready to proceed.

2.1.3.0 Troubleshooting

If you receive the error message 'Could not connect to the specified SMTP server', verify the SMTP hostname is correct, and you have access to relay messages.

2.1.4 Register software license

You must register your copy of WebMail. Please follow the links to generate a new serial key so as to most accurately reflect this installation.

Select Continue when you are ready to proceed.

2.1.5 Secure the Webadmin and WebMail

WebMail includes an administration panel which is used to control users, modify system settings, view logs and run system maintenance tasks. You should specify the username and password you wish to use for the WebAdmin panel. The installer will create an Apache .htaccess file to password-protect the directory.

NOTE: You may not need to insert the line that starts with AccessFileName if this setting is already present in your Apache configuration.
NOTE: Most hosted sites already have the AccessFileName and AllowOverride parameters set correctly. If you do not have access to the Apache server configuration, you can just continue, and check after the installation that you do receive a password prompt when accessing webadmin. If you do not receive a password prompt, you should contact your hosting provider to adjust these settings for you.

If possible/necessary, edit your httpd.conf (or appropriate .conf file for Apache) and insert these lines:

AccessFileName .htaccess

    AllowOverride All

If you made changes to Apache configuration, you will need to restart the service. For most systems, one of the following lines will work:

/etc/init.d/httpd restart
/etc/init.d/apache restart
/etc/init.d/apache2 restart

When you are sure that .htaccess files will work properly on your web server, select Edit httpd.conf, then Continue.

2.1.5.0 Troubleshooting

• If you forget or lose the password for the WebMail WebAdmin, you can remove the file /path/to/webmail/webadmin/.htaccess. Removing this file will remove the WebAdmin password prompt. Next, access the Webadmin > Security > Admin password to specify the new password

• Once complete WebMail will create a configuration file (/path/to/webmail/libs/Atmail/Config.php) based on the information you provided during the installation.

• You can optionally edit the configuration file manually if you want to define settings, or preferrably use the inbuilt Webadmin panel:

  http://url.com/webmail/webadmin/

• Once logging into WebMail, if you receive the error "DB Error: no such database" - Verfiy that you have successfully defined the correct mysql details in the installer.

• To reset the installation wizard and start from scratch, edit the configuration file

  /path/to/webmail/libs/Atmail/Config.php

  And remove the

  'installed' => 0 

  line.

  Next remove the /path/to/webmail/install/.htaccess file, and reload the WebMail URL to continue installation from the beginning again.

• If you receive the error message when loading WebMail:

  Warning: fopen(html/english/login.html): failed to open stream: No such file or directory in /var/www/html/phpport/webmailphp/webmail/libs/Atmail/Global_Base.php on line 205 cant open html/english/login.html

  This is due to the HTML templates for the specified language not been built. To enable run the following command via the command-line:

  cd /path/to/webmail/ ; php lang.php english lang/languages/english/english.lang

  Where english is the language from the error message above

2.1.6 Migrating from another WebMail product

If you are migrating from another WebMail system, select the software you are migrating from using the dropdown box and click Migrate. If you are starting a fresh install, or your system is not listed, then click 'Continue'.

2.1.7 Installation complete

Your installation is now complete and ready to use.