Installation Guide

This page guides you through the installation process of easyrec.

• Requirements
• Installation
  • Configuring MySQL
  • Creating the database
  • Deploying the Web Application
• Configuration
  • First startup/Initial configuration
  • Database connection setup
  • Database initialization
  • easyrec feature selection
  • User account creation
  • Ready to go

Requirements

To install easyrec you need the following prerequisites installed:

• Java 7 SE or later
• Application Server Tomcat 6.0 or later recommended or see Application Servers
• Database Server MySQL 5.1 or later (5.5 or later recommended)

Installation

easyrec comes with an interactive, web-based installer that is run automatically when you start easyrec for the first time. Before you can run easyrec, make sure your deployment environment meets the prerequisites outlined above (Tomcat6 , MySQL 5.1 or later and JAVA 7 SE or later). Once you have established an environment with Tomcat 6 running and a MySQL server reachable, acquire the latest easyrec_X_xx.war from the download section of the easyrec sourceforge project page https://sourceforge.net/projects/easyrec/files/.

Configuring MySQL

easyrec uses InnoDB as the default database storage engine. Unfortunately as configured out of the box InnoDB performs very poorly so we strongly advise you to properly configure MySQL according to our recommended settings:

We STRONGLY ENCOURAGE easyrec users to use the following settings for InnoDB. Internal tests have shown ~10x performance improvements of the easyrec backend compared to the defaults. You can change the configuration values by editing your my.ini(Windows) or my.cnf (Linux/Solaris) files in your MySQL root directory and restarting the database server afterwards.

• make sure to remove the skip-innodb entry
• innodb_flush_log_at_trx_commit=0
• innodb_buffer_pool_size=1024M
• innodb_log_file_size=250M
• innodb_log_buffer_size=16M
• (innodb_additional_mem_pool_size=8M) (only valid until MySql 5.1, omit on newer versions)

Note: When changing the innodb_log_file_size the MySQL server usually refuses to restart and complains about an incorrect log file size. To fix this problem move the old log files (usually named ib_logfile0 and ib_logfile1) from the root of your MySQL data folder to a backup folder of your choice so that the MySQL data folder does not contain any log files. Try starting the MySQL server again. It should now initialize the new log files with the proper size. Once you made sure everything is up and running you can delete the old log files from your backup folder.

Note 2: We suggest an innodb_buffer_pool_size of 1024MB above. Depending on your needs and environment you may specify a higher value. Official MySQL documentation suggests you can specify up to 1/4 to 1/3 of your total physical memory to the buffer pool

Note 3: MySQL 5.6 and newer comes with a feature called "Performance Schema" enabled by default which provides some additional logging and montioring of performance metrics. Disabling this feature will improve perfromance for easyrec some more.

This is a crucial step to ensure good performance of easyrec!

Creating the database

easyrec requires a MySQL database for operation. For help on installing a MySQL database server and creating database users please refer to the MySQL documentation at http://dev.mysql.com/doc/. Following we describe the procedure for creating a database using the MySQL console. However, you may also perform the required steps using the MySQL admin tool/client of your choice, e.g. PhpMyAdmin, SQLYog, HeidiSQL or similar as long as it provides the necessary user and database management options.

• Navigate to the MySQL folder and run the MySQL console using the following command:

{Path to MySQL}/bin/mysql -u root -p mysql

This starts up the MySQL console.

• Next, create a database and a user that has all privileges for that database:

create database easyrec;

• Create a user and grant all privileges to it for the database you just created.
  For environments where the MySQL server and the web server (i. e. Tomcat) are hosted on the same machine this is done by issuing the following command (Please replace 'easyrecuser' and 'password' with appropriate values of your choice) :

grant index, create, select, insert, update, drop, delete, alter, lock tables on easyrec.* to 'easyrecuser'@'localhost' identified by 'password';

If your MySQL server is NOT running on the same machine as your web server, you need to specify the hostname of the web server from which the database will be accessed (e.g. my.easyrec.org):

grant index, create, select, insert, update, drop, delete, alter, lock tables on easyrec.* to
'easyrecuser'@'my.easyrec.org' identified by 'password';

• Finally leave the MySQL console:

exit;

This is all the preparation needed for the database. easyrec will create the required tables during the easyrec install process automatically.

Deploying the Web Application

Once you completed the database setup, take the easyrec .war file you downloaded from sourceforge and deploy it on your web server. Using tomcat this can be done by either

• using the Tomcat manager application, which should be accessible on your web server running Tomcat at the URL http://{hostname}:{port}/manager/html where you replace {hostname} and {port} with the appropriate values for your machine (For further details please refer to the Tomcat documentation)

or

• by simply copying the file to the Tomcat webapps folder (located at {Path to Tomcat}/webapps) given that Tomcat is configuered for auto-deployment (which it is by default).

If you deployed the easyrec web application successfully, it is accessible using the URL http://{hostname}:{port}/easyrec-web.

Configuration

First startup/Initial configuration

Once all of the above steps are completed, you can continue with the installation and configuration of easyrec using a web browser.
When accessing the URL where easyrec was deployed e.g.http://myserver.com/easyrec-web for the first time after you deployed the web application, you will be guided through the final steps of the easyrec setup and configuration.

Database connection setup

As a first step you will be welcomed by a page that allows you to set up the database connection as pictured below.

Simply enter the details about your database connection and the username/password created in the previous section of this installation guide.

Field	Explanation
Database Host	The host the database is located on. If the database is located on the same host as the web server use "localhost".
Database Name	The name of the MySQL database you created.Note: If the MySQL server is configured to listen an a port other than the MySQL default port (3306), add the port to the hostname, separated by a colon (e.g. 'myserver:4711').
Username	The username used to access the easyrec database.Ensure that the user has SELECT, INSERT, UPDATE, DROP and DELETE permissions on the easyrec database. For security reasons it is strongly suggested that you do not use a database superuser account.
Password	The user password for accessing the easyrec database.

Once you have entered appropriate values in each field click the 'continue' button. easyrec will try to establish a connection to the database server using the information you provided in the form. If any problems should arise, an error message hinting at the cause of the problem will be displayed. If the connection attempt was successful you will progress to the next step.

Database initialization

The next page is just a short status update that a database connection could be established and the settings have been stored in the easyrec configuration. Since easyrec switched to the MySQL InnoDB database engine with version 0.95 you will see an alert message to remind you of properly configuring your MySQL database settings. This is a crucial step since unfortunately InnoDB as configured out of the box performs very poorly.

Once you have made sure that your MySQL configuration is correct, click away the alert message box and continue.

Hint: You can edit your database settings and restart MySQL right at this moment. There is no need to stop the easyrec installer. Just configure your database and when you are done return to the browser window and continue with easyrec setup.

Click the 'initialize database' button to continue.

In case you are redeploying the easyrec-web.war file and the database has already been created, you are presented with a slightly different screen:

You can either choose between 'initialize database' or 'use existing database'.
When using the second option, no tables will be created or altered and all existing data is kept in the database.

WARNING: Be aware that all easyrec tables will be deleted from the database specified in case you click on 'initialize database'

easyrec feature selection

If database initialization was successful you will be directed to the easyrec feature selection page.

Field	Explanation
Use REST	enable easyrec REST API. This is the default way to communicate with easyrec.
Developer Mode	This mode enables detailed debug output and enhanced monitoring at the cost of performance. Activate this option only on easyrec instances intended for development use. The use of this feature in production environments is strongly discouraged!

Developer mode just enables detailed log output about internal method calls and response values as well as more detailed performance profiling information. Unless you are a developer without direct debug access to the machine running easyrec you will want to leave this feature OFF.

By clicking the 'continue' button, easyrec will proceed to load and initialize all the services necessary for providing the selected features. This operation may take some time (usually several seconds up to 1 minute) to complete. If everything loaded according to plan you will be forwarded to the final step of the easyrec installation process.

User account creation

The final step before you can start using easyrec is to create user account, which is required to log in to the easyrec admin tool. The tool provides you with a basic overview about the easyrec status, allows you to perform some administrative operations. Most importantly it is the place to obtain your API key that needs to be passed along with every request to the easyrec API.

The user registration form should be self-explanatory. Simply provide a username and a password you want to use to log in to the easyrec admin tool. If you want you can supply some personal information as well. The personal information can be altered later on from within the admin tool. However, for the time being be aware that there is no easy way to change the username and password afterwards.

Ready to go

Congratulations! You have installed and configured easyrec successfully. You are now ready to start using easyrec and integrate it into your web applications.

The final screen informs you of the successful completion of the easyrec setup process. By clicking the 'management section' link you will be forwarded to the easyrec admin tool and logged in with the credentials provided in the previous step.