Deploying WebObjects Applications Apple Computer, Inc. NeXT, the NeXT logo, OPENSTEP, IN NO EVENT WILL APPLE BE Enterprise Objects Framework, LIABLE FOR DIRECT, INDIRECT, © 1999 Apple Computer, Inc. Objective–C, and WEBSCRIPT are SPECIAL, INCIDENTAL, OR All rights reserved. trademarks of NeXT Software, Inc. CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT No part of this publication may be Adobe, Acrobat, and PostScript are OR INACCURACY IN THIS MANUAL, reproduced, stored in a retrieval trademarks of Adobe Systems even if advised of the possibility of system, or transmitted, in any form or Incorporated or its subsidiaries and such damages. by any means, mechanical, electronic, may be registered in certain photocopying, recording, or otherwise, jurisdictions. THE WARRANTY AND REMEDIES without prior written permission of SET FORTH ABOVE ARE Apple Computer, Inc., except to make Helvetica and Palatino are registered EXCLUSIVE AND IN LIEU OF ALL a backup copy of any documentation trademarks of Linotype-Hell AG and/or OTHERS, ORAL OR WRITTEN, provided on CD-ROM. its subsidiaries. EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is The Apple logo is a trademark of Apple ITC Zapf Dingbats is a registered authorized to make any modification, Computer, Inc. trademark of International Typeface extension, or addition to this warranty. Use of the “keyboard” Apple logo Corporation. (Option-Shift-K) for commercial Some states do not allow the exclusion purposes without the prior written ORACLE is a registered trademark of or limitation of implied warranties or consent of Apple may constitute Oracle Corporation, Inc. liability for incidental or consequential trademark infringement and unfair damages, so the above limitation or competition in violation of federal and SYBASE is a registered trademark of Sybase, Inc. exclusion may not apply to you. This state laws. warranty gives you specific legal rights, and you may also have other No licenses, express or implied, are UNIX is a registered trademark in the rights which vary from state to state. granted with respect to any of the United States and other countries, technology described in this book. licensed exclusively through X/Open Apple retains all intellectual property Company Limited. rights associated with the technology Windows NT is a trademark of described in this book. This book is Microsoft Corporation. intended to assist application developers to develop applications All other trademarks mentioned only for Apple-labeled or belong to their respective owners. Apple-licensed computers. Simultaneously published in the Every effort has been made to ensure United States and Canada. that the information in this manual is accurate. Apple is not responsible for Even though Apple has reviewed this typographical errors. manual, APPLE MAKES NO WARRANTY OR Apple Computer, Inc. REPRESENTATION, EITHER 1 Infinite Loop EXPRESS OR IMPLIED, WITH Cupertino, CA 95014 RESPECT TO THIS MANUAL, ITS 408-996-1010 QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS Apple, the Apple logo, Macintosh, and FOR A PARTICULAR PURPOSE. AS WebObjects are trademarks of Apple A RESULT, THIS MANUAL IS SOLD Computer, Inc., registered in the “AS IS,” AND YOU, THE United States and other countries. PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY Enterprise Objects is a trademark of AND ACCURACY. Apple Computer, Inc. Table of Contents Introduction 5 Related Documentation 5 WebObjects HTTP Adaptors 7 CGI Adaptors 7 API-based Adaptors 8 Installable HTTP Adaptors 8 Configuration Files 9 Automatic Discovery of WebObjects App Servers 10 Web Server Adaptor 10 wotaskd 11 Web Server Adaptor Configuration File Format 11 XML Format in Full 11 Sections 13 Attributes 13 Sample Configuration File 15 Configuration File DTD 16 Installing Applications 19 Deploying With Monitor 21 Setting Up the Monitor Application 21 Starting Up Monitor 21 Setting Up Monitor 22 Deploying on Multiple Hosts 24 Adding a Host to Monitor 25 Adding and Configuring an Application 27 Creating Application Instances 29 Starting and Stopping an Application Instance 30 Setting Command-Line Arguments in Monitor 32 Starting Up Applications From the Command Line 37 Monitor Option Summary 40 Global Configuration 40 Host Configuration 42 Application Configuration Options 43 Instance Configuration Options 44 iii Table of Contents Administrative Tasks 47 Monitoring Application Activity 47 Obtaining Information From Monitor 47 Logging and Analyzing Application Activity 50 Logging and Analyzing Adaptor Activity 50 Accessing the Application Statistics Page 51 Performance Testing 54 Recording a Session 54 Playing Back a Session 55 Improving Performance 57 Automatic Scheduling 59 Load Balancing 62 Increasing the Listen Queue Depth 65 Making Monitor and wotaskd Fail-safe 67 Starting Monitor and wotaskd on Windows NT 67 Using woservice on Mac OS X Server 67 The WebObjects Application URL 69 iv Introduction Introduction To a large extent, WebObjects needs little attention once it is installed. However, administrators of a WebObjects site still need to know how to accomplish certain tasks, such as installing applications, creating and running instances of them, and configuring HTTP adaptors. In addition, you’ll probably be concerned about improving your site’s performance. The tools and techniques described in this document help administrators complete the tasks required to deploy and maintain WebObjects applications. Because each deployment can be different, the document gives suggestions and options for making your deployment successful. This document begins by providing essential background information on WebObjects HTTP adaptors and how they are used to distribute requests. Then it describes how to use an application called Monitor to monitor and administer your deployment. Finally, it describes the basic administrative tasks are and tells you how to perform them. Related Documentation Other WebObjects documents might be of interest to system administrators: • Installation Guide: Includes system requirements, compatibility information, and location of the WebObjects Home Page. (The Installation Guide is printed and included with the WebObjects CD-ROM or can be downloaded from NeXTanswers; it is not online). • Post-Installation Instructions: Describes how to verify the installation and troubleshoot if WebObjects applications do not run. • Installation instructions for supported HTTP adaptors can be found in InstallationInstructions.html, which is located in NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/. Instructions for building HTTP adaptors from provided source code are located in BuildingInstructions.html in the same directory. 5 WebObjects HTTP Adaptors WebObjects HTTP Adaptors A key part of WebObjects administration involves dealing with adaptors. This section provides a little background material on what a WebObjects HTTP adaptor is, how it works, and how you can configure it to suit your needs. A WebObjects HTTP adaptor (called WebObjects adaptor or sometimes HTTP adaptor) routes client requests processed by an HTTP server to WebObjects applications and returns the response to the server, which sends them back to the client. WebObjects makes available several adaptors, of which only one can be active with a particular server at a time. Every transaction with a WebObjects application uses the currently active adaptor. The relationships between adaptor and application are, potentially, many-to- many. Multiple instances of the same WebObjects application can run on the same machine or on a variety of machines and communicate with the same adaptor. In addition, multiple HTTP servers can be running on the same machine or on different machines; each server can have its own adaptor, each with its own constellation of application instances. Although there can be only one active HTTP adaptor per HTTP server, an application can concurrently communicate with other types of adaptors, such as an adaptor that uses Distributed Objects or a secure-socket adaptor. There are two general types of HTTP adaptors, CGI adaptors and API-based adaptors. When WebObjects is installed, the CGI adaptor is made active by default. To use an API-based adaptor, you must specifically activate it. Activating the API-based adaptor deactivates the CGI adaptor for a particular server. To activate an API-based adaptor, build and install it using the instructions found in BuildingInstructions.html and InstallationInstructions.html (both are located in NEXT_ROOT/Developer/Examples/WebObjects/Source/Adaptors/). CGI Adaptors The CGI adaptor is an executable file named WebObjects—WebObjects.exe on Windows NT—which resides in the host HTTP server’s cgi-bin or scripts directory. This adaptor is available on all supported platforms. It is generic in that it works with any HTTP server conforming to the Common Gateway Interface (CGI). 7 WebObjects HTTP Adaptors API-based Adaptors API-based adaptors are WebObjects adaptors based on APIs specific to a particular web server. The NSAPI adaptor, which is based on the Netscape Server 3.5 API, is available on all supported platforms except the Mach-based Mac OS X Server. A WebObjects adaptor based on Microsoft’s Internet Information Server API (ISAPI) is also supported on Windows NT. WebObjects supports an adaptor based on Apache’s module API on UNIX platforms (including the Mac OS X Server). In addition, Netscape’s WAI API is provided as an example project, although is not supported; the WAI adaptor is suitable for all platforms except Mac OS X Server. The