Table of Contents
The Evolution Hosting User Manual is the place to find out what Evolution Hosting is and how it works. It describes the high-level operation of Evolution Hosting including its architecture and functionality, as well as providing low-level configuration and troubleshooting steps
Questions or information not found in the user manual can be obtained by contacting Evolution directly. Visit Evolution Hosting on the web to find full contact information or e-mail <support@evolutionhosting.com>.
Table of Contents
Evolution Hosting is a Web Hosting service that specializes in the Java programming language. It offers simplified deployment of Web sites and applications to the Internet via the myEvolution hosting control center.
myEvolution allows customers to do things like upload files, start application servers, query databases, and add e-mail accounts - all via a simple web-browser interface. myEvolution has special features that make the deployment of enterprise applications based on J2EE and Web Services simple and fast.
Evolution Hosting has been perfecting Java application deployment since 1999 and has consistently been an active member of the Java community. Evolution has served in various Java Community Process roles including the application deployment API expert group and has contributed to many of the Java related open-source projects. Much of this knowledge has been built into myEvolution providing a robust and full-featured Java hosting environment for Evolution customers.
To foster clear reading of the Evolution Hosting User Manual, it is helpful to point out a few terms that appear throughout this document. These glossary links define a brief nomenclature. Please visit the glossary for other terms not explicityly mentioned in this list.
myEvolution simplifies Java application deployment and offers control of standard hosting systems such as e-mail and DNS servers. Some of myEvolution's capabilities include: starting and stopping servers, deploying and updating applications, adding e-mail addresses, changing databases, and scheduling data backups.
Figure 3.1 illustrates an instance of the myEvolution Hosting Control Center alongside an Evolution Hosting customer account . The account has three production tiers: web, application, and database; each with one physical server. The myEvolution instance is shown with its remote agents deployed, providing constant communication between myEvolution and the production environment
Account holders access myEvolution via a web browser. Developers and even business users can manage complex environments with myEvolution rather than being forced to rely on deployment experts and system administrators. Globally dispersed groups can deploy applications as a team. Different users can simultaneously make database updates, deploy new content, and add new e-mail addresses.
myEvolution is taylored to the Java platform and offers the ability to validate WAR and EAR files, start Java Virtual Machines and provisions resources on the fly. Part II explains how to get started using myEvolution.
Table of Contents
Evolution Hosting's technical architecture provides a robust environment for enterprise websites. The environment allows for powerful application management and monitoring. It also provides the ability to move and provision new resources as accounts change and grow.
Figure 4.1 represents a high-level view of the Evolution Hosting environment. A customer account is shown along with common services, including DNS, e-mail, and backup. The account is fronted by a firewall and all servers are controlled by myEvolution agents.
Accounts can be custom provisioned to exactly match customer requirements. Either shared or dedicated platforms can be requested by account holders to best fit budgetary and performance needs.
Evolution Hosting's technical architecture is designed for reliability and manageability. The environment provides monitoring, application management, resource provisioning, and automated corrective action capabilities to all accounts.
Figure 4.2 illustrates a typical Evolution Hosting account setup with the myEvolution hosting control center.
A major feature of the architecture shown in Figure 4.2 is the separation of the management area from the production servers. myEvolution has all of the information it needs to recreate any of the production tiers on new physical servers in the event of a catastrophic failure . The net result is increased reliability for Evolution Hosting customers.
Account holders use their myEvolution to deploy applications to a working area. From this location, the application needs to be pushed out to the account's live production servers. Content is pushed using a publish process.
The Publish process is more correctly a synchronization process due to the fact that content can move both directions between myEvolution and the production environment. When the same content exists in both places, the one with the most recent modified date is used as current. The current content item is then copied to the opposite server, overwriting old content in the process.
Figure 4.3 illustrates the publish process pushing files out to a live customer account.
The recommended method of moving content to Evolution accounts is first to upload content to the myEvolution hosting control center and then to Publish it to the production environment.
There is an optional Direct Upload process that account holders can use to push content directly to production environments. The Direct Upload eliminates the extra step of clicking the publish button in myEvolution.
The advantage to using Publish versus the Direct Upload method is that there is an instant backup of content in the myEvolution control center. If an account holder wishes to switch between shared and dedicated packages, or if an error occurs in the current physical server, the entire account can be immediately restored to a new server.
Content placed directly into the production environment via Direct Upload will be synchronized to myEvolution only after a Publish command is given or when one of the servers is restarted by the account holder from inside myEvolution.
Instructions on executing the publish command are available in the section called “Publish”.
Table of Contents
In the event that a catastrophic failure occurs in an Evolution account's application or database, Evolution has put in place a comprehensive set of technologies and procedures that allow a quick and complete recovery. This system consists of hardware, software, and remote storage appliances that provide for the backup, analysis, and restoration of an account.
Evolution's disaster recovery system allows for either coarse or fine-grained restoration. Backups and Evolution Administration tools can be used to recreate an individual user's mailbox or an entire database server. The overall suite of disaster recovery procedures translate into increased uptime and reliability for account holders.
The details below are a minimum feature set that every Evolution account has. Dedicated hosting has additional options above and beyond the list below. This may include changes to the frequency of backups, application or server clustering, and other recovery measures that an account holder may wish to implement. Please contact <sales@evolutionhosting.com>. to discuss specific needs in further detail.
The Evolution hosting platform is built from the ground up with redundancy in mind. Some examples of this include:
Redundancy Examples
Multiple Internet data connecitons to tier 1 providers
All account configurations stored in databases
Replication based site-publish architecture allows for dynamic account moves or restorations.
Redundant central infrastructure such as DNS and mail servers
Advanced monitoring of systems in all respects, both at the central infrastructure and individual account level.
Evolution Hosting has built its systems to continue functioning in the event of a catastrophic failure.
Evolution maintains hot-standby servers that are preconfigured with the myEvolution hosting environment and remote agent. Should an account's server become unusable, Evolution staff can use a myEvolution administration console to dynamically move the account from the corrupt server to a new hot-standby server. This feature is automated and takes only a matter of seconds.
RAID stands for "Redundant Array of Independant Disks". RAID allows a server to continue functioning if one or more hard disks fail. Each server in the Evolution environment has RAID and therefore has increased reliability at the disk-hardware level.
This section contains information on each type of backup that Evolution monitors and runs for account holders. One important metric with regard to backups is the frequency with which they run. Table 5.1 illustrates the schedule on which Evolution backup tasks occur.
Table 5.1. Backup Frequency Summary Chart
| Backup Frequency Table | |||||||
|---|---|---|---|---|---|---|---|
| Backup Type | Default Frequency | Is User Configurable | End-Location | Downloadable | |||
| Shared | Dedicated | Shared | Dedicated | Shared | Dedicated | ||
| Files and Content | Daily | Yes | Yes | Storage Area Network (SAN) | SAN | Yes | Yes |
| Database Data | Daily | Yes | Yes | SAN | SAN | Yes | Yes |
| Full Database Schema and Content | Weekly | No | Yes | SAN | SAN | No | Yes |
| Configuration | Upon Publish or Server Restart* | No | No | myEvolution Database | myEvolution Database | Yes | Yes |
| Content | Upon Publish or Server Restart* | No | No | myEvolution Server | myEvolution Server | Yes | Yes |
| Daily | No | Yes | SAN | SAN | No | Yes | |
| Server | Weekly | No | Yes | SAN | SAN | No | No |
| Off-Site | Monthly | No | Yes | Geo Remote SAN | Geo Remote SAN | No | Yes |
* Configuration changes and content are synchronized between a myEvolution Server and the Customer Application Server.
Each account's entire directory tree, including all of its files and content, is backed up daily to a remote SAN.
Database data is exported and moved to a remote SAN on a daily basis. These daily backups include only data and do not include database schema information (e.g. table definitions, stored procedures, etc.). Evolution recommends customers always maintain a current DDL set used to create and recreate databases. Full database backups, including schema information, are included in database backups.
Account holders may schedule and access Evolution data backups at any time from within myEvolution. This backup can be downloaded by the account holder via FTP or web browser (secure download via SSL is also available).
All databases in the Evolution hosting environment are fully backed up once per week and saved to a SAN. This includes both schema information and data. In the event of a database failure, the backups are quickly restored to a hot-standby database server.
In the Evolution environment, all application configuration settings are stored in a myEvolution database. myEvolution Database instances are located in a separate location from application server production environments. In the event of a failure with the application's configuration, this environment may be dynamically recreated to the existing production deployment server, or it may be dynamically recreated to an entirely different hot-standby server.
In the Evolution environment, all web and application content is backed up via the myEvolution replication feature. When content is uploaded, it is placed in a myEvolution server. This content remains on the myEvolution server until it is published to its respective production deployment server, where the application runs. In this way, the current content set is always in two places. Should the production deployment server experience problems, the entire application can be immediately published to a new hot-standby server.
Evolution e-mail accounts are backed up daily and saved to a SAN. These backups can be used to recreate an account's entire mailbox structure, including all folders and messages. Should a single mailbox become corrupted, Evolution staff can also use these backups to restore an individual account.
All servers in the Evolution environment are backed up on a regular schedule to a SAN. These backups ensure that in the event other restoration steps fail, the server itself, with all of its data, can be restored to a new platform.
Table of Contents
Evolution has created a number of tutorials to assist account holders with the development, testing, and deployment of applications to myEvolution. The tutorials are one of the cornerstones in the Evolution Hosting system and it is highly recommended that each account holder download and take advantage of the tutorial that corresponds to his or her account.
The tutorials generally correspond to a particular application server. As vendors release new application server versions, Evolution staff update or create new tutorials to best fit the new offering.
Although each tutorial is different, they all are based on the same design and have similar layers of functionality. These layers are discussed in the next section.
To understand how the turorials work from a high-level, the tutorials can be divided into layers. Each layer has a different purpose:
Tutorial Layers
Layer 1: OS/Environment Layer
A base-level environment layer that investigates the local computer to find out things like the OS version, location of the JDK, etc. This layer is used by other layers that need access to various resources. This level is written in Perl to take advantage of its excellent file and command line capabilities. The main file driving this layer is /bin/library.pl. Take a look at this file to adjust where the tutorial should look for your JDK and what information it should use to connect to your local database, etc.
Layer 2: Compile/Build Layer
A Java-Ant based compile-build environment that controls the main tasks that the tutorial can perform. This layer uses settings and information from the OS Layer to do things like start and stop the server, compile all classes, build a WAR file, and more. All of these tasks are built in Ant "targets" and can be viewed and modified in the file /bin/verge.xml.input.
Layer 3: Application
The application layer refers to the actual Web application that contains the example code for the particular tutorial. In the Odin tutorial, for instance, a number of Java classes, Servlets and JSP's are provided that demonstrate features such as the Orion security UserManager. Full source code is provided. Look for this code in the /src/, /vroot/html/, and /war/warname/ directories.
| Evolution Tutorial Contents | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| Aligo | Bossman | Cheetah | Deity | Anubis6 | Anubis7 | Khufu | Odin | Sphinx | |
| Build/Compile/Run Environment | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
Building and Deploying EAR's | No | Yes | Yes | No | No | No | No | Yes | No |
Building and Deploying WAR's | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | |
| No | Yes | No | Yes | Yes | Yes | No | Yes | No | |
| No | Yes | No | Yes | Yes | Yes | No | Yes | No | |
| Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | |
| Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | |
| No | Yes | No | Yes | Yes | Yes | No | Yes | No | |
| No | Yes | No | No | No | No | No | No | No | |
| No | Yes | No | Yes | Yes | Yes | No | Yes | No | |
| No | Yes | No | Yes | Yes | Yes | No | Yes | No | |
| No | Yes | No | Yes | Yes | Yes | No | Yes | No | |
Wireless Concepts | Yes | No | No | No | No | No | No | No | No |
Uploading Files | No | No | Yes | No | No | No | No | No | Yes |
Securing via JDBC Realm | No | No | Yes | No | No | No | No | Yes | Yes |
| Loading Property Resources | No | No | Yes | No | No | No | No | No | Yes |
| Processing Credit Cards | No | No | Yes | No | Yes | Yes | No | No | Yes |
Sending E-Mail with JavaMail | Yes | Yes | Yes | Yes | Yes | Yes | No | No | Yes |
| Example Discussion Forum | No | No | No | No | No | No | No | No | No |
Download the Aligo RestaurantGuide here.
Download Bossman here.
Download Cheetah here.
Download Deity here.
Download Anubis6 here.
Download Anubis7 here.
Download Odin here.
Download Sphinx here.
Contact <support@evolutionhosting.com> for Khufu.
Contact <support@evolutionhosting.com> for Horeb.
Table of Contents
Note: please also read the Domain Parking section of this manual for more information related to domains, URL's, and IP addresses.
The Domain Name System (DNS) is a physical address lookup utility that has evolved as a core piece of the Internet's operation. The DNS allows Internet addresses in mnemonic form such as www.companyx.com to be resolved into a corresponding numeric IP address such as 134.220.4.1 . It is this numeric address that allows computers to locate one another.
To ensure that addresses are not changed by anyone but the registered owner, the DNS requires that addresses be changed through a Registrar. Evolution takes care of a majority of DNS configuration, but the Registrar changes must be done by the customer.
This section of the Evolution manual explains when and how to change DNS settings so that Evolution accounts can be located on the Internet.
When any account is signed up via the Evolution Hosting automated signup process, two (2) domains are instantly set up within the Evolution DNS infrastructure. Evolution calls these domains the primary domain and the auxillary domain.
The primary domain will usually be the domain customers use to access the site. It will not be available, however, until the account holder completes the DNS Server Name Change process with their Registrar. Prior to the DNS change, the auxillary domain is used by the customer for immediate access after signup and for initial testing. In the following example a primary domain and auxillary domain are listed. Note that the auxillary domain is simply the primary domain with .evohst.org appended to the end of it.
Example Domain Set
Type: Primary Domain
Example URL: www.companyx.com
Derived From: Entered by customer during account signup
Use: Used by site visitors
Available: Only after account holder updates DNS settings with their registrar
Notes: Evolution accepts all valid domain names, including International domains
Type: Auxillary Domain
Example URL: www.companyx.com.evohst.org
Derived From: Created by myEvolution by appending .evohst.org to the primary domain.
Use: Used by Evolution staff and account holders
Available: Available immdeiately after account signup
Notes: The auxillary domain is not valid for e-mail address use - it is intended for web browser use only.
The primary domain is not available for use until the account holder changes the Internet's central DNS records. This change causes the Internet's global DNS system to point to the Evolution DNS subsystem. The end result is that when a URL is typed into a web-browser anywhere on the Internet, the browser will successfully find the Evolution hosted web site.
The Internet's DNS system has a time lag of up to 72 hours (three days) in propogating DNS updates to all DNS servers around the world. In cases where a previously existing site is active, it is advisable to keep both the previous site and the new Evolution site live during the 72 hour transition period. If the previous site is turned off before 72 hours has passed some customers may still be sent to the old site and receive an error.
Evolution has two (2) DNS servers that must be communicated to registrars for each new Evolution account. Please note that Evolution servers should not be used by your own network. Please be sure and use the DNS servers provided by your local internet access provider.
Table 7.1. Primary and secondary DNS server
| Evolution DNS servers | |
|---|---|
| dns1.evolutionhosting.com | |
| dns2.evolutionhosting.com | |
The two subsections that follow give step-by-step instructions for updating DNS records with a few of the Intenet's leading registrars.
BulkRegister is Evolution's recommended Registrar due to its excellent web-based administrative tools. There aren't any instructions for BulkRegister at this time, partly because of the simplicity of their site. Note there is a minimum fee for signup.
Evolution's second choice in registrars is Register.com.
Register.com Update Instructions
Browse to the Register.com website.
Click on the Manage My Account link and login.
Select Modify DNS.
Replace all existing names with the two DNS names as listed in Table 7.1. Click Yes. to proceed.
Validate the changes and click Yes to confirm.
An e-mail will be sent to the registered contacts with a confirmation URL that must be clicked on. Check mail on the registered address and follow the instructions to verify the changes.
The updated domain registration will take up to seventy-two (72) hours to propagate throughout the Internet.
Network Solutions was the first registrar on the Internet and as a result it currently maintains the largest amount of domains. Evolution, however, recommends against Network Solutions due to their extremely difficult change procedures.
Network Solutions Update Instructions
Browse to the Network Solutions website.
Click on Manage Account.
If the domain has an account number or login then login to the admin site. Older domains may not have an account number or login so the second method must be used: Enter the domain name to manage and click 'Go'.
Select the form: I want to transfer my domain name to another ISP and then click Go.
Enter an active e-mail address that matches the one Network Solutions has on file for the administrative or technical contact for this domain name (help is available on the web page). Enter the domain name of the site to change and click Go. Note that if the account holder has set up another security method, such as userid / password (CRYPT-PW), then that is the authentication method that should be used.
Change the host name and address form fields to match those given in Table 7.1. The primary and secondary DNS servers should be the only host names listed.
Click on Submit this form for processing.
For the e-mail address that was used above, check mail for the Modify Domain Form from Network Solutions and verify the changes are correct.
Reply to the e-mail to begin the update process. Note that the e-mail must be sent from the e-mail address that Network Solutions recognizes as being authorized for the domain. Also note again that if another another security method was previously set up, such as userid / password (CRYPT- PW), then that is the authentication method that must be used.
Once accepted by Network Solutions the updated domain registration will take up to seventy-two (72) hours to propagate throughout the Internet.
Table of Contents
A standard myEvolution account will have a single domain name that points to a single set of content. Some accounts, however, require multiple domain names and have multiple sets of content that correspond to the different names. Domain Parking is the term that Evolution uses to describe the process of working with more than one domain name in the context of a single account.
An example of domain parking is as follows: Company X may have a primary domain name of www.companyx.com, but may have another domain name of internal.companyx.com and require that they point to two different applications within their account. Using properties within myEvolution, account holders may set up their account to forward requests for www.companyx.com to one set of application content, while requests bound for internal.companyx.com are forwarded to a second set of application content.
Note: please also read the DNS section of this manual for more information related to domains, URL's, and IP addresses.
The following sections illustrate various domain parking scenarios, explaining both when they should be used, and how to configure them.
If an account holder is changing domain names (zones), from, for example, companyx.com to newcompany.com, myEvolution will automatically create the appropriate e-mail, DNS, and application server entries. The two domains behave and respond identically so that site visitors experience a smooth and uneventfull name change.
Note that the the account will still be listed under the primary domain name in myEvolution for consistency.
Using domain parking, one myEvolution account can answer correctly for more than one domain name. This parking scenario is accomplished by adding the additional names as described in ejip.domain.parking.zones, for situations requiring entirely new zones; or in ejip.domain.parking.subdomains, for situations requiring only new subdomains. Visit the above links for instructions on how to update the myEvolution properties.
When accounts require a many-to-many relationship between domain names and applications, this is the scenario that should utilized. This technique is used when different domain names must be routed to different content sets. Table 8.1. illustrates this scenario:
Table 8.1. Configured to Point to Different Applications Within an Account
| Example Parking Scheme | |
|---|---|
| Incoming Request Domain Name | Intended Destination Domain Name |
| http://www.companyx.com | http://www.companyx.com/mainsite/ |
| http://guest.companyx.com | http://guest.companyx.com/guestsite/ |
| http://www.companyz.com | http://www.companyz.com/companyzsite/ |
In the above example set, there are three content sets:
These contexts may be implemented by an account holder as separate JSP pages or as separate WAR's. For the detailed example below, we will demonstrate the JSP page setup.
Steps to set up Multiple Domains and Content Sets
Obtain the Domain Names
Follow the steps in Chapter 7 to register and point the required domain names to Evolution Hosting's DNS servers. In this example, the domains that would require registration are companyx.com and companyz.com. The domain with guest in its name is only a subdomain of companyx.com and is therefore covered in the companyx.com registration.
Set the myEvolution Domain Parking Properties
Assuming domains companyx.com and companyz.com are now active, and assuming that companyx.com is the primary domain name for the account, add:
companyz.com
to ejip.domain.parking.zones, and add:
quest.
Create Content Directories
In the root content area (depending on the account, this is most likely under the Default Web App) create the context subdirectories as listed:
Place the content for each domain entirely within its respective subdirectory.
Create Main index.jsp Page With Redirection Logic
In the same directory that the above subdirectories were created, creata a top-level index.jsp page and add Java code similar to the following pseudo code:
For precise code, see helloWorld.jsp located in the section called “Cheetah (Apache Tomcat 4.x)”.
String serverName = null ;
String proxyName = null ;
// when using Apache ProxyPass must check Via header
//ProxyVia on
//Inserts Via: 1.1 www.myserver.com in the header so programs can use real server name
// 1.1 == http version sent by the browser
// www.myserver.com == Host header sent by the browser
proxyName = request.getHeader("Via") ;
if (null != proxyName) {
//with ProxyPass
int index = proxyName.indexOf(' ') ;
if (-1 < index) {
serverName = proxyName.substring(index+1) ;
}
} else {
serverName = request.getServerName() ;
if (80 != request.getServerPort() && 0 != request.getServerPort() && 443 != request.getServerPort()) {
serverName += ":" + Integer.toString(request.getServerPort(),10) ;
}
}
System.out.println("Server name (and possibly :port) is: " + serverName) ;
if (serverName.equalsIgnoreCase("www.companyx.com")) {
response.sendRedirect("http://www.companyx.com/mainsite") ;
} else if (serverName.equalsIgnoreCase("guest.companyx.com")) {
response.sendRedirect("http://guest.companyx.com/guestsite") ;
} else if (serverName.equalsIgnoreCase("www.companyz.com")) {
response.sendRedirect("http://www.companyz.com/companyzsite") ;
} else {
System.out.println("Error, serverName " + serverName + " has not been redirected.") ;
}
Create Welcome pages for Subdirectories
Create simple welcome index.jsp pages in each subdirectory. All myEvolution ccounts are initially configured to redirect to a page titled index.jsp when no file is explicitly specified in a url, so the redirects in the step above will eventually resolve to these welcome pages.
In summary, when a site visitor enters guest.companyx.com into their browser, they will see guest.companyx.com/guestsite/ in their browser's address bar and see the content in the /guestsite/ directory. With this technique account holders may host multiple domains within one account. A more robust, but more complicated, method is to create three webapps (e.g. mainsite.war, guestsite.war, and companyzsite.war). Webapps have the advantage of separate classpaths so that classes of the same name do not conflict. There are many more advantages to webapps not covered here.
Note that since Evolution already uses virtual hosting in the shared environment it is not possible to nest virtual hosting within an account.
Account Holders have complete control over MX (mail exchange) records in myEvolution. Account Holders may use Evolution mail servers or change the MX records to point to their own external mail servers. Mail exchange settings are set in the myEvolution ejip.server.mail.mx and ejip.server.mail.mx2 properties.
Account Holders have complete control over additions to DNS zone files. Via myEvolution, account holders may add ejip.domain.parking.arecord and ejip.domain.parking.cname records at any time.
Some account holders prefer to maintain their own DNS servers. Evolution can accomodate this request while still managing everything else. Account holders need only modify the ejip.domain.parking.externaldns myEvolution property to indicate this preference.
An Evolution Account may exist on multiple physical servers, or may be moved at anytime in the event of a system failure. In order to help applications remain portable, Evolution sets Java system properties in each account. These system properties enable applications to do things like find their root file directory. System properties are set into each account's JVM at application startup. This allows developers to execute commands such as
String myAppHome = System.getProperty("app.home") ;
from within their program. Once retrieved, file properties are used to set the base path in file operations.
To view exactly which properties are in their account, account holders can login to myEvolution and go to the Server | Logs | Startup Log section. Here, properties are shown exactly as they are entered into the JVM in the form
-D[name]=[value]
The example property above is set with this entry: -Dapp.home=/home/vhost1/www.companyx.com/
Applications deployed into Evolution Hosting accounts should use the provided System Properties when working with files and directories. A full explanation of working with these properties is provided in Chapter 9.
Two examples of directory related system properties are app.home and app.data. See the Table 8 for a complete list.
In this section, Evolution illustrates its standard account directory structure to help account holders understand where their files are kept after upload to myEvolution. This entire directory structure is replicated for every account, although slight variations may exist based on application server type and version. Further, this structure exists both on the myEvolution server and on the Application Server at the same time, and is periodically synchronized as explained in the section called “The Publish Process”.
+---bin <-- ** Server build/start/stop scripts
+---conf <-- ** Configuration files for the application server
+---dynamic <-- ** Working directory used by application server
+---lib <-- ** Required Java Class Jar files - registered directly in JVM's classpath
+---log <-- * Application server logs
+---mail <-- ** IMAP mailboxes
+---vroot
+---data <-- * Simple storage of miscellaneous files by account holder
+---database
+---backup <-- ** Database data backups
+---export <-- ** Database data exports
+---import <-- ** Temporary upload area for CSV data files to be imported
+---html
+---ejip <-- * Used by myEvolution in application monitoring
+---images <-- * Served directly by Apache WS to optimize performance
+---WEB-INF <-- * Default-Web-App Config Files (e.g., web.xml)
+---classes <-- * Java Classes for use by Default-Web-App
+---lib <-- * Java Class Jar files for use by Default-Web-App
+---j2ee <-- * EAR or WAR files
+---lib <-- * Jar files, property files, etc. - registered directly in JVM's classpath
+---log <-- * Apache access log directory
KEY:
* = Fully accessible/viewable by account holder through myEvolution
** = Only indirecly accessible by account holder through myEvolution configuration settings
The Secure Sockets Layer (SSL) is a commonly-used protocol for managing the security of a message transmission on the Internet. Account holders who require transimission security on their site for tasks such as credit-card processing may set up SSL encryption by purchasing an encryption key from any of the industry recognized vendors. Once purchased, the user's site is updated with the key and SSL-enabled.
To simplify the background check that certificate issuers perform on anyone wishing to obtain a certificate, Evolution recommends that customers first obtain a Dunn and Bradstreet® (D-U-N-S Number) number before requesting a certificate. The D-U-N-S Number is a nine-digit identification sequence, which provides unique identifiers of single business entities, while linking corporate family structures together. The SSL Certificate Authorities (E.g., Thawte® or Verisign®), who authorize SSL Certificates, use D-U- N-S numbers to make certain that certificate requests are valid and not fraudulent.
Note that the D-U-N-S number should correspond to the owner of the URL that the certificate will serve. For example, if a certificate is being requested for www.CustomYachts.com, attempting to use a D-U-N-S number for Great Java Programmers, Inc. may be rejected by the Certificate Authority. Rather a D-U-N-S number for Custom Yachts, Inc. would be preferable.
Typically, the process to set up SSL in an Evolution account proceeds as follows:
SSL Setup Steps
Following their registrar's instructions, the account holder first updates domain name contact (WHOIS) information to make certain it is exactly correct and current. Registrars demand that the WHOIS information match that of the certificate request precisely.
Account holder sends Evolution technical staff the D-U-N-S number, exact contact information, and the requested SSL URL. Evolution verifies this information using a WHOIS query.
Evolution generates an initial certificate and requests a signed certificate from the Certificate Authority using the provided D-U-N-S number.
Account holder works with the Certificate Authority to verify their identity.
Certificate Authority generates final certificate and Evolution installs it on the production server.
Evolution Hosting fully supports e-commerce applications and offers a range of solutions to help account holders accept payments from their customers.
Summary of Evolution Hosting Credit Card processing options
Third Party Dynamic URL
Customer dynamically creates simple URL's with vendor ID and order items
Account holder does not need to store credit card numbers or build billing system
No SSL Certificate Required
Verisign/CyberCash API
Full Java API for processing credit card transactions.
Account holder has more control over billing system.
OfBiz Full Blown Java Shopping Cart and Commerce System
Use of Evolution Hositng custom CyberCash API
Requires standard credit card merchant account at a bank
Custom Billing
Evolution Hositng installs third-party software
Evolution Hositng supports third-party software
The most basic form of commerce integration that an account may choose is to frame-in a third-party processor. Under this option an Evolution account creates an HTML frame on their order processing page and loads an external web page. The external page is managed by the third-party and the Evolution account holder need only ensure that the proper order and account paramaters are passed in the frame's url string. This option is by far the simplest way to add purchasing to a web site, because it eliminates custom programming and the requirement for a merchant-account (the third-party provides a shared merchant account).
Another options allows Evolution account holders to develop or integrate custom payment processing systems. Evolution supports account holders in this task by modifying firewall rules to allow interaction with external payment gateways.
For programmatic payment processing, Evolution Customers may choose to integrate with Cybercash , the Internet's leading credit card processing company. Evolution has fully integrated the Cybercash payment gateway into its environment via a custom Java API. This API provides the ability to securly process credit card transactions when combined with a credit card merchant account, as is required by Cybercash.
The final e-commerce option, Custom Payment Processing, allows Evolution Hositng customers to supply special software to Evolution Hositng for installation and configuration. Contact Evolution sales for more information.
Table of Contents
Table of Contents
A high-level description of myEvolution can be found in Chapter 3. This chapter explains basic operating procedures for myEvolution such as logging in, finding help, and signing off.
Account holders sign into myEvolution via the login page. A username and password are required. If an account holder misplaces their username or password, they may use the reminder feature on the same page to have login credentials e-mailed to the account's primary contact.
Account Holders access the various sections in myEvolution by clicking on the primary and secondary navigation links at the top of the page. These links utilize JavaScript and HTML Frames to optimize performance. The primary navigation links (top row) dictate what is displayed in the secondary links (bottom row). For example, once the database tab is clicked on, the bottom row of links is updated to display the SQL Tab, the Import Tab, etc.
The Server Control is located in the upper right corner of myEvolution and is used to control the life cycle of an account's application server.
Stages of the Server Control (color coded)
Stopped (Red)
The application server and its JVM are not running.
Starting (Yellow)
The application server and its JVM are in the process of coming online, but are not yet running.
Running (Green)
The application server and its JVM are started and capable of fielding incoming requests.
To start, stop, or restart an account's application server the Server Control Buttons are used.
Server Control Buttons
Start (Left Side)
Starts an account's application server. If the server is currently Running, the Start button will Restart the server (the server does not have to first be Stopped).
Status (Middle)
Indicates the current state of an account's application server.
Stop (Right Side)
Stops an account's application server.
myEvolution has context-sensitive help in every section Help appears to the right of the navigation links and contains both a section description and a link to the user manual for more information. For additional help, the Support section of myEvolution contains links to the user manual, Evolution Support contact form, and priority electronic paging system.
Table of Contents
The Deploy Section of the myEvolution Hosting Control Center is one of the most frequently accessed areas in the Evolution environment. From Deploy, account holders can upload new application content, validate EAR's or WAR's, and Publish applications.
For a quick-start to deploying applications to myEvolution, skip ahead.
A majority of the Deploy section is devoted to uploading files to directories in the Evolution environment. It is helpful to view Chapter 11 for reference on the underlying directory structure behind the various myEvolution Deploy sections. Account holders should also read the Publish section before working in the Deploy section to understand the underlying architecture of myEvolution and its method of delivering applications to production servers.
The remainder of this chapter explains the Deploy subsections in detail.
This section gives tips and abridged deployment instructions to deploy a J2EE WAR into the Evolution environment.
Log into myEvolution and navigate to the DefaultWebApp section. From there, click on the directory named ejip and examine the file named monitor0.jsp. This file is configured and included with all accounts and is used for monitoring. It demonstrates how to get a connection to a database using J2EE DataSources.
While still in the DefaultWebApp section, click on the WEB-INF directory and examine the web.xml file. This is a standard WAR configuration file, but it shows entries tailored for myEvolution.
Any standard J2EE WAR file can be deployed to Evolution. Use the examples in Step 1 as a guide to make any necessary changes to database code and the WAR file's web.xml configuration file.
Package the WAR normally using a command similar to the JAR command. Note that the /WEB-INF/web.xml WAR configuration file may be included, or the default that is already created in the account's DefaultWebApp section may be used.
The WAR may be uploaded into either the DefaultWebApp section, or the EAR's, WAR's, Etc. section. Read each section to find out which method is best for the account and then follow the instructions to deploy. In general, the DefaultWebApp technique is the preferred method for a single WAR, whereas multiple WAR's can be deployed in the EAR's, WAR's, Etc. section.
The application server and deployed application should now be running. The web server, application server, and database server can be tested by accessing the monitor page. If the account's Auxillary Domain were www.companyx.com.evohst.org , the monitor page could be checked at the auxillary url http://www.companyx.com.evohst.org/ejip/monitor0.jsp. If the WAR was deployed in the EAR's, WAR's, Etc. section and was named WARB, it could be checked at http://www.companyx.com.evohst.org/WARB/.
There are multiple ways to deploy J2EE applications in myEvolution. The various techniques map to supported deployment approaches in each application server vendor's deployment implementation. The following table lists the techniques supported by each vendor platform.
Table 15.1. J2EE Application Deployment Matrix
| J2EE Application Deployment Matrix | |||||
|---|---|---|---|---|---|
| DefaultWebApp | EAR's, WAR's, Etc. | ||||
| WAR | EAR | SAR | Service Definition | ||
| JBoss 3.0 | Yes | Yes | Yes | Yes | Yes |
| Oracle 9iAS | Yes | Yes* | Yes | No | No |
| Orion 1.5.x | Yes | Yes* | Yes | No | No |
| Tomcat 3.x | Yes | Yes | No | No | No |
| Tomcat 4.x | Yes | Yes | No | No | No |
| WebLogic 5.x | Yes | Yes | No | No | No |
| WebLogic 6.x | Yes | Yes | Yes | No | No |
| WebLogic 7.x | Yes | Yes | Yes | No | No |
* WAR files may be deployed in these servers by first packaging them in an EAR.
All vendor platforms accept the deployment of Java Classes. These classes should either be deployed within the above mentioned applications (such as in a WAR's WEB-INF/lib/ directory), or via the JAR's Section of the myEvolution deployment area. Deploying a JAR file to the JAR's Section will automatically add it to the JVM's. -classpath setting.
This section of myEvolution is where simple HTML pages and images are generally deployed. Although the DefaultWebApp is technically a J2EE WAR file, it can be used as a simple web site deployment directory by non-java-experts. Just upload an HTML page, click publish, and the new content will be live.
The DefaultWebApp is simply an exploded WAR file. Instead of keeping all of the WAR's content inside of a single file, it is exploded or extracted so that all of the files are more easily accessible. Evolution account holders may deploy one (1) WAR in this fashion, additional WAR's must be deployed as explained in the WAR Section.
Although the concept of a DefaultWebApp is not part of the Sun J2EE Specification, it is implemented by most J2EE application server vendors as an alternative to deploying via a WAR file, which bundles an application's contents into a single file. The primary advantage of a DefaultWebApp deployment is the ease with which individual files may be updated in a deployed application.
Steps to Deploy to the DefaultWebApp
Upload Content
Files may be uploaded individually, as an archive (e.g., Zip file), or as a full WAR file. To upload, click on the File button, select the file on the local PC, then click upload. Be sure to click Overwrite if there is already a file with the same name.
Extract Content
If a Zip, JAR, or WAR file was uploaded, they must be extracted by clicking on the uploaded file and then clicking the Unjar link in the lower pane of the browser.
Publish Content
In order to become part of the live site the content must be transferred to the production server. Follow the instructions in the publish section to move the files. Note that if the server is to be restarted, Publish can be skipped, because it is executed upon server restart.
Start the Server
If the server is not running, it must be started. The Server Control section explains how to start the server.
Check the Startup Log for messages
Consult the Startup Log to read deployment messages.
EAR's and WAR's are the prescribed deployment medium of the J2EE specification. They are complete web applications contained in a single file.
SAR's, and Service Definitions's are deployment mediums specific to the JBoss application server.
The recommended (best practice) in deploying an application via the EAR's, WAR's, Etc. Section of myEvolution is as follows:
Steps to Deploy to the EAR's, WAR's, Etc. Section
Upload
Upload the EAR, WAR, SAR, or Service Descriptor file to the EAR's, WAR's, Etc. Section.
Validate
Click on the file and view validation messages in the lower pane of the browser.
Start (or Restart) the Server
Click on the Server Control's Start button.
Check the Startup Log for messages
Consult the Startup Log to read deployment messages.
The JAR's section of myEvolution allows multiple Java Classes to be deployed in aggregated form.
To deploy JAR files to myEvolution:
Steps to Deploy JAR's
Upload
Upload the JAR file to the JAR's Section of myEvolution.
Start (or Restart) the Server
Click on the Server Control's Start button.
The Classes contained in the uploaded JAR files are automatically added to the Classpath of the pertinent Classloader(s) for the account. Exact classpath settings for an application can be viewed in the section called “Startup Log”. Account holders should note that myEvolution includes all core classes required by various application servers and these files should not be uploaded into the JAR's Section or ClassCastExceptions may result.
The Data Section can be accessed by applications and is specially configured to not be accessible via site visitor's web browsers. An example use for this tab would be to store signup confirmation files generated by an application. The files could later be downloaded via the Data Section for review. To see how applications access the Data directory and related properties see Chapter 9
The FTP Section contains reference information and credentials explaining how to transfer files to and from an account via FTP. Figure 4.3 illustrates FTP upload options.
The Publish Section has one link, which activates the Publish routine for an account. Read more about Publish in the section called “The Publish Process”.
Table of Contents
The Server section of the myEvolution Hosting Control Center contains logs and property information related to an account's servers and other resources such as DNS.
The logs section should be consulted frequently by account holders to check server startup results and application output.
Contains vital information related to the application server startup such as classpath settings, J2EE deployment information, and summary success or failure messages.
Access to the Webalizer reporting suite as described in Chapter 24. To view the Webalizer reports, simply click on the link for this section.
The properties section contains server properties and other settings for various aspects of the Evolution Hosting environment. A description of all properties can be found in myEvolution Properties Glossary.
Evolution utilzes the industry leading Apache Web Server to optimize the performance of every account. Apache is used for Virtual Hosting and to directly serve certain files, bypassing the JSP/Servlet Engine, in order to optimize performance. Content in the /images/ directory in each account's Default-Web-App, for example, is served directly by Apache.
For information on working with application servers within myEvolution accounts, please see Chapter 6.
Table of Contents
Each Evolution Hosting account has at least one database. Evolution databases are primarily used by an account's Java application, but may also be used by other applications (e.g., cgi-bin). This section provides information on the general setup and management of databases, as well as instructions on how to connect to a database from within an Evolution hosted Java application.
For answers to frequently asked questions, visit the Evolution Hosting Databases.
Each account's database tablespace is created automatically by the myEvolution Hosting Control Center upon account signup and is immediately ready for use. Account holders do not have to do anything extra related to the tablespace and can immediately begin creating the database schema.
It is worthy to note that the term database actually refers to a software application that can contain multiple tablespaces. Evolution Accounts each have at least one tablespace, but may share a database. The term database may be used in place of tablespace, because of its common understanding.
The database schema is the unique definition of an account's database structure. The schema is created via the myEvolution database tab using SQL statements.
The databases that Evolution Hosting offer fully support the SQL standard, in addition to offering proprietary extensions to do special tasks. Vendor specific documentation should be consulted for information on a particular vendor's SQL implementation.
Evolution Hosting recommends that account holders maintain a full set of SQL scripts (sometimes referred to as DDL) to create, recreate, or modify the account's database schema at any time. Ideally, these scripts should be maintained in a code versioning system, such as CVS.
Evolution Hosting provides tutorials, modifiable account properties, preconfigured application server setttings, and other tools to assist account holders in connecting to their database from Java applications. This section explains these tools in detail.
The first stop for account holders investigating how to connect to their database should be the Evolution tutorials. These are fully functioning Java applications that demonstrate concepts such as JDBC access from a Servlet, and updating records from a Bean Managed Entity Bean. Account holders should read Chapter 6. and examine the tutorial that corresponds to their account type.
Access to all Evolution databases is accomplished via Java DataSources. Datasources are a Java standard for obtaining a JDBC connection to a database in a generic fashion. At startup, the application server registers a DataSource in JNDI. The JNDI name is application server-specific. However, to remain portable, J2EE defined 'resource-references' for use in application source code. The database property, ejip.datasource.name, refers to the application server's JNDI name. This property value can be changed to rename the datasource, but must comply with the naming conventions imposed by the account's application server JNDI Namespace.
Resource-references are mapped to the application server-specific DataSource name in JNDI. There are two ways to get a handle to a DataSource in an application server.
Through the application server-specific JNDI name (non-portable, not advised). These do not require a "java:comp/env" lookup into the InitialContext.
Through resource-references (portable, advised) in code and deployment descriptors. These use the "java:comp/env" prefix for lookup into the InitialContext.
The following details the steps required for database access from a JSP or Servlet via DataSources. Details for setting up EJB access to DataSources is similar, but use different deployment descriptors. Container-managed Entity Beans would not require these steps, but Bean-managed Entities and Session Beans using JDBC will need to define resource references similar to web applications.
Setting up an Application to Use Datasources
Register the desired name for the Datasource with myEvolution.
Modify the myEvolution property ejip.datasource.name as desired
This property represents the application server's JNDI name of the DataSource. It is NOT the JNDI name you use in your application code. Since it is application server specific, it must follow the JNDI naming conventions of the server. Typically, the server allows slashes '/' for subcontexts. The name can be left as default or changed. Whatever name is given, the application should use the identical string in the application server-specific descriptor when mapping the resource reference string to the actual JNDI name specified in ejip.datasource.name.
Set the correct datasource name in the application's /WEB-INF/web.xml file
Modify the application's web.xml so that it matches the ejip.datasource.name property.
<resource-ref>
<! - - res-ref-name is the JNDI name used in application's code - - >
<res-ref-name>jdbc/myDataSource</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
Map the resource reference to the ejip.datasource.name in the application server-specific descriptor.
For instance, here is an example of a jboss-web.xml file that maps to the ejip.datasource.name of 'jdbc/DefaultDS':
<jboss-web>
<context-root>/mywebcontext</context-root>
<resource-ref>
<res-ref-name> jdbc/myDataSource</res-ref-name>
<!- - Server-specific JNDI name. Ex: "java:/"+ "ejip.datasource.name" - ->
<jndi-name>java:/jdbc/DefaultDS</jndi-name>
</resource-ref>
</jboss-web>
Notice, the ejip.datasource.name property does not have "java:/" ; however, the jboss-web.xml requires this prefix for this resource reference mapping.
Write the Java code
Write the Java code, making sure the DataSource name matches the resource-reference established in the web.xml deployment descriptor. Remember to prefix your web application's lookup into JNDI with "java:comp/env".
//get DB connection...
Connection con = null ;
try {
Context jndiCntx = new InitialContext();
out.println("Looking up jdbc/myDataSource");
DataSource ds = (javax.sql.DataSource)jndiCntx.lookup("java:comp/env/jdbc/myDataSource");
out.println("Found. Connecting to jdbc/myDataSource");
con = ds.getConnection();
if (null != con) {
out.println("Connection successful!");
}
} catch (Exception ex) {
out.println("getConnection failed. See error log for stack trace.");
} finally {
// close the Connection
try {
if (con!=null) con.close() ;
} catch(SQLException sqle) {
con = null ;
}
}
Note that the close() method on the connection actually returns it back to the database pool for other resources to use.
This section of myEvolution is where account databases can be modified, exported, and backed up.
The myEvolution SQL Tab allows execution of database queries and is automatically connected to the account's live database. It has three primary sections:
Subsections of the SQL Tab
Table Listing (top)
This section is always visible at the top of the SQL Tab and lists all tables currently in the databse. Clicking on one of the tables will display its definition.
SQL Commands (middle)
The SQL Execution Area allows the input of any standard SQL command that is compatible with the account's database. Output from the SQL Execution Area appears in the SQL Output area, which is described below.
Results / Messages (bottom)
The SQL Output Area displays output from database queries that were previously input in the SQL Execution Area.
The Backup Tab allows account holders to create a full data backup of an account's database. This file can then be downloaded for backup or analysis purposes. The Backup Tab also provides facilities for scheduling backups to occur on a regular basis. These backups augment other global database backups that Evolution Hosting performs on a regular schedule for all accounts.
Table of Contents
Evolution Hosting offers full e-mail hosting facilities to account holders. These services can take the form of simple e-mail aliases, or dedicated e-mail servers with custom Servlet based management facilities. This section of the Evolution User Manual details the various options and their use.
| Evolution E-mail Packages | |||||
|---|---|---|---|---|---|
| Option | Includes | Monthly Price | |||
| Shared | Dedicated | ||||
| Base Fee | Per Account | Base Fee | Per Account | ||
| 1 | JavaMail , Aliases , and Distribution Lists | $0 | $0 | Request a quote. | Request a quote. |
| 2 | IMAP Mailboxes (includes option 1) | $10 | $3 | Request a quote. | Request a quote. |
| 3 | Webmail and Portal Mail-API (includes options 1 and 2) | $20 | $4 | Request a quote. | Request a quote. |
JavaMail allows account holders to send e-mail from within programs. An example use of JavaMail is a shopping cart application that sends a confirmation e-mail when an order is processed.
The full JavaMail API is supported. The SMTP host name is available via the system property ejip.smtp . Sample code to send e-mail via the JavaMail API is included in the Cheetah tutorial.