INSTALL

   OPENEXAM PHP - INSTALL INSTRUCTIONS


** REQUIREMENTS:

   These are the requirements. Tested versions within brackets, but other
   versions might work just OK.
   
        *) PHP >= 5.6.x || 7.x [5.6.33, 7.0.27]
        *) An SQL database (RDBS) supported by PDO. [MySQL 5.6.38]
        *) Apache web server [2.4.27]
        *) Composer 1.2.xxx [2016-09-12]
	 
   PECL Extensions (including those builtin in PHP):
	    
        *) phalcon.so  - Core MVC functionality, use the 3.x branch (required).
        *) fileinfo.so - For detection of MIME type for uploaded files (required).

        *) gettext.so  - GNU gettext  (i.e. ngettext(), _(), ...) (recommended).
        *) zip.so      - For bundling results for download (recommended).

        *) http.so     - HTTP extension (content type of media URL's) (optional).
        *) curl.so     - For downloading UPPDOK data (optional).
        *) pcntl.so    - Signal handling in render worker (optional).
        *) soap.so     - Service intergration with external systems (optional).

   The script admin/compat/check.sh will check the code and display a list of all 
   required extensions.

   It's highly recommended to enable database, model and catalog information cache
   using a combination of:

        *) xcache.so   - System local cache when using PHP 5.6 (recommended).
        *) apcu.so     - System local cache when using PHP 5.6/7.x (recommended).
        *) redis.so    - Distributed database query cache (recommended).

   If getting errors about the apc_fetch() function is missing when using PHP 7.x, 
   try to install the APCu backwards compatibility module. Make sure to load this 
   extension after apcu. Downloaded source code from https://pecl.php.net/apcu_bc 
   if required.

   Useful links for downloading required software:

        https://www.mathjax.org/
        https://phalconphp.com/en/

** CONFIGURATION:

   Turn off magic quotes in php.ini:
   
        magic_quotes_gpc = Off
        magic_quotes_runtime = Off
   
   It's no longer recommended to enable magic quotes. This feature defaults 
   to off in PHP 5.3.x and is scheduled for removal in PHP 6.
   
** INSTALL:

   To keep instructions compact, lets define some SHELL variables to use:

        appdir=/var/www/localhost/apps/     # Web application directory not direct accessible.
        webdir=/var/www/localhost/htdocs    # The web server document root.
        bindir=/usr/local/bin               # System local binaries in PATH.

   1. Install Composer:

      Package dependencies are handled by Composer: https://getcomposer.org/. Follow these 
      instructions for installing Composer globally:

            bash$> curl -sS https://getcomposer.org/installer | \
                        php -- --install-dir=${bindir} --filename=composer

   2. Install Phalcon MVC:

      This is a required extension PHP extension. Without it the MVC layer of OpenExam
      wont work.

            bash$> wget https://github.com/phalcon/cphalcon/archive/master.zip
            bash$> unzip master.zip
            bash$> cd cphalcon-master

      Read thru the README.md and install any dependencies. Continue by configure,
      build and install cp

            bash$> phpize && aclocal && libtoolize --force && autoheader && autoconf
            bash$> ./configure --enable-phalcon
            bash$> make
            bash$> make install

      Add phalcon.so to PHP extensions (system dependent). Verify that the Phalcon
      extension is enabled:

            bash$> php -m | grep phalcon
      
   3. Install OpenExam:

      o) From source code:

            bash$> tar xfvzp openexam-online.tar.gz -C ${appdir}

      o) From SVN:

            bash$> svn co svn://svn.bmc.uu.se/cbe/openexam-online/trunk ${appdir}/openexam-online

      o) From GIT:

            bash$> svn clone git@github.com:openexam/openexam-online.git ${appdir}/openexam-online

      Create a symbolic link to the applications public directory under the web root:

            bash$> ln -s ${appdir}/openexam-online/phalcon-mvc/public ${webdir}/openexam

      Install application dependencies (creates the vendor directory):

            bash$> cd ${appdir}/openexam-online
            bash$> composer install --no-dev

   4. Configure OpenExam:

      Make config protected versions from the template configuration files (*.def.in):
	       
            bash$> cd ${appdir}/openexam-online/phalcon-mvc/app/config
            bash$> for f in *.in; do cp -i $f ${f%%.in}; done

      Edit the configuration files (*.def) using your favorite editor.

   5. Create database:

      Create the database openexam. The database connection must be granted SELECT, INSERT,
      UPDATE and DELETE privileges. If using phalcon.php (phalcon/devtools), then the connection
      must be granted CREATE, ALTER and DROP table privileges.

      Insert the connection parameter in ${appdir}/openexam-online/phalcon-mvc/app/config/config.def. 
      
      Repeat the database creation procedure on any SQL-server that is going to be used for load 
      balancing. For a simple setup without load balancing, the same same SQL-server (typical 
      running on localhost) is going to be used both for dbread and dbwrite.

      o) Create database using SQL-script (MySQL only):

            bash$> mysql -u root -p
            Enter password:
              ...
            mysql> CREATE DATABASE openexam;
            mysql> GRANT SELECT,INSERT,UPDATE,DELETE ON openexam.* TO openexam@localhost IDENTIFIED BY 'password';
            mysql> FLUSH PRIVILEGES;
            mysql> USE openexam;
            mysql> SOURCE ${appdir}/openexam-online/admin/sql/openexam.sql
            mysql> INSERT INTO admins(user) VALUES('username');   # Add system administrator
            mysql> EXIT

      o) Create database using Phalcon Developer Tools (phalcon/devtools):

         This procedure is recommended for RDBS other than MySQL (e.g. PostgreSQL). Use the
         RDBS tools to create an empty database. Continue by creating the tables:

            bash$> cd ${appdir}/openexam-online/phalcon-mvc
            bash$> ../vendor/bin/phalcon.php migration run --migrations=schemas/migrations

   6. Language support:

      To get laguage support (translation) working, you have to compile the *.po files for your 
      platform. This is done by running make in the package root directory:

            bash$> cd ${appdir}/openexam-online
            bash$> make

      This should compile all *.po to *.mo that can be read by PHP's GNU gettext extension. If 
      the gettext extension is missing, then application defaults to english text.

   7. Javascript plugins:

      Install required javascript plugins by running:

        o) cd ${appdir}/openexam-online/phalcon-mvc/public/plugins && ./mathjax.sh
	    
   8. Finishing:

      The user defined setting files (*.def) should not be readable by world, only by trusted 
      users and the account the web server is running under (see admin/setperm.sh):

            bash$> cd ${appdir}/openexam-online/phalcon-mvc/app/config
            bash$> chmod 600 *.def
            bash$> setfacl -m u:apache:r *.def

      You are now ready to restart the web server at try it out.


// Anders Lövgren, 2010-05-07