DESCRIPTION
-----------
This document explain about how to install and setup playSMS


REQUIREMENT
-----------
Minimum Required Hardware
- Web server capable hardware

Minimum Required Software
- Operating System Linux (install on MS Windows or BSD is also possible)
- Web Server (for example Apache2 or lighttpd)
- Database Server MySQL 5.x.x or latest stable release
- PHP 5.x.x or latest stable release with mysql module enabled and CLI version
- PHP gettext extension (this is a must for text translation)
- PHP multibyte string function (should be able to call mb_convert_encoding)
- Access to SMTP server (playSMS will use this to send email)
- lynx, wget or curl, a console web browser (example scripts require lynx)
- Downloaded playSMS package from SF.net or latest source code from Github
- Selected gateway application. Recommended to use Kannel or SMS Server Tools

Minimum Required Server Administrator (or Developer)
- Understand howto make sure installed PHP has MySQL module enabled/loaded
- Understand howto create/drop MySQL database
- Understand howto insert SQL statements into created database
- Basic knowledges to manage Linux (skill to navigate in console mode)


INSTALLATION
------------
There are 2 methods available to install playSMS:
1. Using install-script
2. Step-by-step

If you are using Ubuntu server, relatively new and not much core changes, then
I suggest you to use 1st method, using install-script.


INSTALLATION on Linux using install-script
------------------------------------------
playSMS Web Interface using install script:

1.  Extract playSMS package somewhere (Usually in /usr/local/src).

    # tar -zxf playsms-x.x.x.tar.gz -C /usr/local/src

    Note: x.x.x may vary according to the package name you've download.
          For example playsms-0.9.9.2.tar.gz

2.  Edit install.conf, read it, understand it and make changes to suit your
    system configuration

    # cd /usr/local/src/playsms-x.x.x/contrib/installer

    # vi install.conf

3.  Run installer script. Be warned that the script have been tested only on 
    Ubuntu server or desktop.

    # cd /usr/local/src/playsms-x.x.x/contrib/installer

    # ./install-playsms-ubuntu.sh

    Note:
    - you must read and verify the install data presented when running
      script install-playsms-ubuntu.sh, and continue only when the data
      is correct
    - edit install.conf again if you think your install data is wrong
    - after successful installation, please run command "ps ax" and see
      if playsmsd, sendsmsd, recvsmsd and dlrssmsd are running

      # ps ax | grep playsms
      3165 ? S 0:02 /bin/bash /usr/local/bin/_playsms/playsmsd /var/www/playsms
      3181 ? S 0:02 /bin/bash /usr/local/bin/_playsms/recvsmsd /var/www/playsms
      3200 ? S 0:01 /bin/bash /usr/local/bin/_playsms/sendsmsd /var/www/playsms
      3217 ? S 0:02 /bin/bash /usr/local/bin/_playsms/dlrssmsd /var/www/playsms

    - stop here and review your installation steps when above daemon scripts
      aren't running
    - consider to ask question in playSMS mailing list or facebook group when
      you encountered any problem
    - if all seems to be correctly installed you may try to login from web

      browse http://<your web server IP>/playsms/ and login using default
      administrator user

      username: admin
      password: admin


INSTALLATION on Linux step by step
----------------------------------
playSMS Web Interface step-by-step installation:

1.  Extract playSMS package somewhere (Usually in /usr/local/src).

    # tar -zxf playsms-x.x.x.tar.gz -C /usr/local/src

    Note: x.x.x may vary according to the package name you've download.
          For example playsms-0.9.9.2.tar.gz

2.  Create playSMS web root, spool and log and set ownership to user www-data or
    web server user

    # mkdir -p /var/www/playsms /var/spool/playsms /var/log/playsms \
      /var/lib/playsms

    # chown -R www-data /var/www/playsms /var/spool/playsms /var/log/playsms \
      /var/lib/playsms

    Note: There are Linux distributions using 'apache' as web server user
          instead of 'www-data'.

3.  Copy files and directories inside 'web' directory to playSMS web root and
    set ownership again to user www-data or web server user, just to make sure

    # cp -rR /usr/local/src/playsms-x.x.x/web/* /var/www/playsms

    # chown -R www-data /var/www/playsms

4.  Setup database (import database)

    # mysqladmin -u root -p create playsms

    # mysql -u root -p playsms < /usr/local/src/playsms-x.x.x/db/playsms.sql

    Note: You don't need to use MySQL root access nor this method to setup
          playSMS database, but this is beyond our scope. You should read MySQL
          manual for custom installation method or howto insert SQL statements
          into existing database.

5.  Copy config-dist.php to config.php and then edit config.php

    # cp /var/www/playsms/config-dist.php /var/www/playsms/config.php

    # vi /var/www/playsms/config.php

    Note: Please read and fill all fields with correct values

6.  Enter daemon/linux directory, copy files and folder inside

    # mkdir -p /etc/default /usr/local/bin

    # cp /usr/local/src/playsms-x.x.x/daemon/linux/etc/playsms /etc/default/

    # cp -rR /usr/local/src/playsms-x.x.x/daemon/linux/bin/* /usr/local/bin/

7.  Just to make sure every paths are correct, please edit /etc/default/playsms

    # vi /etc/default/playsms

    Note: Make sure that PLAYSMS_PATH is pointing to a correct playSMS
          installation path (in this example to /var/www/playsms), and also make
          sure that PLAYSMS_BIN is pointing to a correct playSMS daemon scripts
          path (in this example to /usr/local/bin)

8.  There are two choices to get playSMS daemon starts automatically on boot.
    You need to choose one:

    A. Using init script. When you are installing playSMS on Debian based distro
       (like Ubuntu), you may use contributed init script. Copy the init script
       to /etc/init.d/ and program it to start at boot

       # cp /usr/local/src/playsms-x.x.x/daemon/linux/etc/playsms.init-ubuntu \
         /etc/init.d/playsms

       # update-rc.d playsms defaults

    B. Using rc.local. Look for rc.local on /etc, /etc/init.d, /etc/rc.d/init.d
       When you found it edit that rc.local and put:

       "/usr/local/bin/playsmsd_start" (without quotes, remove quotes)

       on the bottom of the file (before exit if theres an exit command).
       This way playsmsd_start will start automatically on boot.

    Note: Just like any other steps before, you need 'root' access to do this.

9. Start playsmsd manually, no need to reboot your OS

    A. If you are using the init script:

       # /etc/init.d/playsms start

    B. If you are using rc.local:

       # /usr/local/bin/playsmsd_start

    Note:
    - after successful installation, please run command "ps ax" and see 
      if playsmsd and sendsmsd are running

      # ps ax | grep playsms
      3165 ? S 0:02 /bin/bash /usr/local/bin/_playsms/playsmsd /var/www/playsms
      3181 ? S 0:02 /bin/bash /usr/local/bin/_playsms/recvsmsd /var/www/playsms
      3200 ? S 0:01 /bin/bash /usr/local/bin/_playsms/sendsmsd /var/www/playsms
      3217 ? S 0:02 /bin/bash /usr/local/bin/_playsms/dlrssmsd /var/www/playsms

    - stop here and review your installation steps when above daemon scripts
      aren't running
    - consider to ask question in playSMS mailing list or facebook group when
      you encountered any problem
    - if all seems to be correctly installed you may try to login from web

      browse http://<your web server IP>/playsms/ and login using default
      administrator user

      username: admin
      password: admin


If you have GSM modem and plan to use it with playSMS, please continue to follow
instructions in INSTALL_SMSSERVERTOOLS to use SMS Server Tools (smstools3) as
your gateway module, or follow INSTALL_KANNEL if you want to use Kannel.

Gnokii and Gammu also supported, please follow INSTALL_GNOKII if you want to use
Gnokii as your gateway module, or INSTALL_GAMMU if you want to use Gammu.

