TM BlueDragon 6.1 Installation Guide BlueDragon 6.
NEW ATLANTA COMMUNICATIONS, LLC BlueDragon™ 6.1 Installation Guide May 27, 2004 Version 6.1 Copyright © 1997-2004 New Atlanta Communications, LLC. All rights reserved. 100 Prospect Place • Alpharetta, Georgia 30005-5445 Phone 678.256.3011 • Fax 678.256.3012 http://www.newatlanta.com BlueDragon is a trademark of New Atlanta Communications, LLC. ServletExec and JTurbo are registered trademarks of New Atlanta Communications, LLC in the United States.
Contents 1. INTRODUCTION ..............................................................................................................I 1.1 ABOUT THIS MANUAL ..................................................................................................... I 1.2 TECHNICAL SUPPORT ..................................................................................................... I 1.2.1 Additional Information in FAQs ............................................................................. ii 1.
6.3.1 Automatic Configuration of ODBC Datasources (Windows) ..............................21 6.3.2 Configuring Access, SQL Server, and Other ODBC Datasources .....................21 6.3.3 Support for MySQL .............................................................................................22 6.3.4 Configuring Datasources Not Listed...................................................................22 7. EXECUTING YOUR CFML APPLICATIONS ...............................................................
1 1. Introduction N ew Atlanta BlueDragon is family of server-based products for the deployment of ColdFusion® Markup Language (CFML) for dynamic web publishing—with native technology platform integration on the operating system, web server, and database of your choice. CFML is a popular server-side, template-based markup language that boasts a rich feature set and renowned ease-of-use.
Besides offering all the documentation, a FAQ, and feature request options, perhaps the most useful aspect of our self-help support is our active BlueDragon-Interest discussion list. New Atlanta engineers and customers are available to help solve both common and challenging problems. There’s also a searchable archive of past discussion list topics. Details regarding paid support options, including online-, telephone-, and pager-based support are available from the New Atlanta web site: http://www.
2 2. BlueDragon Product Configurations BlueDragon is currently available in three product configurations: BlueDragon Server, BlueDragon Server JX, BlueDragon for J2EE and BlueDragon for .NET. 2.
BlueDragon/J2EE is available for Windows, Mac OS X, SPARC Solaris, IBM AIX, HPUX and Linux (and indeed, on any operating system which supports a J2EE server). 2.3 BlueDragon/.NET BlueDragon for .NET (BlueDragon/.NET), due to be released in beta form in the first quarter of 2004, allows you to deploy CFML applications as native .NET components on .NET servers. Like the J2EE edition, this also opens the door to integration with existing native .NET components as well as with ASP.NET pages. 2.
3 3. Preparing For Installation Before proceeding with installation of BlueDragon, there are a few concepts you should understand and in some cases preliminary steps that you should take first. 3.1 System Requirements BlueDragon Server is supported on the following operating systems, and provides web server adapters for the following web servers (BlueDragon Server is not supported on Windows 95/98/Me): OS Web Server Windows 2003 Microsoft IIS 4.0, 5.0, 5.1, and 6.
configuration not listed here, BlueDragon/J2EE will allow you to run your CFML applications on that configuration. For information about BlueDragon/J2EE, see the document, Deploying CFML on J2EE Application Servers. 3.1.1 JDK Requirements BlueDragon Server and Server JX for Windows and Linux are bundled with JDK 1.4.2, and for those editions that is the only JDK version we will support. When installed on Mac OS X, these editions require JDK 1.4.x as well.
You can also avoid this problem by using BlueDragon’s built-in web server for page processing, or you can install a new web server for integration with BlueDragon. Of course, there is no conflict installing BlueDragon if you have installed ColdFusion MX using its built-in web server or a servlet/JSP engine that uses its own web server. 3.
You will be prompted by the BlueDragon installer to specify a TCP/IP port number for the built-in web server; the default port number is 8080. After installation, you may modify the port number via the BlueDragon administration console. 3.7 Web Server Adapters For deploying production web sites, BlueDragon Server includes adapters for all leading web servers: Microsoft® Internet Information Server (IIS), Netscape® Enterprise Server (NES), iPlanet™ Web Server (iWS), and Apache HTTP Server.
3.7.2 Microsoft IIS Adapter uses Extension Mappings If you install a web server adapter on Microsoft IIS, be aware that the adapter runs using extension mappings rather than as an ISAPI filter. Generally, the adapter configuration is handled entirely by BlueDragon, but this clarification us useful should you need to perform any manual configuration. 3.7.
Figure 2. Restarting IIS 5.0 on Windows 2000 (Step 2) 3.7.4 Apache Support on Red Hat 9 Red Hat 9 comes with Apache 2.0.40. As discussed in the requirements section above, BlueDragon supports only 2.0.42 through 2.0.48. Please upgrade to one of these later versions of Apache. A solution for this problem is under consideration. Please contact bluedragon-support@newatlanta.com for more information if you cannot upgrade your Apache version. 3.7.
The following table describes these symbolic links in detail for the Red Hat and Mac OS X default configurations. From this information it should be straightforward to derive the required information for other configurations, such as Debian or Slackware (“environment variable”-style notation used below is only to compact the size of the table and need not be used in any commands executed on your system).
Note that these examples do not include a link for the Apache configuration specification file (httpd.conf) since the name is the same for the Red Hat or OS X installations as it is for the Apache Group installation. However, for some other Linux distributions, such as Gentoo, an additional link would need to be added to the list provided above for Red Hat: ln -s /etc/apache/conf/apache.conf /usr/local/apache/conf/httpd.conf 3.7.
4 4. Running the Installer There are separate BlueDragon installers for Windows, Linux, and Mac OS X. Be sure to download the appropriate installer for your operating system. Also, there are separate installers for BlueDragon Server and BlueDragon Server JX. Again, installation of BlueDragon/J2EE is covered separately in Deploying CFML on J2EE Application Servers. The BlueDragon installers are Java-based and include a built-in Java VM (JVM).
More detailed installer debug information can be found in the following files found in the root directory of the drive where BlueDragon installation was attempted: BlueDragon_Server_installation_error.log BlueDragon_Server_installation_output.log 4.2 Installing on Linux The BlueDragon Server and Server JX installers for Linux have the following file names (the entry-level BlueDragon Server is only available on Linux): BlueDragon_Server_61-Linux.sh BlueDragon_Server_JX_61-Linux.sh 4.2.
4.2.3 Startup and Shutdown Automation on Linux BlueDragon Linux installations include a script for simplifying the starting and stopping of both BlueDragon Server and Server JX configurations. The script is constructed in the “rc” standard form which allows for integration into the system startup and shutdown sequence of both Linux systems. This script is named and installed as follows for these respective systems and BlueDragon editions: /etc/rc.d/init.d/BlueDragon_Server Linux /etc/rc.d/init.
Agreement carefully and check the READ ME displayed by the setup program for any last minute notices before continuing. 4.3.1 Resolving Installation Problems on OS X Basic installer status information can be found in the installer log file, which is named BlueDragon_Server_JX_6.1_InstallLog.log (or without “_JX” version) located in the BlueDragon installation directory (if the installer is aborted before completing, the log file will be placed on the Windows desktop).
Item Description bin This directory contains various binary executable files used by BlueDragon Server. Do not modify or delete the contents of this directory. classes This directory exists in BlueDragon Server JX only and is automatically added to the classpath. See the READ ME in this directory for more information. config This directory contains various configuration files used by BlueDragon Server. Do not modify or delete the contents of this directory.
4.4.1 How the BlueDragon Server Has Been Installed On Windows, BlueDragon Server is installed as a service that is configured for automatic startup, and is started by the installer. On Linux and Mac OS X, BlueDragon Server is installed as a UNIX daemon and is started by the installer. See Sections 4.2.3 and 4.3.2 for more information. BlueDragon 6.
5 5. Verifying Your Installation With BlueDragon installed, you should now verify that the installation was successful by running some tests against the BlueDragon server as described in this section. 5.1 Built-in Web Server To verify that the BlueDragon built-in web server is running, enter the following URL in a web browser (if you specified a port other than 8080 during installation, use that port number in the URL): http://localhost:8080/index.
Figure 3. BlueDragon CFML Test Page BlueDragon 6.
6 6. BlueDragon Administration Console The BlueDragon administration console is used primarily to configure the BlueDragon environment. It also provides status information about the BlueDragon runtime state. The console offers online help on each page to assist in understanding how its features work. There is information in the online help that is not in the BlueDragon documentation. Additional discussion of the online help is found in the BlueDragon 6.1 User Guide.
Figure 4. Administration Console Login After logging in, the BlueDragon administration console will appear similar to Figure 5, below. Click the menu items in the left frame to access the various BlueDragon administration functions. Refer to the BlueDragon 6.1 User Guide, which can be found in the docs directory of the BlueDragon installation directory, for more information about using the administration console. BlueDragon 6.
Figure 5. BlueDragon Administration Console 6.2 Accessing the Administration Console Remotely As mentioned in the previous section, the BlueDragon administration console can only be accessed using the built-in web server. The built-in web server is configured by default to be accessible only from the server on which BlueDragon is installed. This means that the BlueDragon administration console, by default, cannot be accessed remotely.
• During installation, BlueDragon now prompts you to provide the option of changing the default setting of restricting access to the localhost. You can provide additional IP addresses or a range in the installation dialogue • If you’re able to access the administration console and want to modify it to allow other IP addresses to access it, note that the "License & Security" link (under "General") has a field called "Allowed IP addresses".
available. See http://www.jfitz.com/tips/putty_config.html for a tutorial on the Putty (ssh client) on Windows. Forward local port 8080 (or wherever you have BlueDragon’s internal server set) via SSH to the remote server port 8080. This will also allow you to leave the remote server configured to accept requests only from localhost/127.0.0.1, as that is where the incoming SSH tunnel will appear to come from.
described in Section 6.3.1 and then use the ODBC Refresh option also described there to see the datasource. 6.3.3 Support for MySQL As discussed previously in this document, while BlueDragon supports MySQL (and even shows an available MySQL Driver in the list of choices of drivers offered in the administration console when adding a datasource), the driver is not installed with BlueDragon. See Section 3.4 for more information on preparing the environment to support MySQL. 6.3.
7 7. Executing Your CFML Applications With BlueDragon installed and verified, the next step will be to execute your existing CFML applications. How you do this will depend on whether you’re using the built-in web server or have implemented a web server adapter. 7.1 Working with a Web Server Adapter If you’re using a web server adapter, the location of your CFML files will be driven by your web server and/or virtual directory mappings for that web server.
8 8. Viewing BlueDragon Logs There are two log files creating during the execution of BlueDragon templates. 8.1 BlueDragon Server.log files The BlueDragon Server.log files are located within the logs subdirectory of the BlueDragon installation directory (the file name is called BlueDragon Server JX.log on BlueDragon Server JX, and on Linux/Unix/OS X the words in the log file names are separated with underscores).
The advantage to creating a file for each error is that if an error occurs in production, you can see the error page without needing to ask the end user to print the page or create error handling processes with CFERROR. (You can, of course, still use CFERROR to create your own error handling process.) Note that this log of error pages grows without limit. You may want to delete older files occasionally.
9 9. Updating BlueDragon If you already have BlueDragon installed and want to install another edition or version, there are some concerns you should be aware of. This section highlights those. It also presents information that may be useful when uninstalling BlueDragon, which is discussed further in Section 10. In the discussions to follow, the term “edition” is used to refer to the different BlueDragon products, as in BlueDragon Server of BlueDragon Server JX.
that they must each be configured to use different ports for the built-in web server and any web server adapter. Be aware, however, that there is no mechanism to carry your current configuration settings, custom tags, logs, and wwwroot documents (if you used the built-in web server) from the current installation to another. Section 9.4 offers information to help preserve current settings and implement them in the new installation. 9.
• wwwroot holds any CFML and other web documents you created if you used the built-in web server for development • classes and lib hold CFX custom tags, database drivers, servlets, or other java classes (note that each will contain files and subdirectories even if you don’t place any there) • customtags holds any CFML custom tags you may have placed there for server-wide access (again, there are some sample files already placed there at installation) • servlets (found in Server JX only) holds any jav
9.5 Obtaining Updates and Patches Patches for BlueDragon are made available whenever New Atlanta deems it appropriate. Patches are always provided at no charge to BlueDragon users, therefore it’s highly recommended that you apply a patch whenever it is issued (as announced on the BlueDragon-Interest mailing list) to be sure to resolve or prevent problems you may experience. You can find these patches in the FTP site, ftp://ftp.newatlanta.com, specifically in the public/bluedragon directory.
10 10. Uninstalling BlueDragon The following sections describe uninstalling BlueDragon on Windows, Linux, and Mac OS X. 10.1 Protecting Previous Work, Settings, and Logs Before uninstalling, be cautioned that the BlueDragon uninstall process attempts to remove all directories and files where BlueDragon was installed, which may include useful work and information that you may want to protect (especially if you’re planning to then install a new release).
For the Server edition, remove the _JX portion of that command. The uninstaller will be launched in console or GUI mode based on the mode used when the installer was run. The GUI mode uninstaller requires a minimum of 8-bit color depth (256 colors) and a minimum 640 x 480 screen resolution. 10.4 Uninstalling on Mac OS X At a command prompt or from the Finder, execute the following uninstall application found in the “uninstall/Uninstall BlueDragon Server 6.1.
11 11. Appendix: Disabling NES/iWS Servlets Section 3.7.6 indicated that if you plan to install a BlueDragon web server adapter with Netscape® Enterprise Server/iPlanet™ Web Server, you must first disable the web server’s built-in servlet support. Follow the instructions, below, based on which version of the NES/iWS web server you have installed. 11.1 iPlanet Web Server 6.0 For iWS 6.0, the built-in servlet/JSP engine is enabled by default.
Figure 6. Disable iWS 6.0 Servlets/JSP Figure 7. Deactivate the iWS 4.0/4.1 Servlet Engine BlueDragon 6.
11.3 Netscape Enterprise Server 3.5.1 and 3.6 For NES 3.5.1 and 3.6, the built-in Java interpreter is deactivated by default. If, however, it has been activated on your server you must deactivate it before installing the BlueDragon web server adapter. 1. From the Netscape Administration Server home page, click the appropriate server. 2. Click Programs from the menu bar in the upper frame of the server administration page. 3. In the menu in the left frame of the Programs page, click Java. 4.
