Installation Manual YAWL in the Cloud D.M.M. Schunselaar Eindhoven University of Technology, P.O. Box 513, 5600 MB, Eindhoven, The Netherlands d.m.m.schunselaar@tue.nl 1 Introduction Welcome to the manual on how to install YAWL in the cloud. In this manual, we will take the reader step-by-step through the different phases of installing YAWL in the cloud. The steps in this manual are applicable to Microsoft s Azure cloud environment (http://azure.microsoft.com/). We have tried to be as clear as possible but we assume the reader has some familiarity with SQL, XML, and setting various configurations of the windows operating system. Prior to discussing the installation of YAWL in the cloud, we first elaborate on some general actions which have to be done in Azure. This manual is split into 5 parts: working with Microsoft Azure, setting up the database, setting up a router, adding an engine, and adding a tenant. The installation files can be found at http://www.win.tue.nl/coselog/wiki/yawlinthecloud. 2 Using Microsoft Azure In order to be able to install the cloud, we show some aspects of Microsoft s cloud platform Azure. We do not provide a complete overview but show the minimal information required to use Microsoft Azure. For more information on Azure, we would like to refer the reader to http://azure.microsoft.com/ en-us/documentation/. In this section, we first show how to create a virtual machine. Afterwards, we show how certain ports can be opened on this virtual machine. 2.1 Adding a virtual machine After having logged in into Microsoft Azure, one can see the screen as depicted in Fig. 1. Click on the tab Virtual Machines on the left of the screen. This results in the screen in Fig. 2. By clicking on + new on the lower left, we can instantiate a new virtual machine. We select Quick Create. We have the screen as presented in Fig. 3. For this example, we call our virtual machine This research has been carried out as part of the Configurable Services for Local Governments (CoSeLoG) project (http://www.win.tue.nl/coselog/).
ExampleMachine, we fill in a user name and password, and we set the region. After pressing the create a virtual machine button Azure starts provisioning a virtual machine Fig. 4. Fig. 1: The screen presented after logging in. 2.2 Opening ports on the virtual machine After having provisioned the virtual machine (Fig. 4), Azure automatically creates the possibility for a remote desktop to the virtual machine. To see the port on which the remote desktop is instantiated, click on the virtual machine and afterwards click on endpoints, the screen from Fig. 5 is presented. Using this port, we can connect to the virtual machine. First, we add an endpoint for an Apache server to this list. In order to do so, we click on + add in the bottom centre. For this example, we add a add a stand-alone endpoint but one can also use the other option in case this virtual machine has to be part of a loadbalancing set. After pressing the arrow, we are presented a screen where we can name our endpoint, indicate the protocol and the public and private port. We fill the values as indicate in Fig. 6. Afterwards, we press the checkmark and the endpoint is added to the list of endpoints. To be able to allow for requests on the endpoints, we have to add an exception to the firewall within the virtual machine. Adding the exception to the firewall is left to the reader. 2
Fig. 2: The virtual machines in Azure. 3 Setting up the Database Fig. 3: Creation of a virtual machine. YAWL in the cloud has been tested with two databases. The first database is MySQL, the second is MSSQL. Due to the fact that YAWL is not compatible 3
Fig. 4: Provisioning of a virtual machine. with the MSSQL version of Azure, we advice to use the MySQL version. In this manual, we show the use of MySQL. Within the installation files, we have provided scripts for creating the table structure within MSSQL but we do not elaborate on these. 3.1 MySQL Since MySQL is not native to Azure, we first need to create a virtual machine for running MySQL (in our example it is called YAWLPlanB since we originally opted for using a cloud based database). The steps for creating a virtual machine can be found in Sect. 2.1. After having created and provisioned the virtual machine, we need to create an endpoint to be able to communicate with the MySQL virtual machine. Instead of the ports listed in Sect. 2.2, we use the private port 3306 and the public port 3306. In the next step, we log in into the virtual machine and we install the MySQL workbench 2 (we are working with version 5.2 but newer versions might also work). Within the MySQL workbench, connect to the local instance of MySQL, and execute the script DatabaseYawlcloudEmptyStructureMySQL.sql from the installation files to create the database structure. The scrip can be executed 2 http://www.mysql.com/products/workbench/ 4
Fig. 5: Endpoints of a virtual machine. by File, Open SQL Script, and navigating to the location of the aforementioned file. Having created the database structure, we are finished with setting up the database. 4 Installing a Router In order to install a router, we first create a virtual machine and add the endpoint as described in Sect. 2 (we have called our virtual machine YAWL). After having set up the virtual machine and create the endpoints, we install Java 1.6 3, we install Notepad++ (for editing the XML files) 4, and we install Apache Tomcat 7.0.42 5. Having installed the software, we now copy the router (called YAWLCloud) to the webapps folder of Apache Tomcat. Next, we have to connect this router to 3 http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archivedownloads-javase6-419409.html 4 http://notepad-plus-plus.org/ 5 http://archive.apache.org/dist/tomcat/tomcat-7/v7.0.42/bin/ 5
Fig. 6: Adding an endpoint for HTTP requests. the earlier created database (Sect. 3). To do this, we navigate to the WEB- INF/classes/ folder within the router webapp. Here is a file called hibernate.cfg.xml located. Open this file with Notepad++. In Fig. 7, the various fields which have to be set are depicted. Since we are using MySQL, we have set the dialect and connection driver accordingly. In the connection url, we set the location of the database with the port appended with the database name. In the next two lines, we fill in the username and password of the database. Next to setting the hibernate file, we also need to change the web.xml file in the WEB-INF folder. In Fig. 8, we depict which value within web.xml needs to be modified, this value should direct to the location of the earlier mentioned webapp. Finally, we need to add the mysql-connector-java-5.1.x-bin.jar to the lib folder of Apache. This connector can be found in the virtual machine for the database in the folder MySQL/MySQL Connector J/. 5 Adding an Engine Having set up a router, we can now include an engine. Similar to the router, we first create a virtual machine and the endpoint (we have called our virtual 6
Fig. 7: The various settings to be made in hibernate.cfg.xml. Fig. 8: The setting to be made in web.xml. machine Server1 ). Next we install Java, Notepad++, and Apache Tomcat (see Sect. 4). Having installed all the software, we copy the engine to the webapps folder of Apache Tomcat. First, we connect the newly create engine to the earlier created database (Sect. 3). To do this, we navigate to the WEB-INF/classes/ folder within the engine webapp. Here is a file called hibernate.properties located. Open this file with Notepad++. In Fig. 9, the various fields which have to be set are depicted. Since we are using MySQL, we have set the dialect and connection driver accordingly. In the next two lines, we fill in the username and password 7
of the database. In the connection url, we set the location of the database with the port appended with the database name. Fig. 9: The various settings to be made in hibernate.properties. Next to setting the hibernate file, we also need to change the web.xml file in the WEB-INF folder. In Fig. 10, we depict which value within web.xml needs to be modified, this value should direct to the location of the cloud service and the location of this engine. Similar as for the router, we need to add the mysql-connector-java-5.1.xbin.jar to the lib folder of Apache. This connector can be found in the virtual machine for the database in the folder MySQL/MySQL Connector J/. Finally, we need to add this engine to the cloud using the management component of the cloud. The management component is accessible via the url of the cloud service (in our case http://yawl.cloudapp.net/yawlcloud/). After navigating to that location, we get the screen as depicted in Fig. 11. Under Menu, click on Servers and Engines. In the opened webpage, click on Add new server ; the screen in Fig. 12 is depicted. Fill in a nickname for this server, fill in the DNS of the virtual machine as the hostname, and for the CPU load URL also fill in the DNS of the virtual machine. 8
Fig. 10: The setting to be made in web.xml. After having added a server, we can enlist our engine on this server. To do so, click on Add new engine. Fill in the port number where the engine webapp is running (port 80 in our case) and the name of the webapp of the engine which is engine in our case. After having added the server and engine, we obtain the screen as depicted in Fig. 14. 6 Adding a Tenant Adding a tenant is similar to adding an engine. Similar to the engine, we first create a virtual machine and the endpoint. Next, we install Java, Notepad++, and Apache Tomcat (see Sect. 4). Having installed all the software, we first need to configure the tenant with its identifier within the cloud (this identifier is used later). We add the tenant via the cloud management component. Starting again from Fig. 11, click on Communities and Tenants. In the new webpage, click on Add new tenant. In the name field fill in the name of the tenant, in the ResourceService URL we have filled in: http://tenant.cloudapp.net:80/tenant/ib#resource. The first part refers to the webapp where the tenant is going to run. After pressing Add, 9
Fig. 11: The main screen of the management component. we obtain the list with tenants and we can see that our new tenant has obtained the id 0. After having added the tenant to the management component, we copy the tenant to the webapps folder of Apache Tomcat. First, we connect the newly create tenant to the earlier created database (Sect. 3). To do this, we navigate to the WEB-INF/classes/ folder within the tenant webapp. Here is a file called hibernate.properties located. Open this file with Notepad++. In Fig. 16, the various fields which have to be set are depicted. Since we are using MySQL, we have set the dialect and connection driver accordingly. In the next two lines, we fill in the username and password of the database. In the connection url, we set the location of the database with the port appended with the database name. Next to setting the hibernate file, we also need to change the web.xml in the WEB-INF folder. In Fig. 17, we depict which value within web.xml needs to be modified, this value should direct to the location of the cloud service and identifier of this tenant. 10
Fig. 12: The settings for adding a server. 11
Fig. 13: The settings for adding an engine. 12
Fig. 14: The overview of servers and engines. 13
Fig. 15: Adding a tenant to the cloud. 14
Fig. 16: The various settings to be made in hibernate.properties. 15
Fig. 17: The setting to be made in web.xml. 16