Installation Guide

From Easyrec Wiki
Jump to: navigation, search

This page guides you through the installation process of easyrec.



To install easyrec you need the following prerequisites installed:

  • Java 5 SE [1] or later
  • Application Server Tomcat 6.0 [2] or later recommended or see other Application Servers
  • Database Server MySQL 5.1 [3] or later (5.1.33 or later recommended)


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 5 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 [4].

Configuring MySQL

Since version 0.95 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 InnoDB settings.

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 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.

grant index, create, select, insert, update, drop, delete, alter, lock tables on easyrec.* to
'easyrecuser'@'' identified by 'password';
  • Finally leave the MySQL console:

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)


  • 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.


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. 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.

Easyrec installer page1 095.PNG

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.

Easyrec installer page2 create innodDBalert 095.PNG

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.

Easyrec installer page2 create 095.PNG

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:

Easyrec installer page2 095.PNG

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.

Easyrec installer page3 095.PNG

Field Explanation
Use REST enable easyrec REST API. This is the default way to communicate with easyrec.
Use SOAP enable easyrec SOAP API if you want to access the easyrec API using the SOAP protocol.
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!

The default way to communicate with easyrec is a REST-like API. If this is not a viable option for your usage scenario you can also choose to integrate easyrec into your application environment using the SOAP protocol. Parallel operation of both interface technologies at the same time is possible.

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.

Easyrec installer page4 095.PNG

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.

Easyrec installer page5 095.PNG

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.

Personal tools

easyrec documentation