eusurvey oss installation guide - joinup · eusurvey oss installation guide 2 this document...

EUSurvey OSS Installation Guide

1

Prerequisites ................................................................................................................................................. 2

Tools .......................................................................................................................................................... 2

Java 7 SDK ............................................................................................................................................. 2

MySQL 5.6 DB and Client (Workbench) ................................................................................................ 4

Tomcat 7 ............................................................................................................................................... 8

Spring Tool Suite ................................................................................................................................. 11

Knowledge .............................................................................................................................................. 12

Control System Services ...................................................................................................................... 12

Prepare the Database ................................................................................................................................. 14

Create a new schema .............................................................................................................................. 14

Create a new DB user .............................................................................................................................. 15

Enable Event-Scheduler .......................................................................................................................... 19

Build the application ................................................................................................................................... 21

Get the sources ....................................................................................................................................... 21

Load the code into your IDE .................................................................................................................... 21

Configure the application ....................................................................................................................... 26

Export the WAR archive .......................................................................................................................... 27

Deploy the application ................................................................................................................................ 29

First Steps .................................................................................................................................................... 31


2

This document describes the steps that are necessary to compile and install the open source version of

EUSurvey on a Microsoft Windows system.

The EUSurvey system is a Java web-application that was built using the Spring MVC framework and runs

on a Java servlet container. Enforcing open source software, the system’s development and reference

installation is running Apache Tomcat and uses a MySQL database to store its information. The build

process is assisted by Maven for resolving external dependencies.

All tools used in this tutorial are available free of charge on the corresponding web sites.

Please notice that the different steps to create a working development environment for EUSurvey is

possible using a different set of tools as well. The aim of this document however is to provide a standard

method to create a working EUSurvey environment for developing and running an instance of EUSurvey,

with as less effort as possible.

The experienced user should feel free to use a compatible set of tools of its choice.

Prerequisites

Tools The following tools and binaries need to be installed on the system to create and run the application:

Java 7 SDK

Java is the language, the system was written in. To run an application in JAVA, regardless what

application it is, the JAVA runtime environment must be installed on your system. Given that we will

create an application from source-code, the Java Development Kit (JDK) is required to be installed on

your system.

Download and install the latest JDK 7 version for your system (jdk-7u67) from the Oracle web site:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

Be careful when installing the version of the JDK indeed Spring Tool Suite is now coming in one package

(32-bit and 64-bit) and if you install the wrong version of the jdk (x86 or x64) you could not start sts.exe

(see the adequate section below)

Hint

If you have to install the jdk, follow the steps by the installer. Once installed please follow these

configuration steps

Add the JAVA_HOME

To allow execute any java command everywhere you have to add to the system variables of your

environment variable the JAVA_HOME entry that point to the root directory of your JDK installation.

http://www.oracle.com/technetwork/java/javase/downloads/index.html


3

Adapt the Path

On the system variables of your environment variable edit the entry Path and add the bin directory of

your jdk installation eg c:\jddk\bin

Test is successful

Open a Command Prompt dialog (cmd) via the startup menu and type this command java –version you

should receive an answer as


4

MySQL 5.6 DB and Client (Workbench)

Download and install the latest MySQL Community Server 5.6.X from the MySQL web site:

http://dev.mysql.com/downloads/mysql/

Hint

Please notice that the installation of this package might require the .NET framework 4.0 to be installed

on your computer. If this is not the case, the installation process will halt showing you the message

below. Please browse to the indicated URL to download and install your copy of the Microsoft .NET

Framework 4.5 binaries before proceeding.

Choose the Windows (x86, 64 bit), MySql Installer MSI that will you help to get the right product

http://dev.mysql.com/downloads/mysql/


5

On the download please select the mysql-installer-community-5.6.20 and not the web installer

Choose the setup type that suits your needs. In most of the cases the “Custom” type is the right one.

Please unselect “MySQL for Visual Studio” in the “Applications” sub-menu, if Microsoft Visual Studio is

not installed on your computer.

Please make sure that “MySQL Workbench CE” is selected from the “Applications” to be able to

manually create a custom database schema for EUSurvey later in the installation process. This will

require MS Visual C++ runtime libraries to be installed that will be installed automatically by the installer

during the installation process.


6

Please select “Development Machine” on the configuration tab wizard and make sure that “Networking”

is enabled.


7

On the second page of the installation wizard, please set the password of the MySQL root account. The

default password for the user “root” is “root”.


8

Tomcat 7

As a Java web application, EUSurvey requires an application server (more precisely, a Servlet Container )

to host the application. Following the premise to use open-source software, we will use the Tomcat

web-container from the Apache project to deploy our application to.

Please download and install the latest Apache Tomcat 7 version from the Apache web site located at:

http://tomcat.apache.org/

Please make sure you download executable binaries (.exe) also called 32-bit/64bit Window Service

Installer in the download page who will guide you through the installation process.

In the Choose component tab wizard,if you select the custom type of install, do not forget to select the

service Startup option below the Tomcat node

http://tomcat.apache.org/


9

During the installation process, please specify the folder you have installed your JRE7 to, as done in the

previous step.


10

After successful installation, we will now start the respective service and will check if the application

server is working correctly. This step is optional at this point if you do not plan to deploy the application

right away.

To do so, we first need to start the system service that is not started automatically after installation.

Therefore, we open the view on system services and START the respective service labelled “Apache

Tomcat 7.0 Tomcat 7” from your system’s view on Services.

Please read the Knowledge section if you are unsure on how to do this.


11

Once you have started Tomcat successfully, please go to the following page to see that the application

server is working:

http://localhost:8080/

On success, your browser should show the following (or similar) page:

Spring Tool Suite

The developers of the framework EUSurvey was built upon (Spring MVC) provide an IDE that has been

customized to be especially helpful for developing web application based on the Spring framework. The

Spring Tool Suite is based on the well-known Java IDE “Eclipse” and already provides different tools and

libraries the framework and the build-process rely on.

Download and install the latest Spring Tool Suite version from the Spring web site:

http://spring.io/tools

Please follow these steps to install STS

Download the latest version

http://localhost:8080/

http://spring.io/tools


12

Open the zip file and go to the folder containing the sts tools itself

Extract all files to the path where you want to install sts

Start sts.exe to check if this version is compatible with the Jdk installed previously, if this is not

the same binaries (all must be 64-bit or 32-bit) you will have this error "Failed to load JNI shared

library"

As soon as above mentioned prerequisites are fulfilled, please proceed to the creation of the new

EUSurvey database and to the deployment of the application from compiled sources.

Knowledge

Control System Services

At different moments of the installation, you will have to start/stop/restart background tasks of your

system, called Services.

In Windows systems, Services are controlled from a specific view named “Services” that is accessible

from the Control Panel of your system or right from the Start Menu of your system.

To open this view, you can type “Services” into the input field in the start menu and activate the

respective element.


13

Another possibility is to double-click the “Services” entry in the Administrative Tools of your system’s

Control Panel.


14

In both cases, the following view will open, showing all available system services.

To modify a service’s stage, select an entry and click the right mouse button to open the context menu

of the respective entry.

Then, just select “Start”, “Stop” or “Restart” to change the service’s state.

Please make sure not to unintentionally stop services that are not described in this document, given that

this can affect the stability of your system.


15

Prepare the Database

Create a new schema

To create a new schema, please open MySQL Workbench and connect yourself to the database server

you have installed in a previous step selecting “Database -> Connect to Database…” from the

application’s menu.

Then, click the respective icon in the toolbar to start the creation of the schema. A new page will appear

offering the possibility to configure your new schema. Please give your new schema a meaningful name

(e.g. “eusurvey”) and select “utf8- default collation” as collation.


16

Once you have done so, please click “Apply” to create your new schema. On success, a new schema will

appear in the object browser.

Create a new DB user

Once you have successfully created a new DB to host the elements of EUSurvey, you will need a new

database user that is allowed to modify this database. The application will use the credentials to persist

any type of information. The current implementation requires a database user that is allowed to create

and alter tables and to read and write data in the created schema.

To do so, please select “Users and Privileges” from the “Management” menu section of your Workbench

and click the button labelled “Add Account”, located at the bottom of the screen.


17

If you are asked to re-enter the password of user “root”, please do so and proceed, clicking “OK”.


18

Once you have clicked “Add Account”, the system will ask you to give the new user a name and to assign

him respective privileges to perform specific tasks on your newly created database schema.

At first, please choose a meaningful name for your new user on the “Login” tab, and choose and confirm

a new password.

Then, change to the “Schema Privileges” tab and click “Add Entry…” to select a schema you want the

new user to be privileged to perform some actions on.

In the modal dialog that appears, select “Selected schema:” and highlight the name of the schema you

created in a previous step, before clicking “OK” to confirm your selection. This will make the selected

schema appear in the list of schemas to choose from on the previous page.

Please make sure that the name of the schema is highlighted correctly when it is selected. Otherwise,

the application will just not take the selection into account and will return without any error (and

without any selection).


19

From the list of schemas, please highlight the one you have just added and click OK to configure the

privileges for this schema.

From the tab labelled “Administrative Roles”, please set the “EVENT” privilege for this user.

Then, from the tab labelled “Schema Privilege”, please click “Select ALL” to assign all available privileges

to the new user you are about to create.

Finally, click “Apply” to create your new database user.


20

Once you have successfully performed above mentioned steps you are ready to build EUSurvey from its

sources and to deploy the application to the web-container installed in a previous step.

Enable Event-Scheduler

EUSurvey makes use of an advanced database functionality named “Event Scheduler”. Unfortunately,

this feature is not enabled per default, so that it has to be enabled before EUSurvey can make use of it.

To do so, please edit the configuration file of your MySQL server “my.ini” or “my.cnf”, usually located in

the server’s sub-folder under the “ProgramData” folder of your system disk.

If you don't find the ProgramData or the my.ini it could be because you have to change the folder

settings to let you view the hidden and system folder/files


21

In this file, please scroll down to the [mysqld] section of the file and add the following line to it:

“event-scheduler=ON”

To make the database take these settings into account, the database (that has already been started right

after installation and is running as a background service) needs to be restarted.

Therefore, please open the view on system Services and RESTART the system service labelled

“MySQL56” as described in the Knowledge section above.


22

Build the application To deploy a web application onto an Application Server (JEE compliant web-container), the application

must be available in a so-called WAR file (Web ARchive). Unlike applications written in interpreted

languages, such archives contain binary information and need to be compiled before being deployed.

To do so, the following steps will have to be performed:

Get the EUSurvey sources

Load the code into your IDE

Configure the application

Export the WAR archive

The result of these steps will be a WAR archive that you will have to deploy on a JEE application server

to finally run EUSurvey.

Get the sources Please get the EUSurvey source package and extract the content of the archive to a folder of your

choice. You will find all necessary information at this link

https://joinup.ec.europa.eu/software/eusurvey/description

https://joinup.ec.europa.eu/software/eusurvey/description


23

Load the code into your IDE Once you have extracted the EUSurvey source code to your hard disk, it will be time to load it into your

IDE for configuration (and modification).

To do so, please start the Spring Tool Suite you have installed in a previous step.

At start-up you are asked to select a workspace. A workspace is a specific folder the system will save all

project relevant data to. If you are unsure about what a workspace could be good for, just stay with the

default.

Click “OK” to proceed with the program launch.

Once the IDE has been loaded, we will proceed in loading the source code in to the IDE.

As for Eclipse, the Spring Tool Suite organizes individual applications you develop with it in so-called

Projects that serve as a container for your work on a specific application.

The EUSurvey source code already contains the information needed that just need to be imported to the

IDE.

To do so, please create a new Java Project selecting “File->New-> Java Project” from the application

menu.

Set its name to “eusurvey” and uncheck the “use default location” checkbox.

Then, click the button labelled “Browse…” to specify the folder you extracted the EUSurvey source

archive to.


24

Click finish to create the project.

Wait until the workspace has been built.

The integrated built-system named “Maven” will now start downloading dependencies during the first

build which can take quite some time.


25

Hint

In case your computer is located behind a network proxy and you have never used Maven before, you

might run into trouble, given that Maven requires an internet connection to download missing packages

from the internet.

To tell Maven to use your proxy please edit (or create) the Maven configuration file on your computer.

This file is named “settings.xml” and is usually located in the folder named “.m2” in your home

directory.

Editing this file, please add or adjust the section named “proxies” and make sure you use valid proxy

information.

Please notice that the screenshot just shows default settings, which will not work for you.

Once you have adjusted these settings, you need to tell the build system to restart package download

for dependent libraries. To do so, select “Maven->Update Project…” from your project’s context menu

and wait until the system has correctly downloaded missing libraries.


26

Hint

Just in case this does not solve the error, it might be necessary to rebuild the project. To do so, please

make sure that “Build Automatically” is selected in the Project menu of the application and click “Project

->Clean…” to clean and rebuild your project.


27

Configure the application Once you have correctly loaded the sources into your IDE, it is time to tell the application that way, to

use the database you have installed and configured in a previous step.

To do so, please open the file named “hibernate.cfg.MySql.oss.xml” from the “WEB-INF” directory of the

source tree and make sure the configured database connection matches your own database settings.

If the MySQL server is running on the same machine, you only have to configure username / password

for the database user you created. Otherwise you also have to adapt the URL.

Now open the file named “spring.properties” from the same directory and configure the application to

match your environment settings. This includes the following properties:

Database settings (for technical reasons this has to be done in this file as well. Please use the

settings you used in the previous configuration step (Mandatory)

Application server settings (Optional)


28

Eventual proxy settings (Optional)

Specification of system folders used to save uploaded files and created documents and the

(Optional)

SMTP server configuration (Optional).

The other settings have no meaning for the OSS version and can be ignored.

Hint

For sending out email invitations for secured surveys, the system needs to be configured to connect to a

working SMTP server. Please make sure the configured connection allows the sending of a large amount

of emails before making this feature available to your users.

Export the WAR archive Once you have correctly configured your application, you can compile the application to a WAR archive

for deployment.

To do so, please use the “Export” operation from the context menu of the project in the package

explorer.

From the appearing modal dialog, choose “Web -> WAR file” and click “Next” to proceed to the next

screen.


29

On the second screen, please select a destination folder for the WAR file you are about to create,

clicking the button labelled “Browse…”

Once you have done so, please click “Finish” to compile and export the application’s WAR file to the

selected destination.

Please make sure you name your package “eusurvey.war”, given that this name is required for self-

referenced calls by application at runtime.


30

The WAR file you have just exported basically contains the configured application that can be deployed

on an arbitrary web-container of your choice to run the application.

Deploy the application To deploy a configure application one of the easiest ways is to copy the WAR archive to a folder the

application server will check regularly for updates and will deploy any new application (WAR file) not yet

seen in this folder.

For Tomcat, this folder is called “webapps” and is located in the server’s folder under “Program Files”.


31

To deploy the application, just copy the WAR archive you exported in a previous step to the application

server’s “webapps” folder.

If you did not yet start the Tomcat application server, please do so as described in the section describing

the installation and start of Tomcat 7.

As soon as the server has been started, open the root URL of EUSurvey that is:

http://localhost:8080/eusurvey

Please notice that on first access, the application will start creating the database structure and will do

some initial configuration work . This might take a couple of minutes.

As soon as the application has finished configuration work, the application will welcome you, showing

the following screen (or similar):

http://localhost:8080/eusurvey


32

First Steps Once you have successfully deployed the application on your own application server, you are ready to

either run or modify your own instance of EUSurvey.

Depending on what is planned to do next, the interested reader is referred to the following

documentation:

The System Specification – For an overview of current implemented functionality (for

Administrators)

The Quick Start Guide – For a creating a survey right away (for Form Managers)

The FAQ pages – For advanced information on how to create surveys (for Form Managers)

The Developers Guide – For technical details of the application and basic information on how to

interact with the provided IDE (for Developers)

eusurvey oss installation guide - joinup · eusurvey oss installation guide 2 this document...

Documents