<commit_before>Suma Install Instructions
==========================

Requirements
-------------

These requirements as based on our local testing. Earlier versions may also work:

* MySQL recommended version 5.1
* Apache recommended version 2.2
* PHP recommended version 5.3.3 (although 5.2.3 may also work)
* Zend Framework 1.11 - required for Suma server
* Various Javascript Libraries - all included with Suma code

Additional Client Requirements:

* Device or computer with WebKit browser (e.g. iOS and Android browsers, Safari, Google Chrome) needed to use Suma client


Zend Framework Installation
-----------------------------

Download link: http://framework.zend.com/download/latest
 
Installation instructions url: http://framework.zend.com/manual/1.11/en/introduction.installation.html
 
Or do the following:

1. Expand download in chosen server location
2. Note path to framework library directory location
3. Modify your php.ini's include_path to add path to Zend framework library directory


Suma Software Installation
---------------------------

Download code: Either clone the repository or download a zip of the
code. GitHub provides instructions on the repository page.

https://github.com/cazzerson/suma

Note path to suma download directory.  We will refer to this as SUMA_DOWNLOAD_DIR

For Suma Client Installation:

Copy contents of `/SUMA_DOWNLOAD_DIR/web` to `/YOUR_WEB_DIR/suma`
If you need to copy it to a directory other than
'suma', just change the server URLs at the top of spaceassess.js

For Suma Server Installation:

* Copy contents of `/SUMA_DOWNLOAD_DIR/service` to a location outside your web directory. For example, if your web directory is `/var/www/htdocs` you could copy the contents of the `/SUMA_DOWNLOAD_DIR/service` to `/var/www/app/sumaserver`.

    Note this location, we will refer to it later as `SUMA_SERVER_INSTALL_DIR`

* Copy contents of `/SUMA_DOWNLOAD_DIR/service/web` to `/YOUR_WEB_DIR/sumaserver`

If you need to copy it to a directory other than
'sumaserver', you must change a line in `OUR_WEB_DIR/sumaserver/index.php` 

Change `'sumaserver'` the line `->setBaseUrl('/sumaserver')` to the name of the directory where you installed the Suma server index.php.


Apache Configuration
---------------------

You can configure your apache web server two ways using apache's configuration rewrite engine or using a .htaccess file

Apache rewrite
If using Apache's rewrite module add these lines in your web server (likely httpd.conf) configuration file 

    <Directory "/YOUR_WEB_DIR/sumaserver">  
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} -s [OR]
    RewriteCond %{REQUEST_FILENAME} -l [OR]
    RewriteCond %{REQUEST_FILENAME} -d
    RewriteRule ^.*$ - [NC,L]
    RewriteRule ^.*$ index.php [NC,L]
    </Directory>
                
Restart apache after adding these lines for configuration to apply

.htaccess
If using a .htaccess place the file in the `/YOUR_WEB_DIR/sumaserver` directory and add these lines
 
    RewriteEngine on
    RewriteCond %{REQUEST_FILENAME} -s [OR]
    RewriteCond %{REQUEST_FILENAME} -l [OR]
    RewriteCond %{REQUEST_FILENAME} -d
    RewriteRule ^.*$ - [NC,L]
    RewriteRule ^.*$ index.php [NC,L]
    
    
Database Setup
---------------

It is recommended you create two databases for Suma.  One for production and one for testing.  The database instructions are the same for both except for changing the database name.

Create database in MySQL using whatever tool you have available.
Create suma account with permissions to `SELECT`, `INSERT`, `CREATE`, `DELETE`, `UPDATE`, `INDEX`, and `ALTER` permissions.

Now you have to run a database initialization script included in the suma download. 

1. Find the file schema.sql in `/SUMA_DOWNLOAD_LOCATION/service/config`.
2. Run that script to initialize database, create suma tables, and establish foreign key constraints.
    
    To run it you can use the command line MySQL tools, phpmyadmin, or any other database management tool you like

*Optional* If you wish to initialize the database with preloaded sample data so you can play around with Suma more quickly, then run the schema_w_sample.sql script instead of schema.sql.


Suma Server Software Configuration
-----------------------------------

* index.php

    You must set some path variables in the index.php file for the suma server to function correctly.

    `SUMA_SERVER_PATH` muse be set to location `SUMA_SERVER_INSTALL_DIR` from earlier in these instructions.

    `SUMA_CONTROLLER_PATH` most be set to `SUMA_SERVER_INSTALL_DIR/controllers`.

* config.ini

    In the `SUMER_SERVER_INSTALL_DIR/config/config.ini` file you must modify the following:

        sumaserver.db.host      = host location of your mysql database
        sumaserver.db.dbname    = suma mysql database name
        sumaserver.db.user      = suma mysql account name
        sumaserver.db.pword     = suma mysql account password
        sumaserver.db.port      = mysql port number
        sumaserver.log.path = path to log directory.  You must make sure this directory is writable by Apache.

* Be sure that the log directory specified in sumaserver.log.path both exists and is writable. 
<commit_msg>Improvements to install docs, including analysis code configuration instructions<commit_after>Suma Install Instructions
==========================

Requirements
-------------

These requirements as based on our local testing. Earlier versions may also work:

* MySQL recommended version 5.1
* Apache recommended version 2.2
* PHP recommended version 5.3.3 (although 5.2.3 may also work)
* Zend Framework 1.11 - required for Suma server
* Various Javascript Libraries - all included with Suma code

Additional Client Requirements:

* Device or computer with WebKit browser (e.g. iOS and Android browsers, Safari, Google Chrome) needed to use Suma client


Zend Framework Installation
-----------------------------

Download link: http://framework.zend.com/download/latest
 
Installation instructions url: http://framework.zend.com/manual/1.11/en/introduction.installation.html
 
Or do the following:

1. Expand download in chosen server location
2. Note path to framework library directory location
3. Modify your php.ini's include_path to add path to Zend framework library directory


Suma Software Installation
---------------------------

Download code: Either clone the repository or download a zip of the
code. GitHub provides instructions on the repository page.

https://github.com/cazzerson/suma

Note path to suma download directory.  We will refer to this as SUMA_DOWNLOAD_DIR

For Suma Client Installation:

* Copy contents of `/SUMA_DOWNLOAD_DIR/web` to `/YOUR_WEB_DIR/suma/web`

* Copy contents of `/SUMA_DOWNLOAD_DIR/analysis` to `/YOUR_WEB_DIR/suma/analysis`


For Suma Server Installation:

* Copy contents of `/SUMA_DOWNLOAD_DIR/service` to a location outside your web directory. For example, if your web directory is `/var/www/htdocs` you could copy the contents of the `/SUMA_DOWNLOAD_DIR/service` to `/var/www/app/sumaserver`.

    Note this location, we will refer to it later as `SUMA_SERVER_INSTALL_DIR`

* Copy contents of `/SUMA_DOWNLOAD_DIR/service/web` to `/YOUR_WEB_DIR/sumaserver`

> If you need to copy it to a directory other than 'sumaserver', you must change a line in `YOUR_WEB_DIR/sumaserver/index.php` 
> Change `'sumaserver'` the line `->setBaseUrl('/sumaserver')` to the     name of the directory where you installed the Suma server index.php.
> Also, change the server URLs at the top of `YOUR_WEB_DIR/suma/web/spaceassess.js`


Apache Configuration
---------------------

You can configure your apache web server two ways using apache's configuration rewrite engine or using a .htaccess file

Apache rewrite
If using Apache's rewrite module add these lines in your web server (likely httpd.conf) configuration file 

    <Directory "/YOUR_WEB_DIR/sumaserver">  
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} -s [OR]
    RewriteCond %{REQUEST_FILENAME} -l [OR]
    RewriteCond %{REQUEST_FILENAME} -d
    RewriteRule ^.*$ - [NC,L]
    RewriteRule ^.*$ index.php [NC,L]
    </Directory>
                
Restart apache after adding these lines for configuration to apply

.htaccess
If using a .htaccess place the file in the `/YOUR_WEB_DIR/sumaserver` directory and add these lines
 
    RewriteEngine on
    RewriteCond %{REQUEST_FILENAME} -s [OR]
    RewriteCond %{REQUEST_FILENAME} -l [OR]
    RewriteCond %{REQUEST_FILENAME} -d
    RewriteRule ^.*$ - [NC,L]
    RewriteRule ^.*$ index.php [NC,L]
    
    
Database Setup
---------------

It is recommended you create two databases for Suma.  One for production and one for testing.  The database instructions are the same for both except for changing the database name.

Create database in MySQL using whatever tool you have available.
Create suma account with permissions to `SELECT`, `INSERT`, `CREATE`, `DELETE`, `UPDATE`, `INDEX`, and `ALTER` permissions.

Now you have to run a database initialization script included in the suma download. 

1. Find the file schema.sql in `/SUMA_DOWNLOAD_LOCATION/service/config`.
2. Run that script to initialize database, create suma tables, and establish foreign key constraints.
    
    To run it you can use the command line MySQL tools, phpmyadmin, or any other database management tool you like

*Optional* If you wish to initialize the database with preloaded sample data so you can play around with Suma more quickly, then run the schema_w_sample.sql script instead of schema.sql.


Suma Server Software Configuration
-----------------------------------

* index.php

    You must set some path variables in the index.php file for the suma server to function correctly.

    `SUMA_SERVER_PATH` muse be set to location `SUMA_SERVER_INSTALL_DIR` from earlier in these instructions.

    `SUMA_CONTROLLER_PATH` most be set to `SUMA_SERVER_INSTALL_DIR/controllers`.

* config.ini

    In the `SUMA_SERVER_INSTALL_DIR/config/config.ini` file you must modify the following:

        sumaserver.db.host      = host location of your mysql database
        sumaserver.db.dbname    = suma mysql database name
        sumaserver.db.user      = suma mysql account name
        sumaserver.db.pword     = suma mysql account password
        sumaserver.db.port      = mysql port number
        sumaserver.log.path = path to log directory.  You must make sure this directory is writable by Apache.

* Be sure that the log directory specified in sumaserver.log.path both exists and is writable. 

Suma Analysis Tools Configuration
----------------------------------

* In `YOUR_WEB_DIR/suma/analysis/lib/Server_IO.php` change `<host>` to your hostname (e.g. lib.abc.edu).
* You can view the Suma analysis tools by visting `http://YOUR_SERVER/suma/analysis/reports`.

{'fraction_non_alphanumeric': 0.09707298999629492, 'fraction_numerical': 0.003890329751759911, 'mean_word_length': 3.421375921375921, 'pattern_counts': {'":': 0, '<': 8, '<?xml version=': 0, '>': 13, 'https://': 2, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 14, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4953081', 'n_tokens_mistral': 3139, 'n_tokens_neox': 2919, 'n_words': 1265}