Installing HiveMail
===================

This document will guide you through installation of HiveMail. If at
any time you are stuck or feel like you need help, please do not
hesitate and contact us at install@hivemail.com. This is an offline
version of our installation guide at:
http://manual.hivemail.com/installation.html


TABLE OF CONTENTS:
------------------

  Chapter 1. Preparations and Uploading Files
  Chapter 2. Installing the Web Interface
  Chapter 3. Installing the Email Gateway
  Chapter 4. Installing the POP3 Gateway
  Chapter 5. Installing the Pipe Gateway
  Appendix A. Telnet and SSH
  Appendix B. SMTP Server Information


1. PREPARATIONS AND UPLOADING FILES
-----------------------------------

  After downloading the HiveMail zip archive from the Members Area,
  unpack the files in it to your computer, ensuring that you maintain
  the directory structure (a tool such as WinZIP will get the job done).
  You should now have two folders, email and upload, and two files called
  UPGRADE and INSTALL.

  Find the file config-dist.php located in the /upload/includes folder and
  rename it to config.php. After renaming the file, open it using a plain
  text editor (such as Notepad). This file contains the configuration
  values for your MySQL database. These settings are as follows:

  * server: The hostname or IP address of the MySQL server you will be
    using. Usually, you may leave this set to localhost, unless the MySQL
    server is on a different machine than your Web server.
  * database: The name of your MySQL database. Please note that this
    setting is not like the server setting above - database refers to the
    name of your database, while server points to the MySQL server.
  * username and password: The username and password that is used to log
    on to the MySQL server. This may be the same as your FTP login
    information, but that's not for certain.
  * persistent: This is a boolean (yes / no) setting that controls the
    type of your connection HiveMail makes to the MySQL server. If this is
    set to 1 (or true), the program will create a persistent connection to
    the server that can be used by more than one user, thus using less
    connections overall. If this is set to 0 (or false), the program will
    create a regular connection that will only serve one user.

  To change the value of a setting, edit the value that is between the
  set of single quotes (i.e: 'value'). Do not remove the single quotes
  that surround the value or the file will not be functional.

  Once you are done editing the values in config.php, save it and exit
  the text editor. You are now ready to upload the files to your Web
  server. Log on to your site using your favorite FTP client, and create
  a folder where you'd like the program to be available from. This
  folder should be below your document root, which is usually /htdocs,
  /public_html or /www. You need to upload all files from the local
  /upload folder to the remote folder you have just created.


2. INSTALLING THE WEB INTERFACE
-------------------------------

  Now that the files are on your Web server, you are ready to install
  the program. To do so, point your browser to the /install folder - for
  example, if you uploaded the files to
  http://www.example.com/hivemail/, you should go to
  http://www.example.com/hivemail/install/. After each and every step
  you will see a link at the bottom of the page with an arrow, click it
  to proceed to the next step.

  If PHP is installed and configured correctly, you will see the welcome
  screen with some information about your installation. If instead you
  are presented with a message telling you PHP is not running, you will
  need to contact your host and make sure PHP is installed on your Web
  server and configured properly.

  The first step in the installation script is to make sure the values
  you've entered in the config.php file are correct. After the script
  tries to connect to the MySQL server, it will let you know if the
  connection was successful. If it was not, you will need to edit
  config.php again and make sure all settings are correct. If you still
  can't get it going, contact your host and ask for your MySQL login
  information.

  After the script successfully connects to the server, it will try to
  use your database. There are two things that may cause a failure in
  this step:

  * Wrong database name: The name of the database you've entered in the
    config.php is wrong. In this case, you will need to edit config.php
    again and make sure the name is correct.
  * Database doesn't exist: It could be the database you are trying to use
    does not exist. In this case, the script will attempt to create the
    database automatically. If this too fails, you will need to either
    create the database yourself or contact your host and ask them to
    create it for you.

  If all goes well, the script will attempt to create the data tables in
  your database. If the database you are using is not empty, you will be
  notified and given the option to reset it (note that resetting the
  database means permanently deleting all information in it). It is
  important that your database does not contain any table that is used
  by HiveMail, or else there will be clashes. After creating the tables
  the script will populate them with default data (such as default
  options, user groups, templates, etc).

  The next step is to set you up as an administrator in the system and
  set the details of the program. The fields you need to fill in are as
  follows:

  Administrator:
  * Username: This is the username of the administrator account. For
    example, set this to admin and the email address will be
    admin@example.com. This is also the username you will be using to log
    on to the Administrator Control Panel, later.
  * Password: The password for the administrator account. This password
    should be strong and hard to guess - otherwise anyone that would guess
    it will be able to log on to the Administrator Control Panel and do as
    he wishes in it.
  * Real name: Your full real name. This will only be used for your email
    account, any outgoing messages will have this name sent with them.
  * Secret question and answer: In case you forget your password in the
    future, you will be required to provide the secret answer to this
    secret question in order to get a new password.

  Options:
  * Application name: Set this to the name of the program that will be
    running on your Web site. For example, if your site is named
    "Example.com", you would want to set this to "Example.com Mail" or
    something else to that effect.
  * Domain name: The domain name under which the program will run. This is
    important, since only mail that is directed to this domain will be
    collected by the program. The script will try to automatically set
    this option, but you might need to do it yourself. This option
    requires a preceding '@' character, so if your site is at
    http://www.example.com/, this setting should be set to @example.com.
  * Program location: This is the complete address of your HiveMail
    installation, without any trailing slashes. You can see this address in
	the address bar in your browser, so for example if you are browsing
	http://www.example.com/webmail/install/index.php?step=6, you will need
	to enter http://www.example.com/webmail in the field.

  (The system will try to automatically detect the last two settings,
  domain name and program location.)

  That's it, you have successfully installed the Web interface of
  HiveMail! As an administrator you can log on to the HiveMail
  Administrator Control Panel, where you can control each and every
  aspect of the program. To get there, point your browser to the /admin
  folder - for example, if you uploaded the files to
  http://www.example.com/hivemail/, you should go to
  http://www.example.com/hivemail/admin/. Be sure to delete the /install
  folder from your Web site, or else you will not be able to log on to
  the control panel (for security reasons). Next stop - installing the
  email gateway.


3. INSTALLING THE EMAIL GATEWAY
-------------------------------

  Installing the Web interface was the first part of installing
  HiveMail. Now it's time install the email gateway, that is - the
  program that collects mail from your server and delivers it to your
  users.

  HiveMail gives you a choice between two gateways:

  * POP3 interface: This option uses a 'CatchAll' POP3 account on your
    server that receives all mail that is sent to your domain name.
    HiveMail automatically checks this account and collects mail from it
    every time someone uses the program. It is much easier to install,
    compared to the other option below, but not as instant, since mail is
    only collected when a user visits the system and not when it actually
    arrives.
  * Pipe interface: The idea is to direct all mail that's received to a
    PHP script that delivers it to right mailbox. Unlike the POP3
    interface, this is a bit harder to install and operate. On the other
    hand, mail is collected and delivered instantly, because the script is
    executed whenever a new email arrives. Installing this interface
    requires access to Telnet or SSH, so if you are not familiar with
    these protocols it's recommended that you use the POP3 interface
    above.

  Please note that you only need to install one of these gateways, not
  both of them.


4. INSTALLING THE POP3 GATEWAY
------------------------------

  The POP3 gateway can operate in two ways. The first option is to check the
  account for messages automatically, on the server itself and without user
  interference. This is done by setting up a cron job - a script that the
  server will run automatically, every predefined number of minutes (orhours).
  The second option is to have HiveMail check the POP3 account when a user
  logs into the system, and with this option you can also limit the checking
  to only once every predefined number of minutes. However, we do not
  recommend the second option, since your users will have to wait while the
  account is checked before the page is displayed to them (when the script
  checks the account). It is still offered as an option to users who cannot
  set up a cron job on the server.

  If you choose the first option (using a cron job), you first need to upload
  one script to your Web site. Before uploading the script, we need to make a
  couple of changes to it to make sure it fits your server. The file in
  question is pop.cron.php, located in the /email folder you unpacked from the
  ZIP archive earlier. Open the file using a plain text editor (such as
  Notepad). The two things we need to alter are:

  * The path to PHP: After openning the file you will see this in the very
    first line:

      #!/usr/bin/php -q

    This is the path to the PHP binaries. On each server this path may be
    different, although it is usually either /usr/bin/php or
    /usr/local/php/bin/php. To find out the path on your server, contact
    your host or run the whereis php command from telnet or SSH. If the
    path on your server is, for example, /usr/local/php/bin/php, you need
    to change the line above to:

      #!/usr/local/php/bin/php -q

  * The path to HiveMail: About 20 lines below, you will see a large box
    with CONFIGURATION at the top. Please thoroughly read the instructions
    in that area, and update the $hivemail_path with the correct path to the
	folder HiveMail is installed in.

  After you are done editing the file, save it and close the editor.
  Now, upload pop.cron.php to your server through FTP. It
  doesn't particularly matter where you upload this file, but we
  recommended that you place it outside your Web root (that is, above
  your document root, which is usually /htdocs, /public_html or /www).
  After uploading the file, change the mode of it (CHMOD) to 0755. In visual
  FTP clients this can usually be done by right-clicking on the file and
  choosing the appropriate option.

  Once the file is uploaded, setting up the cron job for the script can be
  usually done from the control panel your host provided for your site. If
  you are unsure where this can be done, please contact your host.

  Now, to install the POP3 gateway, you need to have an active POP3 account
  on your server that is designed to catch all mail that's sent to your domain
  name. You might not know this, but you probably have this kind of account
  already set up. If you do not have one, you should set one up using CPanel
  or any other control panel software that your host provided for your site.
  If you cannot find where to create the account, contact your host and ask
  for help.

  Once you have the account set up and running, log on to the HiveMail
  Administrator Control Panel using the administrator information you chose
  earlier. There, click Options from the main menu. Scroll down the page until
  you reach the POP3 Gateway group of settings. The first thing to do is
  enable the POP3 gateway by selecting Yes next to that setting - this must be
  enabled, or your mail will not be collected. Then, you need to set up the
  rest of the settings in that group:

  * Mail server: The server that holds this POP3 account. Usually, if your
    site is at www.example.com, the mail server would be mail.example.com.
	However, this is not always true. If you are not sure what the mail server
	is, contact your host and ask them.

  * Server port: The port that's used to connect to the mail server above,
    usually 110.

  * Username and Password: The username and password that is used to log on to
    the mail server and connect to the POP3 account. This may be the same as
	your FTP login information, but that's not for certain.

  * Use cron script: If you have set up the cron job (see above), you must set
    this to Yes. Only set this to No if you want the account to be checked
	when a user logs into the system.

  * Check every: The frequency for checking the POP3 account for messages, in
    minutes. If you set this to 0, the account will be checked whenever a user
	visits the system (we do not recommend this kind of setup). Note: This
	only applied if you are not using the cron job script. If you do use a
	cron job, this setting will have no effect whatsoever.

  * Leave messages on mailbox: If you set this to Yes all messages that are
    fetched from the POP3 account will not be deleted. Only enable this option
	if you really need it.

  After you enter the values for all of these settings, scroll down and submit
  the form to save the changes you've made.


5. INSTALLING THE PIPE GATEWAY
------------------------------

  To install the pipe gateway, you must have shell access to your server
  - telnet or SSH. If you don't have this type of access, you will not
  be able to install the gateway yourself (you might ask your host to do
  it for you, though), so installing the POP3 gateway is you
  alternative.

  First of all, you need to upload one script to your Web site. Before
  uploading the script, we need to make a couple of changes to it to
  make sure it fits your server. The file in question is
  hivemail_process.php, located in the /email folder you unpacked from
  the ZIP archive earlier. Open the file using a plain text editor (such
  as Notepad). The two things we need to alter are:

  * The path to PHP: After openning the file you will see this in the very
    first line:

      #!/usr/bin/php -q

    This is the path to the PHP binaries. On each server this path may be
    different, although it is usually either /usr/bin/php or
    /usr/local/php/bin/php. To find out the path on your server, contact
    your host or run the whereis php command from telnet or SSH. If the
    path on your server is, for example, /usr/local/php/bin/php, you need
    to change the line above to:

      #!/usr/local/php/bin/php -q

  * The path to HiveMail: About 20 lines below, you will see a large box
    with CONFIGURATION at the top. Please thoroughly read the instructions
    in that area, and update the $hivemail_path with the correct path to the
	folder HiveMail is installed in.

  After you are done editing the file, save it and close the editor.
  Now, upload hivemail_process.php to your server through FTP. It
  doesn't particularly matter where you upload this file, but we
  recommended that you place it outside your Web root (that is, above
  your document root, which is usually /htdocs, /public_html or /www).
  After uploading the file, change the mode of it (CHMOD) to 0755. In visual
  FTP clients this can usually be done by right-clicking on the file and
  choosing the appropriate option.

  And last but not least, we need to 'tell' the server to direct all
  mail to the script you just uploaded. To do so, we edit the valias
  file for your Web site. This file is usually located at
  /etc/valiases/example.com, but it might be different on your server.
  Ask your host if you are not sure there this file is. Once you know
  the file location, log in to telnet or SSH and type the following:

    pico /etc/valiases/example.com

  (replace the path with the real path). If you can't use pico, try
  using the vi text editor by typing:

    vi  /etc/valiases/example.com.

  In that file, you need to add a new line, that looks like this:

    *: |/home/example/hivemail_process.php

  Where /home/example/hivemail_process.php is the complete path to the
  hivemail_process.php file you uploaded earlier. If you are not sure
  where this file is located, type this command (outside of the file
  editor) to find where it is:

    find / -name hivemail_process.php -print 2>/dev/null

  For example, if your file is at
  /home/hivemail/etc/hivemail_process.php, this is the line you will add
  to your valias file:

    *: |/home/hivemail/etc/hivemail_process.php

  After you added the line, save the file and exit the file editor.


ENJOY HIVEMAIL!
---------------

  Congratulations! You now have a fully functional copy of HiveMail! Be
  sure to check out the comprehensive Administrator Control Panel
  HiveMail has to offer, and go through the various options to make sure
  it performs just like you want it to.

  Should you ever have any questions or need help, feel free to contact
  our support team at support@hivemail.com.


A. TELNET AND SSH
-----------------

  To log in to your server shell, you need to use a special client that
  is designed for telnet and SSH protocols.

  One option is to use the built-in client that comes with Windows.
  Click Start, and then in the Run dialog box type telnet. In the black
  window that opened, type open example.com 23, where example.com is the
  hostname of your Web site and 23 is the port. For regular telnet, 23
  is usually the port. However, when connecting to Secure Shell (SSH),
  the port is 22. You can type help in order to see a complete list of
  available commands.

  You may also want to use a more advanced and easier to use client.
  PuTTY or SecureCRT are good options, and you can find complete
  documentation for both of them at their Web sites.

  After openning a connection to your server, you will be asked to enter
  your username and password. These are usually the same as your FTP
  login information, however that's not definitive. If you can't log in
  using this information, you will need to contact your host and ask
  them for this information.

  Note: Some hosts disable access to telnet or SSH for their accounts.
  If this is the case for you, you will need to contact your host and
  ask them to help you with executing commands.


B. SMTP SERVER INFORMATION
--------------------------

  For your convenience, we have included a file called smtp_help.php in
  the /upload/install folder in the HiveMail ZIP archive. After uploading
  the HiveMail files to your Web server, you can visit this page in your
  browser and follow the instructions. The script will help you configure
  the SMTP server correcly.

  Please note that the file can only be used after you upload all files
  to your server. You can leave the SMTP settings part of config.php empty
  while installing the program, and come back to it later and use this
  script.