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 1
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. 2
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 3
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 4
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. 5
Please select Development Machine on the configuration tab wizard and make sure that Networking is enabled. 6
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. 7
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 8
During the installation process, please specify the folder you have installed your JRE7 to, as done in the previous step. 9
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. 10
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 11
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. 12
Another possibility is to double-click the Services entry in the Administrative Tools of your system s Control Panel. 13
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. 14
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. 15
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. 16
If you are asked to re-enter the password of user root, please do so and proceed, clicking OK. 17
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). 18
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. 19
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 20
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. 21
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 22
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. 23
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. 24
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. 25
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. 26
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) 27
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. 28
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 selfreferenced calls by application at runtime. 29
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. 30
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): 31
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) 32