INSTALL.txt

INSTALL

1. Installing Prerequisites:
    a. Linux with apt-get
    b. Windows
    c. Other Platforms
2. Installing Envaya in a development environment
3. Pushing your changes to github
4. Installing and updating Envaya on production servers

==================================================
1a. Installing prerequisites on Linux with apt-get
==================================================

The Linux setup scripts are tested on Debian 8, but may work on 
other Linux distributions with apt-get.

The steps below assume that you are installing Envaya in a development 
environment. (For production server installation, see the section 
"Deploying releases to a production server")

1.  Copy Envaya's source code into a world-readable directory. 
    If you don't already have the source code on your computer, you can do:
    
        apt-get -y install git-core 
        git clone --recursive git://github.com/youngj/Envaya.git ./envaya
        cd envaya

    Note: The following commands should be run from a command prompt in 
    the root directory of the Envaya source code.    
    They also assume you are running as 'root'.

2.  Configure your APT sources
    Warning: this will modify your /etc/apt/sources.list file.
        
        ./scripts/setup/sources.sh

3. Install basic prerequisites (php, php extensions, wget, rsync, etc.)

        ./scripts/setup/prereqs.sh
        ./scripts/setup/php.sh

4.  If you don't already have mysql installed, install it.
    Warning: if mysql is already installed, this script will reset
    the mysql root password to the empty string (should fix this...)

        ./scripts/setup/mysql.sh

5. Install sphinx (full text search)

        ./scripts/setup/sphinx.sh

6. Install rabbitmq (task queue)

        ./scripts/setup/rabbitmq.sh
        
7. Install dependencies for selenium tests and other development tools:

        ./scripts/setup/dev.sh
8. (optional) Install some extra programs.
    This may take a long time, and most Envaya services will work without this.

        ./scripts/setup/extras.sh
 
Also, if your server doesn't already have a browser and/or GUI, you can
install one like so:

        apt-get install x-window-system-core gnome-core gdm firefox

Then, reboot into the GUI.
 
=======================================
1b. Installing prerequisites on Windows
=======================================

1.  Install wampserver: 
        http://www.wampserver.com/en/ 
    These directions assume WAMP is installed to c:\wamp.

2.  Install Java JDK 6: 
        http://www.oracle.com/technetwork/java/javase/downloads/index.html

3.  Install cygwin: 
        http://cygwin.com/install.html 
    These directions assume cygwin is installed to c:\cygwin.    
    Select the following 'bin' packages to install: 
        rsync, openssh, mcrypt, git

5.  Modify Path Environment variable. Right-click on "Computer" or "My Computer", 
    then "Properties", then "Advanced System Settings" or "Advanced", then 
    "Environment Variables", then find the "Path" variable and click "Edit". 
    At the end, add:

        ;c:\cygwin\bin;C:\wamp\bin\php\php5.3.0;C:\wamp\bin\mysql\mysql5.1.36\bin        

6. Download Envaya code, e.g.:

        cd c:\wamp\www\
        git clone --recursive git://github.com/youngj/Envaya.git envaya
        cd envaya

7. Install PHP memcache library.
    Download it from:
        http://downloads.php.net/pierre/php_memcache-cvs-20090703-5.3-VC6-x86.zip
    Then extract the zip file and copy the dll to your PHP extension directory:
        C:\wamp\bin\php\php5.3.0\ext\

8.  Add PHP extensions to your php.ini file. 
    Edit C:\wamp\bin\php\php5.3.0\php.ini, and search for "extension=". Uncomment
    or add the following lines:
    
        extension=php_memcache.dll
        extension=php_curl.dll
        extension=php_gd2.dll
        extension=php_mbstring.dll
        extension=php_pdo_mysql.dll

    Also, add this to the bottom of your php.ini file:
    
        variables_order="GPCSE"

9.  Install dependencies for selenium tests. 
    From the PEAR directory C:\wamp\bin\php\php5.3.0\PEAR , 
    run the following commands:
    
        php -d phar.require_hash=0 go-pear.phar
        pear upgrade pear
        pear channel-discover pear.phpunit.de
        pear channel-discover components.ez.no
        pear channel-discover pear.symfony-project.com
        pear install phpunit/PHPUnit

10. Download and install Sphinx 1.10.
        http://sphinxsearch.com/files/sphinx-1.10-beta-win32.zip
    Extract the zip file to c:/sphinx
    
===============================================
1c. Installing Prerequisites on Other Platforms
===============================================

Envaya can also be set up manually on other platforms.

Envaya requires the following prerequisites:

PHP 5.3 or higher, with php-cgi and php-cli
PHP extensions:
    curl
    gd
    json
    mbstring
    mcrypt
    memcache    
    PDO
    pdo_mysql
Mysql
Sphinx 2.04
Rabbitmq

Envaya does not require a separate web server for development, since it 
comes with its own PHP development web server, but you can use Apache or Nginx
instead if you like.

To use Apache (with mod_php) as the web server, set DocumentRoot to the full
path to the www/ directory inside this source tree (e.g. C:/path/to/envaya/www),
and make sure that mod_rewrite is enabled.

To use Nginx (with php-fastcgi) as the webserver, see what scripts/setup/nginx.sh
does, and do something like that.

====================
2. Installing Envaya
====================

After you have installed the prerequisites above, run the following
commands in a command prompt in the root directory of Envaya's source code.
   
1.  Create your local configuration file (config/local.php):

        php scripts/install_settings.php

2.  Edit config/local.php in a text editor to provide settings for
    your development environment.
     * set admin_email to your own email address
     * set your desired database settings
     * override any other settings from config/default.php as necessary
     
    If you are using Windows, you will also need to add the following settings
    (assuming Sphinx was installed in C:/sphinx):

        'sphinx_conf_dir' => 'C:/sphinx',
        'sphinx_bin_dir' => 'C:/sphinx/bin',
        'sphinx_log_dir' => 'C:/sphinx/log',
        'sphinx_pid_dir' => 'C:/sphinx/log',
     
3.  Create empty database and default user:

        php scripts/db_setup.php | mysql -u root -p

4.  Install database tables and create directory for storing data on filesystem

        php scripts/install_tables.php
        php scripts/install_dataroot.php

5. Create sphinx config file and initial index, and rabbitmq users

        php scripts/install_sphinx.php
        php scripts/install_rabbitmq.php

6.  Create initial users for testing (should not be used in production)    

        php scripts/install_test_data.php

    This will create several user accounts, including:
        (administrator) username:testadmin pw:testtest
        username:testorg pw:testtest
        username:envaya pw:testtest

7.  Make compressed CSS and JS files, etc.:

        php make.php

8. Start envaya server processes

        php runserver.php

    Leave runserver.php running in a command prompt. It should print 
    the URL of Envaya's home page. Open this URL in a browser. 
    
9. Install latest version of selenium server (for running tests)
    
        php scripts/install_selenium.php
    
=================================
3. Pushing your changes to github
=================================

Suppose you made a change to Envaya's source code on your local computer 
and want to make your changes part of Envaya's official codebase.
To do this, you will first need to push your changes to your own repository
on github, and then submit a pull request on github. 

The following steps explain how to do this for the first time:

1. Create a github account if you don't already have one: 
     https://github.com/signup/free
         
2. Create a ssh keypair for your computer by running 'ssh-keygen' 
    in a command prompt, and following the instructions.
    When it's done, ssh-keygen should print out something like this:
        "Your public key has been saved in /path/to/id_rsa.pub."
        
3. Copy your ssh public key to your github account settings page.
    To do this, open https://github.com/account/ssh , and click the link to 
    add a public key. Open the public key file generated in the previous 
    step in a text editor (e.g. "(notepad|gedit) /path/to/id_rsa.pub"),
    copy the entire file to the clipboard, and paste the key into 
    the "Key" textarea. The "Title" field can be anything.

4. Fork the official Envaya repository.
    While logged in to github, go to https://github.com/youngj/Envaya 
    and click the 'Fork' button. It should create a page like:
        https://github.com/<your_username>/Envaya 
    
5. Add your new repository as a git remote.
    On your new github repository page, there should be a button 
    labeled "SSH" next to a text box like:
        git@github.com:<your_username>/Envaya.git
    Copy that to the clipboard, then in a command prompt in your local 
    Envaya source code directory, run the following command:
        git remote add public <pasted_url_from_clipboard>

6. Set your name and email address for git:
    git config --global user.name "Firstname Lastname"
    git config --global user.email "your_email@youremail.com"
        
7. Whenever you want to push your changes to your github repository
    (after committing them locally with "git commit"), run the 
    following command:
        git push public master

8. Whenever you want your changes to be included in the official 
    Envaya repository, go to https://github.com/<username>/Envaya ,
    click the "Pull Request" button, and follow the instructions.
        
=======================================================
4. Installing and updating Envaya on production servers
=======================================================

This section explains how to deploy Envaya on a public web server like
http://envaya.org . Ignore this section if you are only setting up Envaya 
in a development environment, not on a production server.

1.  Install Envaya's source code on your local computer as described above.
    
2.  Install the following additional prerequisites:
        - Ruby
                http://www.ruby-lang.org/en/downloads/
        - Capistrano:
                gem install capistrano

3.  Create a file on your local computer config/production.php with the
    local configuration settings for the production server.    
    (In the next step, this file will be copied to /var/envaya/shared/local.php 
    on the production server.)
                
4.  Initially, to install all prerequisites and latest Envaya code, but no
    particular services, on a server running Debian 8:

        cap [HOSTS=<hostname>] deploy:basic_setup
        
    Subsequently, run other deploy:*_setup methods to install particular
    services on that host.
    
    == OR ==

    To install all prerequisites, latest Envaya code, 
    and all Envaya services on a single server running Debian 8:

        cap [HOSTS=<hostname>] deploy:full_setup

5.  Subsequently, to update a server to the latest code:

        cap [HOSTS=<hostname>] deploy