NGASI App in-the-cloud Panel Administration and User Guide
2 NGASI App in-the-cloud Panel Table of Contents Part I Introduction 5 1 Overview... 5 2 Requirements... 6 Part II Cloud Provider 8 1 Setup 2 Login... 8... 9 3 Manage Services... 9 Create Administrator... 9 Part III Administrator 12 1 Login... 12 2 Server Assets... 12 3 LoadBalancer... 14 4 Resellers/Webhosts... 15 Create Reseller... 15 Delete Reseller... 15 5 Runtimes... 16 6 Database... 18 7 Virtual Servers... 19 Virtuozzo/openVZ... 19 Part IV Resellers/Webhosts 21 1 Login... 21 2 Create User... 21 3 Edit User... 22 4 Delete User... 22 5 Management... 22 Part V Users 24 1 Login... 24 2 Applications... 24 Domains Deploy New... 26... 26 Deploy From... List 33 Virtual Hosting... 33 Delete Deployed... Application 33 File Privileges... 34 Delete Application... Archive 34 0
Contents 3 Node Testing... 34 3 Configuration... 35 4 Restart... 35 5 Best Practices... 36 6 Examples... 39 7 Programming... Language/Framework 40 JAVA CfWheels RAILS GRAILS Play Scala/Lift PHP/Zend... 40... 41... 41... 41... 41... 41... 41 Other Scripts... 41 8 Troubleshooting... 41 404 NOT FOUND... 42 Part VI Rest API 44 1 Administrator... 44 2 Web Host/Reseller... 44 Create User... 44 Update User... 45 Clients Memory... Usage 45 3 User... 45 Deploy Application... 46 Install... 46 Complete... 46 Success... 46 Upload Application... 46 Install... 46 Complete... 47 Success... 47 Set Password... 47 Part VII Failover 49 1 Database mysql... 49... 49 Index 0 3
I
Introduction 5 1 Introduction NGASI App-in-the-Cloud Panel enables drag-and-drop deployment of standard web applications onto scalable clouds. It is a Hosted and Out-of-the-Box Cloud Hosting solution for Data Centers and Web hosting providers to provide Platform-as-a-Service (PaaS) thus enabling continuous web presence capabilities for their clients' applications. 1.1 Overview NGASI App in-the-cloud Panel is the first true web application in-the-cloud panel. Enabling web providers capabilities for end users to easily deploy and manage their web applications in the Cloud. NGASI App in-the-cloud Panel is ideal for Database driven applications requiring high availability, with the option to scale across multiple servers permanently or temporarily. Essentially service providers can provide an Elastic like Cloud solution with existing infrastructure.
6 NGASI App in-the-cloud Panel This ensure affordable entry to the Cloud space. NGASI App in-the-cloud Panel enables service providers the ability to provide cloud hosting while also providing conventional hosting at the same time. That way such providers are able to spread costs and other resources around much better than other providers who specializes only in cloud hosting. NGASI App in-the-cloud Panel enables you to provide cloud hosting on the same servers used for traditional shared hosting. With NGASI App in-the-cloud Panel, horizontal scaling can be achieved in an economical manner providing resource usage stats of per hour application CPU, Memory, and Bandwidth usage. Most importantly, NGASI App in-the-cloud Panel provides a non proprietary deployment environment - thus applications are not forced to be customized as in some other cloud solutions. NGASI App in-the-cloud Panel provides great flexibility by supporting several programming languages and frameworks. This include JAVA, RAILS, GRAILS, Play Scala/Lift, Django, RAILO (CFML), CfWheels, PHP (Zend Framework) and other scripting languages. NGASI App in-the-cloud Panel is architected for an application centric environment. This enables fine grain configuration, management, and control of each deployed application. 1.2 Requirements NGASI App in-the-cloud Panel requires an installation of NGASI REST Server or NGASI AppServer Manager unto each server assets. NGASI REST Server is a lightweight server accessed by NGASI App in-the-cloud Panel for configuring and managing server assets.
II
8 NGASI App in-the-cloud Panel 2 Cloud Provider 2.1 Setup This section is intended for the App in-the-cloud Provider, such as Data Center Operators. NGASI App in-the-cloud Panel You need a License for NGASI App in-the-cloud Panel. Please contact a sales representative. Once the License has been granted, you would be provided with access information to download NGASI App in-the-cloud Panel. OS - Operating System For Linux and Unix based Systems (including 64bit) including: Red Hat Fedora Centos Ubuntu Whitebox Debian Suse and Linux other derivatives For Windows based Systems including: Windows 2003 and Windows 2008 Memory - RAM Server with at least 1GB RAM is required (for production). Web Browsers: Supported web browsers include: Internet Explorer 6 and higher Mozilla Firefox 1.5 and higher Safari Chrome NOTE: Allow Popups must be enabled. Install Download and add the ngasi-cp.war file to your JAVA Application Server webapps ROOT directory: Below are steps for the NON-JAVA programmer to get NGASI App in-the-cloud Panel up and running with
Cloud Provider 9 Apache Tomcat: 1)Download and install the JAVA JDK from the following URL: (NOTE: Please do not use the OpenJDK version distributed with Linux) http://www.oracle.com/technetwork/java/javase/downloads/index.html 2)Download and install Apache Tomcat from the following URL: http://tomcat.apache.org/download-70.cgi 3)Place ngasi-cp.war under the following Directory: <TOMCAT_HOME>/webapps/ROOT 4)Uncompress contents of ngasi-cp-war. 5)Delete ngasi.cp.war 6)Create a Datasource object with the jndi name "ws". 7)Startup Tomcat 2.2 Login Deploy NGASI App in-the-cloud Panel to a loadbalanced Cloud: Follow the steps above and start NGASI App in-the-cloud Panel. Login as Administrator and create Server Assets. Download the NGASI App in-the-cloud Panel WAR file. Deploy with the running instance of NGASI App in-the-cloud Panel. The newly deployed NGASI App in-the-cloud Panel can now be used in a high-availability environment. NGASI App in-the-cloud Panel deployed in such an environment enables self-healing capabilities. Upload the backup db.sql of the existing NGASI App in-the-cloud Panel. Also change the CacheMgr setting in WEB-INF/ngcp/cp/cp-ext.properties to: ngasi.modules.cp.impl.memcachedcachemgr The default HTTPS port 8663 and host name localhost: (the default HTTP port is 8666) Login URL: https://localhost:8663/modules/cp/dc/cpdc/index.zul The login for Super Administrator (Data Center Operator) is "dcoperator" and the default password is "coolgeek". To change the "dcoperator" password click the Login Name, displayed on the top right of the screen or refer to the "Rest API" section. 2.3 Manage Services Services the Cloud Provider will be managing. 2.3.1 Create Administrator Administrators are clients,such as web host service providers, of Data Center Operators who rent dedicated servers, etc.
10 NGASI App in-the-cloud Panel Click "Create Administrator" to create Cloud Administrator Accounts. Enter the appropriate information in the Fields. Then click the "Add" button. Once the NGASI App in-the-cloud Panel Administrator Account is Added, the Administrator should appear in the "Administrator List". The Administrator Login and management is detailed in the Administrator section. As the Data Center Operator, you can login directly to the Administrator Account by clicking on the corresponding icon in the "Administrator List".
III
12 NGASI App in-the-cloud Panel 3 Administrator 3.1 Login The Administrator is the NGASI App in-the-cloud Panel user, used for managing all accounts, which includes Resellers and Users. This is normally a web host service provider. Access information should be provided by the Cloud Provider. Assuming the default HTTPS port 8663 and host name localhost: Login URL: https://localhost:8663/modules/cp/dc/cpadmin/index.zul By default the Data Center Operator account is also a built-in Administrator account that cannot be removed. 3.2 Server Assets System Requirements The following are the recommended OS: Centos 5.x Redhat 5.x NOTE: For SELinux enabled systems, "enforcing" must be disabled. Do so by editing /etc/sysconfig/selinux. Also the system should not have anti-virus software enabled. System should not have any other hardened Kernel, such as Atomic Secured Linux (ASL). Server Assets Download NGASI REST Server http://www.ngasi.com/cloud/cp/rest.zul Install NGASI REST Server onto servers to be used as Application Server Nodes and Databases. NOTE: If also utilizing OpenVZ/Virtuozzo VPS, you should install NGASI REST Server unto the host system. Once this is done, NGASI REST Server will be able to recognize and manage any guest VPS. This is much more efficient than installing NGASI REST Server unto several VPS. NOTE: For optimal performance, the uplink/download speeds of the server network ports should be at least 1GB.
Administrator 13 Access Info Login (see Login section) to NGASI App in-the-cloud Panel and add the server assets to the resource inventories by entering the host name and user/password information. NGASI App in-the-cloud Panel communicates with the destination server via the REST API. If the password is the default "coolgeek", you will be prompted to change the password. If not the password will NOT be changed, and the server asset will not be added. NOTE: If the server is firewall protected, please enable access to the IP address and port. NOTE: You DO NOT need a virgin server to install any of the NGASI App in-the- Cloud Panel components. That is one of the purposes of NGASI App in-the-cloud Panel - to enable Cloud services with your existing infrastructure. Server Assets will be used for configuring application servers and databases. Application Servers If the Server Asset will be used for running Applications, then check this Option. NOTE: If the server is firewall protected, please enable access to the web ports from the Loadbalancer. Check the VPS Option for running account applications in their own VPS. You would also need to add VPS IP Pools. The VPS can be dynamically created and an IP address assigned. NOTE: For OpenVZ or virtuozzo VPS support, OpenVZ or virtuozzo must already be installed. Databases If the Server Asset will be used for running Databases, then check this Option. Set the maximum databases and the database type - Primary or Replicated. User Databases are assigned locally resolved Hostnames. This way if the Database fails-over to another server, the application would not need to be reconfigured as the same hostname will be used but would resolve to the other server. mysql phpmyadmin, the web based mysql administration tool, is also configured Load Balancers If the Server Asset will be used for Load Balancing, then check this Option.
14 NGASI App in-the-cloud Panel NGINX Add IP Address for NGINX Load Balancer. NGASI REST Server will install NGINX on the remote server. This implies a web server should NOT be running on the remote server or the IP Address should NOT already be binded on Port 80 and 443. Multiple IP Addresses may be associated with the Server. Each IP Address entry respresents a NGINX Load Balancer Object. It is recommended that the server should be dedicated to just running the Load Balancing service. If the Server Asset will just be dedicated to Load Balancing, then you should add the following line to: /usr/ngasi/webapps/root/web-inf/modules/uap/m-ext.properties no_update_component=true WEBDav/SVN If this Server Asset will be used for WEBDav/SVN access, then check this Option. NOTE: Server Assets may be used for multiple functions. 3.3 LoadBalancer Enter load balancer pool information here. IP Addresses/CNAMES Max accounts. Max connections (optional). You are able to assign multiple load balancers to a server. Make sure addresses and ports to not conflict. Internal HTTP IP Addresses and Ports Set differently if also using nodes for regular web hosting to avoid conflicts; for instance cloud accounts and web accounts on the same server. Load Balancing The load on server nodes should allow for additional load in case of a fail-over. That is, a server node should not be operating under full load or capacity. Below is a simple formula to determine the server resources that should be available in case of a fail-over. (This assumes an equally distributed load weight.) 100 / (total nodes) = (available capacity) % So for example a LoadBalanced Cluster with 4 nodes: 100 / 4 = 25 % So in determining the max accounts and other resources to place on the server nodes,
Administrator 15 an allowance of 25% available resources should be unused. In reality, before calculating the percent of resources to be made available, a number of less than 100 % should be used in the calculation. For good measures 80-90 % should be the figure to start off with. This is because a server should never be running at 100% percent capacity - to avoid crashes. 3.4 Resellers/Webhosts Use this feature to manage Resellers (Webhosts). Resellers manages the end user accounts. By default the Data Center Operator account is also a built-in Reseller account that cannot be removed. 3.4.1 Create Reseller Click the "Create Reseller" to create Reseller Accounts. Enter new login name. Then click the "Add" button. Once the NGASI App in-the-cloud Panel Reseller Account is Added, the Reseller should appear in the "Reseller List". The Reseller Login and management is detailed in the Resellers/Webhosts section. As the Administrator, you can login directly to the Reseller Account by clicking on the corresponding icon in the "Reseller List". 3.4.2 Delete Reseller NOTE: Deleting a Reseller will automatically Delete any User Accounts created by the Reseller. Select one or more Resellers in the "Reseller List". Then Click the "Delete User" button to delete the selected Reseller Accounts.
16 NGASI App in-the-cloud Panel 3.5 Runtimes NGASI App in-the-cloud Panel supports a number of Runtime environments. JAVA JDKs: 1.7.x 1.6.x 1.5.x Application Servers: Tomcat GlassFish JBoss RAILS Supported Ruby versions include 1.8.7 1.8.6 Supported JRuby versions include 1.5.0 Supported RAILS versions include 3.0.x 2.3.5 Application Servers Passenger Mongrel GlassFish Tomcat GRAILS Supported GRAILS versions include 1.3.x 1.2.x Application Servers GRAILS Embedded Tomcat Play Supported Play versions include 1.x
Administrator 17 2.x Application Servers Play Embedded Netty Scala/Lift The Simple Build Tool (SBT) is used to build and deploy Scala/Lift Applications. Application Servers Scala/Lift Embedded Jetty Django Supported Python versions include 2.6.x 2.5.x Supported Django versions include 1.2.x Railo (CFML) Supported Railo (CFML) versions include 3.1.x and higher CfWheels Supported CfWheels versions include 1.x and higher PHP/Zend PHP-5.3;Zend-1.10.x PHP-5.2;Zend-1.10.x Quercus (JAVA) Other Scripts Apache
18 NGASI App in-the-cloud Panel 3.6 Database If available, a Database is automatically created for the application to use. JAVA If a DataSource name is specified, the application server is configured with a JNDI DataSource entry containing the database access information. RAILS The "production" database configuration is populated in the database.yml file. db:migrate is automatically run on the application upon deployment. GRAILS The "production" database configuration is populated in the DataSource.groovy file. Play The "production" database configuration is populated in the application.conf file. Scala/Lift The database configuration is populated in the default.props file like so: src/main/resources/props/default.props db.driver= db.url= db.user= db.password= db= db.host= Django If available, a Database is automatically created for the application to use and the "default" database configuration is populated in the settings.py file. And the "syncdb" command is executed. During installation of Django apps, a superuser is created. Below are the default credentials: User: admin Password: coolgeek Railo (CFML) If available, a Database is automatically created for the application to use and the DataSource configuration is set. CfWheels If available, a Database is automatically created for the application to use and the DataSource configuration is set. The DataSource name is set to "wheels". PHP/Zend If available, a Database is automatically created for the application to use and the
Administrator 19 "production" database configuration is populated in the application.ini file. 3.7 Virtual Servers This section details how to make virtual servers available. 3.7.1 Virtuozzo/openVZ The following steps below will enable accounts to run applications under their own Virtual Private Servers (VPS) on a VZ based server. 1)Virtuozzo or openvz must already be installed and running on the system. NOTE: A recent version of the VZ kernel should be running. 2)Download and copy the following VZ templates to the VZ template cache directory (/vz/template/cache): http://downloads.ngasi.com//ngasi_install/vz/ngasi-vps-scientificlinux-6.0-x86.tar.gz 3)Download and install NGASI REST Server http://www.ngasi.com/cloud/cp/rest.zul 4)Add information for the IP address of the VPS that will be created for the accounts. Add the following entry to /usr/ngasi/webapps/root/web-inf/modules/uap/m-ext.properties (create file if does not exists) vz_public_ips=172.16.0.43/4,172.16.0.100,172.16.0.200 number proceeding "/", means a range incremented by up to that number e.g. 172.16.0.43/4 is the same as 172.16.0.43,172.16.0.44,172.16.0.45,172.16.0.46 5)Make sure the system is registered as a "Server Asset". NOTE: At least 2 systems must be configured as above for VZ to be made available as an option when creating user accounts.
IV
Resellers/Webhosts 21 4 Resellers/Webhosts Use this feature to manage User Accounts. User Accounts are the end users that deploys and manages the applications. 4.1 Login Login Info: The host name and port should be provided by your Administrator. So assuming the default HTTPS port 8663 and host name localhost: Login URL: https://localhost:8663/modules/cp/host/index.zul 4.2 Create User Click the "Create User" to create User Accounts. TYPE in desired user account login name. Then click the "Add" button. Once the User Account is Added, the User should appear in the "User List". The User Login and management is detailed in the Users section. As the Reseller, you can login directly to the User Account by clicking on the corresponding icon in the "User List". NOTE: At the minimum, a JAVA application requires at least 64MB RAM. At the minimum, a RAILS Application requires at least 32 MB RAM (Passenger), 80MB (GlassFish), 50MB (Mongrel on Linux), or 70MB (Mongrel on Windows). At the minimum, a GRAILS application requires at least 256MB RAM. At the minimum, a Play application requires at least 12MB RAM. At the minimum, a Django application requires at least 12MB RAM. Keep this in mind when allocating Memory and Application limits across multiple server nodes. RESOURCE LIMITS: If a MAX is set to greater than 0 and the value differs to a MIN, then total resource usage will start off with the MIN and grow up to the MAX.
22 NGASI App in-the-cloud Panel Enabling the Shrinkable setting, will eventually decrease the allocated resources back to the MIN. Enabling Shrinkable is ideal for on demand computing, e. g. per hour usage service. For fixed resource limits, set the MAX equal to MIN. In a fixed resource configuration, the MIN is actually the MAX. 4.3 Edit User Select an Account in the "User List". Then Click the "Edit User" button to edit the selected User Account. After making the appropriate changes, click the "Save" button. 4.4 Delete User NOTE: Deleting a User will automatically Delete any applications deployed by the User. Select one or more Accounts in the "User List". Then Click the "Delete User" button to delete the selected User Accounts. 4.5 Management NGASI App in-the-cloud Panel comes equipped with resource management tools such as Memory Management CPU Management Bandwidth Management Maximum Application Limits Disk Limits (System User Accounts) Nodes Management (vertical and horizontal scaling and shrinking)
V
24 NGASI App in-the-cloud Panel 5 Users The User accounts is the end user that deploys and manages the applications. 5.1 Login Login Info: The host name and port should be provided by your Administrator. So assuming the default HTTPS port 8663 and host name localhost: Login URL: https://localhost:8663/modules/cp/user/index.zul 5.2 Applications This section covers topics about application management. Account applications are run by non-privileged users across various server nodes. The names of the system users are dynamically assigned and differs to your login name. JAVA All applications are deployed under the user's java/webapps directory. For a user named ngcp1, an application, myapp, will be deployed as follows: /home/ngcp1/java/webapps/myapp GlassFish: For GlassFish, apps are deployed under the Glassfish "autodeploy" directory. JBoss: For JBoss, apps are deployed under the JBoss "deploy" directory. RAILS All applications are deployed under the user's rails/webapps directory. For a user named ngcp1, an application, myapp, will be deployed as follows:
Users 25 /home/ngcp1/rails/webapps/myapp GRAILS All applications are deployed under the user's grails/webapps directory. For a user named ngcp1, an application, myapp, will be deployed as follows: /home/ngcp1/grails/webapps/myapp Play All applications are deployed under the user's play/webapps directory. For a user named ngcp1, an application, myapp, will be deployed as follows: /home/ngcp1/play/webapps/myapp Scala/Lift All applications are deployed under the user's scalalift/webapps directory. For a user named ngcp1, an application, myapp, will be deployed as follows: /home/ngcp1/scalalift/webapps/myapp Django All applications are deployed under the user's django/webapps directory. For a user named ngcp1, an application, myapp, will be deployed as follows: /home/ngcp1/django/webapps/myapp PHP/Zend All applications are deployed under the user's zend/webapps directory. For a user named ngcp1, an application, myapp, will be deployed as follows: /home/ngcp1/zend/webapps/myapp Railo (CFML) All applications are deployed under the user's railo/webapps directory. For a user named ngcp1, an application, myapp,
26 NGASI App in-the-cloud Panel will be deployed as follows: /home/ngcp1/railo/webapps/myapp GlassFish: For GlassFish, apps are deployed under the Glassfish "autodeploy" directory. CfWheels All applications are deployed under the user's cfwheels/webapps directory. For a user named ngcp1, an application, myapp, will be deployed as follows: /home/ngcp1/cfwheels/webapps/myapp GlassFish: For GlassFish, apps are deployed under the Glassfish "autodeploy" directory. Other Scripts: All applications are deployed under the user's web directory. For a user named ngcp1, an application, myapp, will be deployed as follows: /home/ngcp1/webapps/myapp. NOTE: For PHP applications deployed with Quercus, refer to the JAVA section. 5.2.1 Domains At least 1 Domain must be set prior to installing any application. Go to the Domain section and set. There you will also see the IP Address or CNAME that the domain should resolve to. This would require configuring at your Domain Registrar or some other service. NOTE: You must explicitly add the "www" subdomain if desired. 5.2.2 Deploy New Click the "Deploy New" deployment. button to Upload a new Application Archive for Fill out any necessary information then click "Continue" to proceed. Once successfully deployed, an Icon symbolizing the deployed application will be added to the Canvas display. JAVA
Users 27 The JAVA application must be in WAR format. The expanded directory tree should look like:... WEB-INF NOTE: If available, a Database is automatically created for the application to use and the DataSource (if the name is specified) is configured. Application Directory The application is deployed to: <HOME_DIRECTORY>/java/webapps So an application named myapp would be in the following directory: <HOME_DIRECTORY>/java/webapps/myapp NOTE:For GlassFish, apps are deployed under the Glassfish "autodeploy" directory. NOTE:For JBoss, apps are deployed under the JBoss "deploy" directory. RAILS The RAILS application must be in ZIP format. The expanded directory tree should look like: -app -config -db -doc -lib -log -public -script -test -tmp
28 NGASI App in-the-cloud Panel -vendor NOTE: If available, a Database is automatically created for the application to use and the "production" database configuration is populated in the database.yml file. db:migrate is automatically run on the application upon deployment. Application Directory The application is deployed to: <HOME_DIRECTORY>/rails/webapps So an application named myapp would be in the following directory: <HOME_DIRECTORY>/rails/webapps/myapp GRAILS The GRAILS application must be in ZIP format. The expanded directory tree should look like: -grails-app -lib -scripts NOTE: If available, a Database is automatically created for the application to use and the "production" database configuration is populated in the DataSource.groovy file. Application Directory The application is deployed to: <HOME_DIRECTORY>/grails/webapps So an application named myapp would be in the following directory: <HOME_DIRECTORY>/grails/webapps/myapp NOTE: You may deploy a GRAILS application as a JAVA WAR, however in order for the DataSource be set, you would need to specify the data source's JNDI name in the grails-app/conf/datasource.groovy file as follows: datasource { jndiname = "java:comp/env/jdbc/mydatasource" # or
Users 29 } # jndiname = "java:comp/env/mydatasource" NOTE: Also if the GRAILS app is deployed as a regular JAVA application, you may need to upload the Database Schema. Play The Play application must be in ZIP format. The expanded directory tree should look like: -app -conf -public NOTE: If available, a Database is automatically created for the application to use and the "production" database configuration is populated in the application.conf file. Application Directory The application is deployed to: <HOME_DIRECTORY>/play/webapps So an application named myapp would be in the following directory: <HOME_DIRECTORY>/play/webapps/myapp Scala/Lift The Scala/Lift application must be in ZIP format. The expanded directory tree should look like: -src -project
30 NGASI App in-the-cloud Panel NOTE: If available, a Database is automatically created for the application to use and the database configuration is populated in the default.props file like so: src/main/resources/props/default.props db.driver= db.url= db.user= db.password= db= db.host= Application Directory The application is deployed to: <HOME_DIRECTORY>/scalalift/webapps So an application named myapp would be in the following directory: <HOME_DIRECTORY>/scalalift/webapps/myapp Django The Django application must be in ZIP format. The expanded directory tree should look like: -app -settings.py -... NOTE: If available, a Database is automatically created for the application to use and the "default" database configuration is populated in the settings.py file. And the "syncdb" command is executed. During installation of Django apps, a superuser is created. Below are the default credentials: User: admin Password: coolgeek Application Directory The application is deployed to: <HOME_DIRECTORY>/django/webapps So an application named myapp would be in the following directory:
Users 31 <HOME_DIRECTORY>/django/webapps/myapp Railo (CFML) NOTE: You can also install Railo as a regular JAVA Application (see above). The Railo (CFML) application must be in ZIP format. The expanded directory tree should look like:... whatever.cfm NOTE: If available, a Database is automatically created for the application to use and the DataSource configuration is set. NOTE: For security purposes (as well as for a loadbalanced cloud environment), the Railo admin console is unavailable by default. To enable, remove the security constraint in the WEB-INF/web.xml file. Application Directory The application is deployed to: <HOME_DIRECTORY>/railo/webapps So an application named myapp would be in the following directory: <HOME_DIRECTORY>/railo/webapps/myapp NOTE:For GlassFish, apps are deployed under the Glassfish "autodeploy" directory. CfWheels The CfWheels application must be in ZIP format. You only need the CfWheels project files. You do not need to bundle CfWheels - that is automatically done for you at deployment. The expanded directory tree should look like:
32 NGASI App in-the-cloud Panel... config models controllers views css images NOTE: If available, a Database is automatically created for the application to use and the DataSource configuration is set. The DataSource name is set to "wheels". Application Directory The application is deployed to: <HOME_DIRECTORY>/cfwheels/webapps So an application named myapp would be in the following directory: <HOME_DIRECTORY>/cfwheels/webapps/myapp NOTE:For GlassFish, apps are deployed under the Glassfish "autodeploy" directory. NOTE: You can also install CfWheels as a regular Railo (CFML) Application (see above). PHP/Zend The PHP/Zend application must be in ZIP format. The expanded directory tree should look like: -application -public NOTE: If available, a Database is automatically created for the application to use and the "production" database configuration is populated in the application.ini file. Application Directory The application is deployed to: <HOME_DIRECTORY>/zend/webapps So an application named myapp would be in the following directory: <HOME_DIRECTORY>/zend/webapps/myapp
Users 33 NOTE: If deploying a PHP application not using the Zend Framework, place the PHP files in a directory called "public" before archiving the application. NOTE: For PHP applications deployed with Quercus, refer to the JAVA section. 5.2.3 Deploy From List NGASI App in-the-cloud Panel enables you to redeploy an Application that has already been uploaded, so you do not have to re-upload the same application each and every time. Click the "Deploy from list" button. Drag-and-drop desired Application from the Application Factory list to the Canvas. Click the "YES" button to proceed. NOTE: If available, a Database is automatically created and configured for the application to use. 5.2.4 Virtual Hosting Application Virtual Hosting (not to be confused with Web Server Virtual Hosting) maps an application to the root of one or more Domain hostnames. For example an application, myapp, deployed on www.mydomain.com: http://www.mydomain.com/myapp could be accessed instead as http://www.mydomain.com with Virtual Hosting enabled. Click on the icon, in the Canvas, of desired Application. Then click the "Virtual Hosting" button (you can also drag-and-drop the icon to the button as well). Select one or more Domain hostnames in the Selection Box, then Click "Add" to proceed. NOTE: To remove any Virtual Hosting that was set, you would click the "Delete" button instead. 5.2.5 Delete Deployed Application To delete a deployed application, click on the icon, in the Canvas, of desired Application.
34 NGASI App in-the-cloud Panel Then click the "Delete" button (you can also drag-and-drop the icon to the button as well). NOTE: If the associated database is managed by NGASI App in-the-cloud Panel, it will also be deleted. 5.2.6 File Privileges Although the deployment is controlled by the NGASI App in-the-cloud Panel, if your administrator has provided WEBDav/SVN access, you can easily edit and manually manage your application via those methods (then sync the changes to the various nodes via NGASI App in-the-cloud Panel). However the initial deploy must be done through NGASI App in-the-cloud Panel, which sets up the appropriate environment as part of the setup process. 5.2.7 Delete Application Archive Use this option to remove an Uploaded Application Archive from the Application Factory. Click the "Deploy from list" button. Drag-and-drop desired Application from the Application Factory list to the "Delete" button. Click "Continue" to proceed. 5.2.8 Node Testing Depending on your service provider, you may have internet access to the backend Web Servers of the nodes in the Load Balanced cluster. This will enable you to test the nodes in the Load Balanced cluster, e.g. check that each node is synchronized and the web pages are showing the correct data. Because if you go directly to the site via the Load Balancer, you may not notice a problem on an individual node. First go to the "Clusters" feature. Click on the Load Balancer to see the details of the various nodes. This includes the host IP Address as well as the ports. Exclusive Load Balancers If the Load Balancer is exclusively assigned to your account, you would see the options to disable/enable nodes. Disable all nodes except the one to be tested on.
Users 35 Shared Load Balancers You want to simulate the host name on the PC you would be performing the test on. So for example hostname "ngdemo.test1.app-in-the-cloud-hosting.com" and node with IP Address 111.111.111.111, add the following line to the PC Host file: 111.111.111.111 ngdemo.test1.app-in-the-cloud-hosting.com In Linux this file is /etc/hosts and in Windows it is C:\WINDOWS\SYSTEM32 \DRIVERS\ETC\HOSTS. Finally assuming the backend HTTP port of the node is 8080, the test Web URL would look like: http://ngdemo.test1.app-in-the-cloud-hosting.com:8080 NOTE: You can also simulate a load balance environment at your end by setting up 2 instances of your app going to the same DB. Then test for consistencies (or lack of) in the responses. NOTE: Remember to comment out the Host entry when finished with test. NOTE: The use of the node Web URLs should only be used temporarily for testing. They should not be used for monitoring or configuring because the nodes may change at any time. 5.3 Configuration If more than 1 Application Server is available to your account, you may change the default Application Server or other aspects of your setup by following the steps below. Click the "Configuration" button in the Left Menu. Make appropriate changes. Then click the "Update" button to proceed. You may also specify specific Application Servers when deploying an application. This allows different applications to be run on different application servers. 5.4 Restart Sometimes you may have a need to Restart the Application. Click the "Restart" button in the Left Menu to do so.
36 NGASI App in-the-cloud Panel 5.5 Best Practices MAKING YOUR APPLICATION CLOUD-READY In the world of always on, companies both big and small are wanting their applications to always be available. Cloud is the efficient packaging of IT infrastructure to provide limitless resources for applications to quickly scale up or down on the fly. This leads to new challenges for application design. Although there are no standards, there are commonly practiced and accepted norms of both cloud provider and cloud consumer (application). In order for the applications to be able to be scaled, the Cloud must provide the ability for applications to move around in the cloud. Before this can happen, the Cloud provider should guarantee the following: Infinite available resources - bandwidth, CPUs, Loadbalancers, Databases, Application Servers, etc. All available in real time. For synchronization purposes, the times of the system clocks for the various nodes should be set to approximately the same. Application references to Date/Time should utilize the built-in system time function of the Database. After all, the database is accessed by all the application server nodes. In addition to the core Cloud infrastructure, there should be a service, closer to the application layer. We call this the Application Hosting Cloud or Platform-as-a-Service (PaaS). The Application Hosting Cloud utilizes the cloud infrastructure by programming services against the Cloud API to provide complete cloud automation and monitoring for the applications. So once the application is deployed on the Cloud, the Application Hosting cloud takes care of all management of the application, which includes automatically scaling up or down of the application. NGASI App in-the-cloud Panel provides such a solution. The requirements for designing applications for the Cloud, includes principals for designing scalable application plus more. A key to architecting your application for the Cloud is to ensure the application is database driven. Persistent content should be served by the database. The database should be agnostic. Making the database as dumb as possible makes it easier to migrate (switch cloud providers or database vendors)
Users 37 and to distribute more processing on application server nodes. MULTI-TENANCY The application should not be reliant on hard-coding of resource references, such as, database connection and disk resources. There should also be no dependence on configuration files for references to resources. Since the location of the application (and multiple instances of it in a cluster) as well as database is not definite (could be anywhere in the Cloud), the application should rely on system environment variables for disk access (such as home.dir,tmp.dir,,java.io.tmpdir, _SERVER["PWD"], _SERVER["HOME"], etc.). Using a standard framework, such as Struts, RAILS, GRAILS, Play, Scala/Lift, Django, Zend, etc. also helps to provide an abstraction for accessing resources, such as databases, etc. The application should also be designed to sit side-by-side another instance of the same application sharing the same runtime; for instance running multiple instances of the same application under the same JAVA JVM. In addition, the application should not be tied to a specific version of the programming language or framework as there is no guarantee such exact environment will exist in the cloud. As mentioned, applications (and the database) are moved around depending on predefined logical rules. This means that the cloud customer may not have physical access to the application, e.g. SSH or FTP. Thus expectations of the Application Hosting Cloud includes automatic configuration of the application, such as the database access; database replications; synchronizing the application onto multiple nodes in the loadbalanced cluster. The Application Hosting Cloud should also have mechanism in place for auto scaling (vertically and horizontally) of the application; and facilities for updating already deployed applications. CACHE NOTE: Accessing a replicated database may be expensive in terms of performance, so local caching when possible is encouraged. For Global caching (temporary data accessed by all the nodes), employ the uses of a cache manager such as Memcached, etc. Cache session based data locally instead of making unnecessary calls to the database for reads.
38 NGASI App in-the-cloud Panel Do not design your app to store dynamic content or states on disk - design to store in database. In the event File storage is required, a high availability network storage solution should be used. As mentioned before, the automated environment is ideal for database driven applications. This means that if part of your application includes large files such as videos, it may be a good idea to break up the application. For under such conditions, the application will not scale well in real time - due to I/O and other latency issues. So for large static resources, they should be hosted somewhere else (such as on a Content Delivery Network or other high-availability network storage). You may manually add these resources to the nodes in your load-balanced cloud. However depending on your service provider, you may not have direct access to the node. And again, the same real-time issues pops up if needing to quickly scale onto additional nodes. Plus the real chance of your nodes becoming out-of-sync. SPECIAL MESSAGES AND BANNERS Cloud hosting is no panacea - there is no 100% availability. However there are ways to manage the unexpected. During operation, although the application server nodes may be running, a number of issues may arise that affect availability; for instance the database may be unavailable or in read-only mode. Also a shared network drive may not be available as well. In this case certain features of your site may be unavailable, but the application would still be up (the fact that the application server nodes are running). Your code should check for such interruptions and display the appropriate messages in a banner, while still keeping the functioning parts of the site available. DNS For failover purposes, the DNS for the hostname leading to the application should point to multiple DNS Servers. These DNS Servers should be located in separate Datacenters. LOG STATISTICS AND ANALYSIS In a Cloud environment, your application would be proxied by some sort of loadbalancing device. This mean access to logs and real source IP Addresses probably will not be possible; some Load Balancers do forward the X-Forwarded-For header which would contain the real IP Address. For log statistics and analysis, it is recommended an offsite link to a traffic analyzer engine be embedded in your application web pages. Google Analytics is a good example.
Users 39 5.6 Examples JAVA Below are descriptions and links to some sample JAVA Applications: sqltestapp.war This is a simple database driven counter application. The value of the counter is stored in a Database. The Database is accessed by a DataSource object, named "GenericDataSource". In addition, the application requires an SQL script be run to create the necessary tables. NGASI App in-the-cloud Panel is able to do so by uploading the SQL script. The required SQL script is sqltestapp.sql. RAILS Below are descriptions and links to some sample RAILS Applications: tracks.zip Tracks is a web-based application to help you implement David Allen s Getting Things Done methodology. It was built using Ruby on Rails. http://getontracks.org phonebook.zip This is a simple database driven contacts application. In addition, the application requires an SQL script be run to create the necessary tables. NGASI App in-the- Cloud Panel is able to do so by uploading the SQL script. The required SQL script is phonebook.sql. GRAILS Below are descriptions and links to some sample GRAILS Applications: petclinic.zip Petclinic is the GRAILS framework demonstration application. Play Below are descriptions and links to some sample Play Applications: yabe.zip yabe is a sample blog application from the Play guide tutorial.
40 NGASI App in-the-cloud Panel Railo (CFML) Below are descriptions and links to some sample Railo Applications: cfmexample.zip This is a simple database driven Pet Clinic application for Railo (CFML). In addition, the application requires an SQL script be run to create the necessary tables. NGASI App in-the-cloud Panel is able to do so by uploading the SQL script. The required SQL script is cfmexample.sql. Finally, during the initial deployment stage, the DataSource name, "GenericDataSource", must be specified. CfWheels Below are descriptions and links to some sample CfWheels Applications: wheelspc.zip This is a simple database driven Pet Clinic application for CfWheels. It is based on the popular Petclinic application from the GRAILS framework demonstration application. In addition, the application requires an SQL script be run to create the necessary tables. NGASI App in-the-cloud Panel is able to do so by uploading the SQL script. The required SQL script is wheelspc.sql. PHP/Zend Below are descriptions and links to some sample PHP Applications: quickstart.zip quickstart Guest Book is a simple database driven Zend application. In addition, the application requires an SQL script be run to create the necessary tables. NGASI App in-the-cloud Panel is able to do so by uploading the SQL script. The required SQL script is quickstart.sql. 5.7 Programming Language/Framework 5.7.1 JAVA Below are some information regarding specific programming languages and frameworks. When switching application servers, NGASI App in-the-cloud Panel attempts to migrate existing applications unto the new app server.
Users 41 When switching TO another app server FROM Glassfish, the existing glassfish apps are expanded to the "java/webapps" directory. This is because in Glassfish, the apps are deployed to the "autodeploy" directory instead of the "java/webapps" directory. And vice versa, when migrating TO GlassFish FROM another app server, the app is archived (WAR), and deployed to the "autodeploy" directory. 5.7.2 CfWheels 5.7.3 RAILS URL Rewriting is enabled for CfWheels. The URL Rewriting engine sits in the Railo server (as apposed to Apache in most environments). For an application named myapp, the Ruby script path would look like: <HOME_DIRECTORY>/rails/webapps/myapp/bin/ruby 5.7.4 GRAILS 5.7.5 Play GRAILS apps are run in the default GRAILS runtime (Tomcat) bundled with GRAILS. By default, each app is run under its own private GRAILS runtime. Play apps are run in the default Play runtime (Netty) bundled with Play. By default, each app is run under its own private Play runtime. 5.7.6 Scala/Lift The Simple Build Tool (SBT) is used to build and deploy Scala/Lift Applications. 5.7.7 PHP/Zend If the JAVA based Quercus is selected as the PHP application runtime, the app is converted to a JAVA application. 5.7.8 Other Scripts Intentionally left blank. 5.8 Troubleshooting
42 NGASI App in-the-cloud Panel 5.8.1 404 NOT FOUND If you see a 404 NOT FOUND when browsing your application, and in the NGASI App in-the-cloud Panel there is an "X" in the Application Icon, try restarting the Application. The application may have been shutdown if your total applications memory or other resource usage exceeded the maximum allowed for your account.
VI
44 NGASI App in-the-cloud Panel 6 Rest API This section covers the Rest API functions. The URL to the Rest base looks like: http://<host>:8666/rest/cp/... or https://<host>:8663/rest/cp/... Each request should be accompanied with at least the following parameters: ftp_user ftp_pass If using a non-browser client, you should first login to the base, like so: https://<host>:8663/rest?ftp_user=admin&ftp_pass=coolgeek Once successfully logged in, retrieve the "JSESSIONID" Cookie. This cookie must be sent back to the server for each subsequent request. Response are formatted in JSON. 6.1 Administrator This section covers the Administrator Rest API functions. The URL to the Administrator Rest base looks like: http://<host>:8666/rest/cp/admin/... 6.2 Web Host/Reseller This section covers the Web Host/Reseller Rest API functions. The URL to the Web Host/Reseller Rest base looks like: http://<host>:8666/rest/cp/host/... In addition to the Web Host/Reseller login and executing the web host/reseller functions, the Administrator may perform the functions on behalf of the Web Host/Reseller. In this case the "reseller" parameter with the web host/reseller account name must be included in the command request. 6.2.1 Create User URI: createuser? account=ngdemo&maxmemory=512&maxcpu=60&maxapps=11&programming. language=java&programming. language=django&maxbandwidth=200&maxnodes=10&min_nodes=2&account.
Rest API 45 password=scotttiger&create=true HTTP Method: GET; POST Returns: boolean name value. e.g.: true 6.2.2 Update User URI: updateuser? account=ngdemo&maxmemory=512&maxcpu=60&maxapps=11&programming. language=java&programming.language=django HTTP Method: GET; POST Returns: boolean name value. e.g.: true 6.2.3 Clients Memory Usage 6.3 User URI: memoryusage/clients HTTP Method: GET Returns: Hash of clients and memory used (MB). e.g.: {"asmdemo":82,"rmdemo2311":382,"farver125":3} This section covers the User Rest API functions. The URL to the User Rest base looks like: http://<host>:8666/rest/cp/user/... In addition to the user login and executing the user functions, the Reseller that owns the user account as well as the Administrator may perform the functions on the user account. In this case the "account" parameter with the user account name must be included in the command request.
46 NGASI App in-the-cloud Panel 6.3.1 Deploy Application 6.3.1.1 Install The following API functions are for deploying an already uploaded application. URI: app/deploy/mysaas4? app=mysaas&database=mysql&appserver=tomcat+7.0.0; JDK6.0_20&overwritedb=true HTTP Method: GET; POST Returns: boolean (true if installation process for application with contextpath "mysaas4" starts) e.g.: true 6.3.1.2 Complete URI: app/deploy/complete/mysaas4 HTTP Method: GET Returns: boolean (true if installation process for application with contextpath "mysaas4" is completed) e.g.: true 6.3.1.3 Success URI: app/deploy/success/mysaas4 HTTP Method: GET Returns: boolean (true if installation succeeded for application with contextpath "mysaas4") e.g.: true 6.3.2 Upload Application 6.3.2.1 Install The following API functions are for uploading an application archive. URI: app/archive/install Form Parameters: account (Optional) app archive (File) programming.language
Rest API 47 datasource (Optional) sql (File) (Optional) HTTP Method: POST (multipart encoding) Returns: boolean (true if installation process for application archive starts) e.g.: true 6.3.2.2 Complete URI: app/archive/install/complete/myapp HTTP Method: GET; POST Returns: boolean (true if installation process for application archive with name "myapp" is completed) e.g.: true 6.3.2.3 Success URI: app/archive/install/success/myapp HTTP Method: GET; POST Returns: boolean (true if upload and installation succeeded for application archive with name "myapp") e.g.: true 6.3.3 Set Password URI: setpassword?new.password=coolgeek HTTP Method: GET Returns: boolean (true if password set succeeded) e.g.: true
VII
Failover 49 7 Failover Failover Strategies 7.1 Database 7.1.1 mysql Database Failover Strategies At least 1 Replicated Database must be binded to the Primary Database in order for Failover to be possible. To help keep the Databases synchronized, it is recommended the systems that the database run under be standalone - to minimize crashes and reboots which are more frequent on a shared system. NOTE: mysql Replication DOES NOT GUARANTEE data integrity between the Primary Database and any Replication server. This is because the replication mechanism is "synchronized". Which means a completed transaction on the Primary may not have completed on a Replication node prior to a failure. To safeguard against this issue, one should manually check the application database soon after a failover. By Default, NGASI App in-the-cloud Panel generates alert notifications when such events occurs. OFFLINE If working on maintenance of a Database server, such as rebooting, the Administrator should set the Offline flag in the Server Assets section of the Control Panel. This prevents triggering the failover mechanism. Replication OFFLINE If the OFFLINE asset is a Replication server, the Primary Database is set to READ- ONLY mode to ensure the replication does not get out of synch. When the OFFLINE flag is removed, READ-ONLY is removed from the Primary Server. Make sure the mysql server is running on the Replicated Server BEFORE removing the OFFLINE flag. As the change in database state (to READ-ONLY) may make some applications crash, the applications associated with the database will automatically be restarted. Primary OFFLINE If the OFFLINE asset is a Primary server, the Replication Databases is set to retry connecting to the Primary Database every 1 second to ensure the replication does not get out of
50 NGASI App in-the-cloud Panel synch. When the OFFLINE flag is removed, the connection retry timeout of the Replication Databases are reset to their defaults. Make sure the mysql server is running on the Primary Server BEFORE removing the OFFLINE flag. As the change in database state may make some applications crash, the applications associated with the database will automatically be restarted. NOTE: You may restart the Primary mysql server with the --read-only flag. Then when the OFFLINE flag is removed, READ-ONLY mode will automatically be removed. Replication Removal Sequence Several tests are done before a Replication Database is deemed out of synch and thus removed from the Replication setup. 1)NGASI is unable to connect via the REST interface. 2)The REST API indicates the Database is not running. 3)Replication to Primary tests fails (could be a network issue). 4)There are no Open Connections from the Replication to the Primary Database. 5)Replication Configuration is removed from NGASI. Failover Sequence Several tests are done before the Failover of the Primary to a Replication Database is triggered. 1)NGASI is unable to connect via the REST interface. 2)The REST API indicates the Database is not running. 3)Application Server to Primary Database tests fails (could be a network issue). FAILOVER 4)One of the Replication Databases is chosen to become the Primary Database. 5)The chosen Database is reconfigured to be the Primary Database. 6)The Primary Database for the other Replication Databases are reset to the new Primary. 7)The Database hostname (used by applications) is reconfigured to resolve to the IP Address of the new Primary Database. 8)As the change in database state may make some applications crash, the applications associated with the database will automatically be restarted. STANDALONE Primary Database If the resulting Failover results in a Standalone Primary Database (that is no Replication Server remaining), then the Database would be unavailable to new Applications. If a Replication Database is added to a Primary Database already in use by Applications, the following are the steps taken to synchronize the Replication Cluster. 1)The Primary Database is set to READ-ONLY mode. 2)The Replication Databases are configured to use the Primary Database.
Failover 51 3)Each Application Database is dumped (from the Primary). 4)Each Application Database is loaded to the Replication Databases. 5)READ-ONLY is removed from the Primary Server 6)As the change in database state may make some applications crash, the applications associated with the database will automatically be restarted. As you can see the Failover process is not exactly instantaneous, so such situations should be minimized and should be scheduled ahead of time and users should be notified in advanced. Also capacity planning is important, as adding Replication Databases to a Primary Database that already has live databases, creates momentary disruptions; i.e. Database READ-ONLY mode as the new Replication Databases are being synched.
52 NGASI App in-the-cloud Panel Endnotes 2... (after index)
Back Cover