Planning a DITA CMS Deployment. Small Business Edition

Planning a DITA CMS Deployment Small Business Edition WWW.IXIASOFT.COM / DITACMS v. 4.2 / Copyright 2016 IXIASOFT Technologies. All rights reserved. Last revised: June 09, 2016

Table of contents 3 Table of contents Introduction Copyright notice 7 New in this documentation release 7 Chapter 1: DITA CMS architecture and components DITA CMS architecture 10 Overview of the DITA CMS Small Business deployment 11 TEXTML Server 12 Content Store 12 Output Generator 15 Web Collaborative Reviewer 15 Web Author Application 16 CMS Application Server 17 Scheduler 17 Client components 17 Chapter 2: Planning the deployment of the DITA CMS solution Terminology 20 Factors influencing the size and type of a DITA CMS deployment 20 Number and types of users 21 DITA CMS content 23

4 Planning a DITA CMS Deployment Small Business Edition Output type and complexity 24 Deployment scenarios 24 Small Business deployments 24 DITA CMS server environments 28 Scaling components 28 Scaling TEXTML Server 28 Scaling the Output Generator 29 Scaling the Web Author Application 29 Scaling the CMS Application Server 30 Chapter 3: Technical specifications TEXTML Server 32 Configuring anti-virus scanning on the server 33 Output Generator 33 Configuring anti-virus scanning on the Output Generator 36 Web Collaborative Reviewer Application 36 Web Author Application 38 CMS Application Server 39 DITA CMS Scheduler 41 DITA CMS Eclipse Client 42 Configuring anti-virus scanning on the client 43 WCR Client 44

Table of contents 5 Web Author Client 45 Summary 45 Chapter 4: Provisioning requirements Software requirements 48 Hardware requirements 50 Appendix A: Appendix: Software versioning DITA CMS software versioning 54

6 Planning a DITA CMS Deployment Small Business Edition

Introduction This document provides the information required to plan a DITA CMS Version 4.2 deployment. Copyright notice 2011-2016 IXIASOFT Technologies Inc. All rights reserved. Except as otherwise expressly permitted by IXIASOFT Technologies Inc., this publication, or parts thereof, may not be reproduced or distributed in any form, by any method, for any purpose. This publication and the information contained herein are made available by IXIASOFT Technologies Inc. "as is." IXIASOFT Technologies Inc. disclaims all warranties, either express or implied, including but not limited to any implied warranties of merchantability or fitness for a particular purpose regarding these materials. New in this documentation release Build 4.2.29 update Added a section on DITA CMS software versioning on page 54. Added the TEXTML Server port in the technical specifications diagram for the Output Generator on page 33.

8 Planning a DITA CMS Deployment Small Business Edition

DITA CMS architecture and 1components DITA CMS architecture and components Topics: DITA CMS architecture Overview of the DITA CMS Small Business deployment TEXTML Server Output Generator Web Collaborative Reviewer Web Author Application CMS Application Server Scheduler Client components This section describes the DITA CMS architecture and components.

10 Planning a DITA CMS Deployment Small Business Edition DITA CMS architecture The DITA CMS solution is comprised of server and client components. Figure 1: DITA CMS architecture on page 11 shows the DITA CMS architecture. Server On the server side, the DITA CMS solution includes the following components: TEXTML Server: Provides a native XML database that combines a reliable document repository with powerful search functions for the DITA CMS content. It also manages the Content Store. Content Store: Stores all the DITA content (maps, topics), non-dita content (images, PDF files, videos, etc.), and workgroup configuration for the DITA CMS. Output Generator: Executes the transformation process from DITA content to the specified output type (PDF, HTML, XML, CHM, etc.). Scheduler: Schedules and executes jobs such as pre-generating output, sending notifications, creating activity reports, etc. Web Collaborative Reviewer (WCR) Application: Allows users to access the PDF-based collaborative reviewing functionality of DITA CMS from an Internet browser. Web Author Application: Allows users to easily edit and review DITA documents from an Internet browser without having to install the DITA CMS Eclipse Client. CMS Application Server: Provides the business logic and caching for DITA CMS applications, such as the Web Author Application. Client There are three clients in the DITA CMS solution: DITA CMS Eclipse Client: Graphical user interface (GUI) that allows users to access the entire set of DITA CMS functionalities, including authoring, reviewing, localizing, and publishing. Web Collaborative Reviewer (WCR) Client: Web client that allows users to access the reviewing functionality of the DITA CMS from an Internet browser. Web Author Client: Web client that allows content contributors and reviewers to edit and review DITA CMS topics from an Internet browser. Overview of DITA CMS components The following diagram shows the DITA CMS architecture. Each component is described in details in the next sections.

DITA CMS architecture and components 11 Figure 1: DITA CMS architecture Overview of the DITA CMS Small Business deployment A DITA CMS Small Business deployment is a simplified version of the DITA CMS deployment with standard configuration and limited features and functionality. In a DITA CMS Small Business deployment, all the DITA CMS components are deployed on a single machine (Windows only), and a single Content Store is supported. The DITA CMS Small Business uses a default workflow configuration and can be accessed by a maximum of 10 concurrent users.

12 Planning a DITA CMS Deployment Small Business Edition Note: Additional user licenses can be purchased. The following components are not available in the basic DITA CMS Small Business deployment, but they can be added for an additional fee: Web Collaborative Reviewer Web Author (including the CMS Application Server) Scheduler In the DITA CMS Small Business deployment, the localization module is not included, but the sequential localization module and language packs can be added for an additional fee. TEXTML Server TEXTML Server is a native XML database that combines powerful search support and a reliable document repository. TEXTML Server is the main component of the DITA CMS solution. It interacts with all the other server and client components. It manages the Content Store, which holds all the DITA CMS data. Content Store DITA CMS documents and configuration are kept in a central location called a Content Store. The Content Store contains the following data: DITA documents: Maps and topics Non-DITA documents: Images and other resources such as PDF files, videos, legacy documentation, and so on Workgroup configuration: Set of business rules that define the workflow for the documents in the Content Store. This configuration specifies the sequence of states that the documents must follow as well as access rights, user group definitions, dictionaries, etc., for the Content Store data. A DITA CMS Small Business deployment contains only one Content Store. The workflow cannot be customized. If the company requires different sets of business rules or workflows, the system can be upgraded to DITA CMS Standard Edition to allow for customizations. Backing up the Content Store TEXTML Server supports the following methods for backing up the Content Store:

DITA CMS architecture and components 13 By performing a full hot copy of a live Content Store By using a volume snapshot of where the Content Store resides, either through the OS (Shadow Copy, LVM Snapshot) or the storage layer (SAN) By using a local replicated Content Store Failover and disaster recovery of the Content Store The Content Store is the most critical component of the DITA CMS since it contains all the data. The TEXTML Server can be deployed to ensure that DITA CMS data is always available and easily recoverable should a machine component fail. In case of a system failure, the lost data can be recovered in two ways: High availability/failover and disaster recovery. They are discussed in the following sections. High availability/failover Failover is a standby operational mode where the functions of a system component (processor, server, network, or database) are handled by secondary system components during a system failure. There are two possible solutions for high availability/failover for a DITA CMS deployment: 1. Using clustering active/passive - When using a high availability cluster, two TEXTML Server installations are needed, one for each node of the cluster. Only one TEXTML Server can be active at one time. When using clustering: A shared block storage is required between the active and the passive nodes. The customer is responsible for the licensing of cluster software and hardware. An additional DITA CMS license is required. The CMS administrator needs to understand the clustering solution since the process is more complex to manage than a regular installation. Once the DITA CMS server is restored, the end user only needs to reconnect. Note: The TEXTML Server does not provide a clustering functionality and uses the existing Windows failover cluster solution. 2. Hypervisor with a virtual machine - Only one installation of TEXTML Server is required. When using a hypervisor with a virtual machine: No extra DITA CMS license is required. No extra configuration is required for the DITA CMS. The DITA CMS installation is standard.

14 Planning a DITA CMS Deployment Small Business Edition All complexities are hidden by the hypervisor and the exact capabilities are defined by the hypervisor. Once the DITA CMS server is restored, the end user only needs to reconnect. Disaster recovery A disaster recovery involves the procedures and policies for data recovery and retrieval following a natural or human-induced disaster. There are two possible solutions for disaster recovery for a DITA CMS Small Business deployment: 1. Using hypervisor with a virtual machine - Only one installation of TEXTML Server is required. When disaster recovery is implemented using hypervisor with a virtual machine: No additional licensing and configuration are required by DITA CMS. All complexities (procedures to retrieve the data) are hidden by the hypervisor and the exact capabilities are defined by the hypervisor. Procedure for installing the DITA CMS is standard. The process of data replication between data centers is hidden by the hypervisor. Once the DITA CMS server is restored, the end user just needs to reconnect. 2. Cold standby with manual data synchronization - The cold standby is a secondary machine where all the DITA CMS components are installed, but not running. It is the responsibility of the customer to copy the data between sites. When disaster recovery is implemented using cold standby with manual data synchronization: An additional DITA CMS license is required. The installation procedure is standard for both primary and secondary sets of machines. Upgrades or updates should be performed on both primary and secondary sets of machines. The customer is responsible for copying the data between sites (with either backup or snapshot); depending on the delay between the copies, it is possible to lose data. The domain name system (DNS) alias pointing to the primary server needs to be remapped to point to the new disaster recovery secondary machine, thus allowing the end user to reconnect without a problem. The replicated data needs to be restored manually before it can be accessed by the end users. Once the DITA CMS server is restored, the end user only needs to reconnect. Once the primary server is restored the entire process needs to be redone.

DITA CMS architecture and components 15 Output Generator The Output Generator executes the transformation process from DITA to the specified output type (PDF, HTML, XML, CHM, etc.). The Output Generator is a centralized server that ensures that users generate their outputs using the same style sheets. Its multithreaded architecture allows users to generate multiple outputs simultaneously. The Output Generator works as follows: 1. It retrieves from the Content Store the DITA objects to be transformed. 2. It saves the files to a working folder. 3. It calls all the tasks defined in the conductor file to transform the DITA files. 4. When the transformation is completed, it zips the generated output and returns it to the DITA CMS Eclipse Client. Any process can be defined in the conductor file to achieve the final transformation to the selected rendered output. The process can be a DITA Open Toolkit script (provided in the DITA CMS installation) or a custom build script. Also, the rendering engine for PDF can be customized to Antenna House, RenderX, or Apache FOP. Web Collaborative Reviewer The Web Collaborative Reviewer (WCR) is a web application that allows reviewers to provide feedback on the DITA CMS content using an Internet browser. When a user logs in to the WCR, the web client retrieves the document objects (topics, maps, images) assigned to this user. The user can select an object and start the review process. When a user selects an object for review, the WCR Application fetches the PDF file from the Content Store and displays it. The user can then annotate the PDF file and add review marks. If the PDF file is not available, the WCR Application requests a PDF review output from the Output Generator and displays it to the user. When the user has finished to review the object, the PDF is saved back to TEXTML Server with the reviewer's annotations. Multiple reviewers can annotate the same documents at the same time. The WCR allows users to review content without having to install the DITA CMS Eclipse Client. This is particularly useful for users such as subject-matter experts (SMEs), who do not need the complete functionality of the DITA CMS.

16 Planning a DITA CMS Deployment Small Business Edition The WCR is a Tomcat application. Tomcat is an application server from the Apache Software Foundation that executes Java servlets and renders Web pages that include Java Server Page coding. Tomcat must be installed before the WCR can be installed and run. Web Author Application The Web Author Application is a web application that allows content contributors and reviewers to easily edit and review DITA documents. It can be used both by users new to DITA or by advanced DITA CMS users. When a user logs in to the Web Author, the web application presents a list of documents assigned to the user in each of the user's roles. For example, if a user is assigned some topics as a writer and other topics as a reviewer, the Web Author retrieves all of these topics and displays them to the user, grouped by roles. When a user selects a document, it opens in the oxygen pane of the Web Author, where the user can modify or comment the document, according to the user role. The functions available depend on the user role. For example, consider a typical scenario for a writer role, where a content contributor needs to provide documentation for a new feature: The information architect uses the DITA CMS Eclipse Client to create the topics that require content and assign these topics to the content contributor in the writer role. The content contributor starts the Web Author and sees these topics in the Assignments area. The content contributor simply needs to click on a document, enter content, and submit the document. The content is then saved in the Content Store. The document returns to its workflow in the DITA CMS Eclipse Client. Now consider a typical scenario for a reviewer role, where a subject-matter expert (SME) needs to review content written by a writer: Once the topics are written, the writer or information architect puts the topics in the reviewing status and assigns them to the SME in the reviewer role. The SME starts the Web Author and sees these topics in the Assignments area. The SME clicks on a document and adds annotation (but cannot change the content). The SME submits the document. The content is then saved in the Content Store. The document returns to its workflow in the DITA CMS Eclipse Client. The Web Author Application is a Tomcat application that supplies the graphical user interface to the Web Author Client. It connects to the CMS Application Server to provide the requested documents to the client.

DITA CMS architecture and components 17 CMS Application Server The CMS Application Server provides the business logic and cache for DITA CMS applications, such as the Web Author Application. It handles the requests to the TEXTML Server and Output Generator. The CMS Application Server is based on the GlassFish application server technology. Scheduler The Scheduler executes scheduled tasks such as pre-generating output, reminding users that they have active documents or that one or more actions are required on their part, creating activity reports, etc. The DITA CMS Scheduler is like a task scheduler (Windows). It checks at scheduled intervals if there are events to process. The events are stored in the Content Store. Client components There are three clients: the DITA CMS Eclipse Client, the WCR Client, and the Web Author Client. DITA CMS Eclipse Client The DITA CMS Eclipse Client is a rich client that provides a graphical user interface (GUI) allowing users to access the DITA CMS functionality, which includes: DITA map editing Topic authoring (using XML authoring tools such as XMetaL XMAX and oxygen XML Editor/Author) Advanced search Version control Link management Image management Standard workflow only Project management Localization management Multi-format publishing PDF-based Collaborative Reviewer (this feature is different from the Web Collaborating Reviewer)

18 Planning a DITA CMS Deployment Small Business Edition This client is a set of plug-ins that run on the Eclipse Framework. Eclipse is a Java-based program available for multiple operating systems (OS). DITA CMS WCR Client The WCR Client is a light client used for web collaborative reviews; it allows users to access the reviewing functionality of DITA CMS without having to install Eclipse. This client is based on the Java applet technology and only requires Java and an Internet browser. The WCR client is not included in the basic DITA CMS Small Business deployment. It requires an additional license. DITA CMS Web Author Client The Web Author Client is a web client that allows content contributors and reviewers to edit and review topics from an Internet browser without having to install the DITA CMS Eclipse Client. It provides some of the DITA CMS Eclipse Client functionality according to user roles and can be used by beginner and advanced DITA users. This client is based on the Java applet technology and requires Java, an Internet browser, and an oxygen web component license. The Web Author client is not included in the basic DITA CMS Small Business deployment. It requires an additional license.

Planning the deployment of the DITA 2CMS solution Planning the deployment of the DITA CMS solution Topics: The DITA CMS Small Business can be deployed on a single Terminology machine only. The following factors will help identify the Factors influencing the size hardware and resource requirements for the Small Business and type of a DITA CMS deployment deployment. This section describes the factors that influence the size and type of deployment and then describes the Small Deployment scenarios Business deployment scenarios. Finally, it describes how the Scaling components server components can be scaled up to support larger deployment needs.

20 Planning a DITA CMS Deployment Small Business Edition Terminology The following terms are used in the deployment scenarios documentation. Content Store Workgroup Workgroup configuration Satellite user Hypervisor with virtual machine Cold standby Stores all the DITA content (maps, topics), non-dita content (images, PDF files, videos, etc.), and workgroup configuration for the DITA CMS. Group of users in a company who share the same Content Store. Set of business rules that define the workflow for the DITA and non-dita documents in the Content Store.This configuration specifies the sequence of states that the documents must follow as well as access rights, user group definitions, dictionaries, etc. A user who works from home or a very small office (with very few DITA CMS users). A hypervisor, also called a virtual machine manager, is a program that allows multiple operating systems to share a single hardware host. The hypervisor controls the host processor and resources, allocates the needs of each operating system, and checks that the guest operating systems or the virtual machines do not disrupt each other. Cold standby is a redundancy method in which the secondary (or standby) system is turned on manually when the primary system fails. Note: Before the system on cold standby is brought online, the latest available copy of the data (including the Content Store) need to be installed or mounted in the cold standby system. Factors influencing the size and type of a DITA CMS deployment Many factors influence how to deploy the DITA CMS solution. They are: Number and types of users DITA CMS content to be developed and stored Output type and complexity

Planning the deployment of the DITA CMS solution 21 Number and types of users The DITA CMS targets all the users in the technical documentation cycle. The following table lists the standard types of DITA CMS users and describes their responsibilities. Note that some of these roles may not apply in a company, depending on the size of the documentation team. Table 1: DITA CMS users Role Subject-matter experts (SME) Project coordinators/ Project Managers Information architects Authors Editors Graphic artists/illustrators Reviewers Translators/Localizers Build masters Responsibilities Provide raw technical information. They might also review the content. Organize the various components and activities needed to manage the content development and release process. Develop map structures, add topics to maps, organize content, publish documents, etc. They also generate the required outputs (PDF, HTML, Eclipse Help, etc.). Develop, edit, and finalize content. When they have completed their content, they send it for technical review. They might also use the Output Generator to see a preview of their output. Review and edit content for grammatical accuracy. Create, modify, and finalize images. Provide feedback on the technical accuracy of the content. Manage the documents in multiple languages. Localization tasks include creating multiple copies of the original document (one copy for each language), exporting the documents as localization kits, sending them to translators, re-importing the documents into the DITA CMS, and generating the output. Generate the content into all the required outputs (PDF, HTML, Eclipse Help, etc.).

22 Planning a DITA CMS Deployment Small Business Edition Role Toolsmiths Responsibilities Configure and implement the Output Generator transformation scenarios, typically with the DITA Open Toolkit. Each user role has a specific set of responsibilities, and these responsibilities determine the extent to which the DITA CMS components are used, as summarized in the following table. Table 2: DITA CMS component usage Role DITA CMS usage WCR usage Web Author usage Output Generator usage Subject matter experts Light Light Light N/A Project coordinators/ Project Managers Light Light N/A Light Information architects Heavy Light N/A Heavy Authors Light Light Light Light to Moderate Might generate output for their personal purpose and to send documents for review Editors Light Light Light Light (if any) Graphic artists /Illustrators Light Light N/A Light (if any) Reviewers Light Light Light Light Translators/Localizers Heavy N/A N/A Heavy Build masters Light N/A N/A Heavy

Planning the deployment of the DITA CMS solution 23 Role DITA CMS usage WCR usage Web Author usage Output Generator usage Toolsmiths Light N/A N/A Heavy Legend Light: These users work on a small number of topics at any time and thus generate a small number of DITA CMS transactions. Heavy:These users typically work on a large number of topics at any time and perform complex operations on many objects. DITA CMS content The content to be developed largely influences the type of deployment chosen. In particular, to plan a deployment the following must be determined: The number of document objects to store (topics, images, maps) The number of languages into which the document objects will be translated Every time a document is localized in another language, all of its objects are duplicated and stored in the Content Store. For example, consider a documentation set with three maps, where each map contains an average of 300 topics. If the maps are translated into 10 languages, then a total of 9000 topics are created in the Content Store (10 languages * 3 maps * 300 topics). How often the documentation is published Note: In DITA CMS terminology, publishing a map means that a release version is created and copies are made of each object in the map. This is equivalent to creating a snapshot of the map and its content and ensures that the content is not affected by future changes. This definition is different from the standard technical documentation publishing concept, which often simply means that the final output is generated.

24 Planning a DITA CMS Deployment Small Business Edition Output type and complexity Output generation also impacts how the DITA CMS will be deployed. DITA CMS output is generated using the Output Generator. To determine how to deploy the Output Generator, the following questions must be answered: How many documents will be generated? How often will the output be generated? In how many formats will documents be generated? Will the transformation scenarios be simple or complex and require heavy processing? How quickly must the output be generated? Are there time constraints? Deployment scenarios The following section provides the most common DITA CMS Small Business deployment scenarios. Small Business deployments In a DITA CMS Small Business environment all the server components are installed on a single server. There are two kinds of deployment scenarios for DITA CMS Small Business purposes. Note: There is a limitation on the total number of users (including authors, reviewers, editors, information architects, etc.) who can access the Content Store in a Small Business deployment. 1. On-site deployment: In this deployment scenario, all DITA CMS server components are installed on a single server located at the customer's primary location. Figure 2: On-site deployment for Small Business DITA CMS on page 26 shows a sample on-site deployment. Two kinds of users can access the DITA CMS Server components in an on-site deployment scenario: Local users: These are the users at the customer's primary location. The DITA CMS Eclipse Client is installed on all the user workstations and the DITA CMS server is accessed over HTTP, SMB, and CORBA. Satellite users: These are users working from home or at a secondary location (e.g., London). The DITA CMS application can be accessed in one of two ways:

Planning the deployment of the DITA CMS solution 25 By installing the DITA CMS Eclipse Client on their workstations and connecting to the main DITA CMS server at the primary location over VPN/WAN. This is the preferred solution for light users such as authors, editors, and reviewers. Because these users generate a small number of DITA CMS transactions, their tasks can be executed over VPN/WAN while still providing a good response time. By working with a DITA CMS Eclipse Client installed at the customer's primary location using a remote application solution such as Citrix, Microsoft remote application, or a virtual machine. This is the preferred solution for heavy users such as information architects, localizers, and production officers. Because these users perform a large number of DITA CMS transactions on many objects, their transactions must be performed locally at the primary site for optimal performance.

26 Planning a DITA CMS Deployment Small Business Edition

Planning the deployment of the DITA CMS solution 27 Figure 2: On-site deployment for Small Business DITA CMS 2. Cloud deployment: In this scenario, all the DITA CMS server components are installed on a private cloud platform owned by the customer. Figure 3: Cloud deployment for Small Business DITA CMS on page 27 shows a sample cloud deployment. Users can access the DITA CMS Server components in a cloud deployment scenario through: The remote desktop protocol (RDP) connection. The web browser applications such as the WCR or the Web Author Application. The WCR application allows users to access the PDF-based collaborative reviewing functionality of DITA CMS from an Internet browser and the Web Author Application allows users to easily edit and review DITA documents from an Internet browser without having to install the DITA CMS Eclipse Client. Figure 3: Cloud deployment for Small Business DITA CMS

28 Planning a DITA CMS Deployment Small Business Edition DITA CMS server environments The DITA CMS server is installed in two environments: Production environment: This environment contains the actual data and is the environment where users perform all the work. It is also where the deliverable documents are generated. Development / Test environment: This environment can be used to develop and test custom templates and transformation scenarios, validate configuration changes, test new updates and upgrades before putting them in production, test new releases of the DITA-OT or DITA specification, etc. IXIASOFT recommends that a development/test environment be installed. Note: The DITA CMS server environments cannot be accessed concurrently by the DITA CMS Eclipse Client. Scaling components For larger deployments or to comply to the requirements of a company, some of the DITA CMS server components must be scaled. The DITA CMS server components can be scaled up (i.e., resources are added to the component, such as adding CPU or RAM) and/or scaled out (i.e., components are added to the solution, such as installing the Output Generator on multiple machines). For Small Business deployment, however, only a scale up option is available. A scale out option is possible when DITA CMS is upgraded to the Standard Edition. Scaling TEXTML Server TEXTML Server can be scaled by increasing the resources on the machine. Scale up The resources on the server (RAM, CPU, disk space, etc.) can be increased as necessary, to cover the following needs: Additional users: Increases the number of transactions, especially for heavy users. Increasing number of documents: Increases the size of the Content Store and requires additional TEXTML Server indexing. New languages: Increases the size of the Content Store and requires additional TEXTML Server indexing.

Planning the deployment of the DITA CMS solution 29 Increasing number of Publish/Localize operations: Increases the size of the Content Store and requires additional TEXTML Server indexing. In all these cases, adding more RAM will increase performance. If memory is so large as to contain the whole Content Store, more CPUs can be added to increase performance. The disk space must also be large enough to hold the Content Store. Scaling the Output Generator The Output Generator can be scaled up. In a DITA CMS deployment, the Output Generator is used to generate output: requested by the DITA CMS users for the web collaborative reviews for scheduled documentation builds The resources required by the Output Generator server depend on the output generation operations and the kind of performance that an organization requires. For example, the resources requirements for a small documentation team that generates documentation twice a year will be very different from that of a worldwide company that regularly generates large documentation sets in multiple output types in a short amount of time. Scale up The Output Generator can be scaled up by adding more resources (CPU, RAM, etc.) to the server on which it is running. Scaling up the Output Generator ensures that it can handle a large number of jobs without requiring an additional license of the rendering engine. It can also handle more complex jobs, such as generating maps in multiple output types (CHM, PDF, HTML, etc.) or generating multiple PDF files for different audiences. Scaling the Web Author Application The Web Author Application can be scaled up. The Web Author may need to be scaled if a decrease in performance is observed when users try to download the applet in the Web Author Client. This can happen if a large number of users are accessing the Web Author Client at the same time or if users are trying to access the Web Author Application from a remote location.

30 Planning a DITA CMS Deployment Small Business Edition Scale up The Web Author Application can be scaled up by adding more resources (CPU, RAM, etc.) to the server on which it is running. Scaling the CMS Application Server The CMS Application Server can be scaled up. The CMS Application Server is responsible for handling the business logic and caching for applications such as the Web Author Application. The CMS Application Server may need to be scaled if the response time from the Web Author Application is too long. This can happen, for example, if there are multiple Web Author Applications that connect to the same CMS Application Server. Scale up The CMS Application Server can be scaled up by adding more resources (CPU, RAM, etc.) to the server on which it is running. Note that adding more memory is the preferred option (as opposed to adding more CPUs).

3Technical specifications Technical specifications Topics: TEXTML Server Output Generator Web Collaborative Reviewer Application Web Author Application CMS Application Server DITA CMS Scheduler DITA CMS Eclipse Client WCR Client Web Author Client Summary This section provides the technical specifications of each component to help plan the installation process.

32 Planning a DITA CMS Deployment Small Business Edition TEXTML Server TEXTML Server is a process that runs on Windows. Figure 4: TEXTML Server technical details on page 32 shows how the process interacts with the different DITA CMS components. The DITA CMS documents are kept in a Content Store.When the DITA CMS solution is initially installed, a Content Store is created to store documents. A Content Store is implemented as an XML database of TEXTML Server. A Content Store is a set of files organized in a folder/directory structure. TEXTML Server must have full access rights to the directory that holds the Content Store. The TEXTML Server configuration is stored in a local XML file. A set of messages, events, and status are written to a local log file, which must be manually cleaned up. By default, TEXTML Server listens on TCP port 2500 for requests coming in from the DITA CMS Eclipse Client, Output Generator, Web Collaborative Reviewer, Scheduler, and CMS Application Server. Additional TEXTML Servers and Content Stores can also be used for fault tolerance or to create a development environment in which to test new releases. Figure 4: TEXTML Server technical details

Technical specifications 33 IP address translation TEXTML Server does not support any type of IP address or port translation. This includes: Port forwarding (from a public IP address to a private address) Tunneling with address translation (for example, using ssh tunnel) Firewall TEXTML Server can be installed behind a firewall, but the IP address of TEXTML Server must be reachable from the client without address translation. The firewall must have the following port open: Port from the DITA CMS Eclipse Client, Output Generator, WCR Application, CMS Application Server, or Scheduler to TEXTML Server (2500 by default) Configuring anti-virus scanning on the server When TEXTML Server is running, no other process can read from or write to its Content Store files. Also, the internal data format of Content Store files is proprietary to IXIASOFT, which can make an anti-virus program report false positive matchings during scanning. Therefore, the anti-virus must be configured to prevent real-time scanning as well as regular (manual or scheduled) scanning of certain files and ports, as follows: Exclude the TEXTML Server communication port (2500 by default) from being scanned by the anti-virus program. Exclude the folder where the Content Store files will be saved as well as any destination specified when doing a backup. Exclude the parent folder of all instances of TEXTML Server where the configuration files and logs are saved (default is %ProgramData%\ixiasoft). Output Generator The Output Generator is a Java program that runs as a service. It runs in the background as a Windows service and executes the transformation process as requested by the DITA CMS Eclipse Client or Web Collaborative Reviewer. Figure 5: Output Generator technical details on page 35 shows how the process interacts with the different DITA CMS components.

34 Planning a DITA CMS Deployment Small Business Edition By default, the Output Generator process listens on TCP port 1500 for transformation requests. The Output Generator configuration is stored in a local text file. When a request comes in, the Output Generator retrieves from TEXTML Server the documents to be transformed and saves them to a local, temporary working directory. This directory must be cleaned regularly. The Output Generator transforms the DITA CMS content using the DITA Open Toolkit (packaged with the Output Generator) or a customized build system, depending on the deployment. When the transformation is completed, the Output Generator zips the generated output and returns it to the DITA CMS Eclipse Client. The Output Generator may establish a callback to the client. This callback is controlled by the client, which supplies the port when requesting to get feedback from an Output Generator (for example, TCP port 1501). If the client sets this value to 0 (zero), the Output Generator will not send any progress information through the callback.

Technical specifications 35 Figure 5: Output Generator technical details IP address translation The Output Generator does not support any type of IP address or port translation. This includes: Port forwarding (from a public IP address to a private address) Tunneling with address translation (for example, using ssh tunnel) Firewall The Output Generator can be installed behind a firewall, but the IP address of the Output Generator must be reachable from the client without address translation. The firewall must have the following ports open:

36 Planning a DITA CMS Deployment Small Business Edition Port from the DITA CMS Eclipse Client, WCR Client, CMS Application Server, or Scheduler to the Output Generator (1500 by default) Port from the Output Generator to the DITA CMS Eclipse Client (1501 by default, if enabled) Configuring anti-virus scanning on the Output Generator To execute transformation scenarios, the Output Generator which is a file-based processing mechanism manipulates many text and script files. Having an anti-virus program perform real-time scanning of these files (scripts and temporary files) can reduce the performance of the Output Generator. Therefore, the anti-virus must be configured to prevent real-time scanning of certain files and ports, as follows: Exclude the Output Generator installation directory. Exclude the Output Generator communication port (1500 by default) from being scanned by the anti-virus program. Note that regular scanning (manual or scheduled) can still be performed, if required. Web Collaborative Reviewer Application The WCR Application is a Java web applet that runs under a Tomcat server. Note: The WCR Application requires that a Tomcat application server be installed. The Tomcat application server can be installed with the rest of the DITA CMS components or an existing installation can be used, as long as it's supported by the DITA CMS. See the Software requirements section for more information. Figure 6: WCR technical details on page 37 shows how the process interacts with the different DITA CMS components. The WCR Application component listens on the TCP port defined by Tomcat (80 by default) for requests coming in from the WCR Client. When the connection is established between the WCR Client and WCR Application, the WCR Application opens an outgoing connection to TEXTML Server on port 2500 (default) to retrieve the review content (as PDF files) assigned to the user and display it. If the PDF was not already generated for the review, the WCR Application opens an outgoing connection to the Output Generator on port 1500 (default) to generate the appropriate PDF. The WCR Client writes to a local, temporary working directory to track the reviewer's annotations until the review is completed.

Technical specifications 37 When the user has completed and saved the review, the WCR Application reopens the connection to TEXTML Server to send the annotations. The WCR configuration is stored in a local text file. Figure 6: WCR technical details IP address translation The WCR Application supports network address translation (NAT), since it relies on Tomcat to control the IP connection. Firewall The WCR Application can be installed behind a firewall with or without NATing. The firewall must have the following ports open: Port from the WCR Client to the WCR Application (80 by default) Port from the WCR Application to the Output Generator (1500 by default) Port from the WCR Application to TEXTML Server (2500 by default) Anti-virus scanning No special anti-virus scanning is required for the WCR Application. Related Links

38 Planning a DITA CMS Deployment Small Business Edition Software requirements on page 48 Web Author Application The Web Author Application is a Java web applet that runs under a Tomcat server. Note: The Web Author Application requires that a Tomcat application server be installed. The Tomcat application server can be installed with the rest of the DITA CMS components or an existing installation can be used, as long as it's supported by the DITA CMS. See the Software requirements section for more information. Figure 7: Web Author Application technical details on page 38 shows how the process interacts with the different DITA CMS components. The Web Author Application listens on the TCP port defined by Tomcat (80 by default) for requests coming in from the Web Author Client. When the connection is established: The Web Author Application supplies the graphical user interface (GUI) to the Web Author Client on port 80 (default) The Web Author Application opens an outgoing connection to the CMS Application on port 3700 (default) to retrieve the data to run on the Web Author Client. The Web Author Application configuration is stored in a local text file. Figure 7: Web Author Application technical details IP address translation The Web Author Application supports network address translation (NAT), since it relies on Tomcat to control the IP connection.

Technical specifications 39 Firewall The Web Author Application can be installed behind a firewall with or without NATing. The firewall must have the following ports open: Port from the Web Author Client to the Web Author Application (80 by default) Port from the Web Author Application to the CMS Application Server (3700 by default) Anti-virus scanning No special anti-virus scanning is required for the Web Author Application. CMS Application Server The CMS Application Server is a Java application server that runs on a GlassFish server. Figure 8: CMS Application Server technical details on page 39 shows how the process interacts with the different DITA CMS components. The CMS Application Server listens on port 3700 for request coming from the Web Author Application. When a request comes from the Web Author Application, the CMS Application Server opens an outgoing connection to TEXTML Server on port 2500 (default) to retrieve the documents assigned to the user and display them. The CMS Application Server listens on port 4848 for configuration data from the GlassFish Administration Console. The CMS Application Server configuration is stored in a local text file. The CMS Application Server opens an outgoing connection to the Output Generator on port 1500 (default), as necessary. Figure 8: CMS Application Server technical details

40 Planning a DITA CMS Deployment Small Business Edition IP address translation The CMS Application Server does not support any type of IP address or port translation. This includes: Port forwarding (from a public IP address to a private address) Tunneling with address translation (for example, using ssh tunnel) Firewall The CMS Application Server can be installed behind a firewall, but the IP address of the CMS Application Server must be reachable from the Web Author Application without address translation. The firewall must have the following ports open: Port from the Web Author Application to the CMS Application Server (3700 by default) Port from the CMS Application Server to TEXTML Server (2500 by default) Port from the GlassFish Administration Console (running on a web browser) to the CMS Application Server (4848 by default) Port from the CMS Application Server to the Output Generator (1500 by default) Anti-virus scanning No special anti-virus scanning is required for the CMS Application Server.

Technical specifications 41 DITA CMS Scheduler The DITA CMS Scheduler is a Java program that runs as a service. It runs in the background as a scheduled task (Windows). Figure 9: DITA CMS Scheduler technical details on page 41 shows how the process interacts with the different DITA CMS components. The DITA CMS Scheduler configuration is stored in a local text file. This configuration specifies the jobs to execute. At configured intervals, the DITA CMS Scheduler opens an outgoing connection to TEXTML Server (port 2500) to see if there are events to process. It also connects to an SMTP server on port 25 to deliver emails. It can connect to the Output Generator (port 1500 by default) if there are PDFs to generate. Only one instance of the DITA CMS Scheduler is required per deployment. Figure 9: DITA CMS Scheduler technical details Firewall The DITA CMS Scheduler is never accessed by a client, so no firewall rules are required. Anti-virus scanning No special anti-virus scanning is required for the DITA CMS Scheduler.

42 Planning a DITA CMS Deployment Small Business Edition DITA CMS Eclipse Client The DITA CMS Eclipse Client is a set of plug-ins that run on the Eclipse Framework. The following DITA CMS plug-ins are available for all users: DITA Content Management System: Main DITA CMS functionality. Collaborative Reviewer: Allows DITA CMS reviewers to provide feedback on topics and allows authors to consult and revise topics that have been commented. DITA 1.2 Specification: Provides the rules for publishing DITA content in print, HTML, online Help, and other formats. The following plug-ins are available for DITA CMS administrators only: DITA CMS Administration: Provides access to the DITA CMS Administration Console. TEXTML Server Administration: Allows workstation users to interact with IXIASOFT's TEXTML Server component, typically installed on the server that holds the Content Store. The following optional plug-ins are also available: oxygen XML Extension (Editor or Author): Provides the DITA CMS context menus in the oxygen XML Editor installed in Eclipse; a third-party license is required to run this plug-in. It also installs the DITA CMS User Guide for oxygen online help. XMetaL XMAX Extension: Provides the DITA CMS context menus in the XMAX Editor installed in Eclipse; a third-party license is required to run this plug-in. It also installs the DITA CMS User Guide for XMAX online help. HyperSTE: Activates the HyperSTE functions for XMAX; a third-party license is required to run this plug-in. Figure 10: DITA CMS Eclipse Client technical details on page 43 shows how the DITA CMS Eclipse Client interacts with the different DITA CMS components. The DITA CMS Eclipse Client opens an outgoing connection to TEXTML Server on port 2500 (default) to store, search, and retrieve the DITA documents and the user configuration. Until the user releases documents to store them in the Content Store, they are saved to the user's Eclipse workspace, which is a directory on the user's workstation. The DITA CMS Eclipse Client opens an outgoing connection to the Output Generator on port 1500 (default) to generate the appropriate output type (PDF, HTML, etc.). If the Output Generator is configured to establish a callback to the DITA CMS Eclipse Client, the client listens on TCP port 1501 (default) to receive progress reports. To disable the callback, set the TCP port to 0.

Technical specifications 43 The DITA CMS Eclipse Client may request progress information from the Output Generator by specifying a listening port (for example, 1501). When the client sets this listening port, the Output Generator will establish a callback to the DITA CMS Eclipse Client. By default, this port is set to 0, which disables the callback. Figure 10: DITA CMS Eclipse Client technical details Firewall The DITA CMS Eclipse Client can be installed behind a firewall, with or without masquerading. All outgoing connections from the client will be automatically translated as usual, but the connection incoming from the Output Generator must be deactivated. This is done in the DITA CMS Eclipse Client preferences, by setting the Output Generator Monitoring Port to 0. Configuring anti-virus scanning on the client Having an anti-virus program perform real-time scanning of the DITA CMS Eclipse Client installation directory and workspace folder can reduce the performance of the DITA CMS Eclipse Client. Therefore, the anti-virus must be configured to prevent real-time scanning of certain files and ports, as follows:

44 Planning a DITA CMS Deployment Small Business Edition Exclude the DITA CMS Eclipse Client communication ports (1501, 1500, and 2500 by default) from being scanned by the anti-virus program. Exclude the folder where Eclipse is installed. These files have a ZIP signature and the anti-virus usually tries to open each of them for scanning, which can result in performance degradation. Exclude the workspace folder where Eclipse stores documents for the DITA CMS. All files in this folder are only used by the DITA CMS and are never executed. Most of the files are XML files. Other files of type ZIP, PDF, JPG, GIF, and PNG can also be present, as well as any other type of file that can be handled by the DITA CMS plug-in through resources. Note that regular scanning (manual or scheduled) can still be performed, if required. WCR Client For the WCR Client, the user simply needs an Internet browser that connects to the WCR Application (port 80 by default). Figure 11: WCR Client technical details Firewall The WCR Client can be installed behind a firewall, with or without masquerading. All outgoing connections from the client will be automatically translated as usual. Anti-virus scanning No special anti-virus scanning is required for the WCR Client.

Technical specifications 45 Web Author Client For the Web Author Client, the user simply needs an Internet browser that connects to the Web Author Application (port 80 by default). Figure 12: Web Author Client technical details Firewall The Web Author Client can be installed behind a firewall, with or without masquerading. All outgoing connections from the client will be automatically translated as usual. Anti-virus scanning No special anti-virus scanning is required for the Web Author Client. Summary The following diagram summarizes the interactions between the DITA CMS components.

46 Planning a DITA CMS Deployment Small Business Edition Figure 13: Interactions between the DITA CMS components

4Provisioning requirements Provisioning requirements Topics: This section provides the hardware and software requirements Software requirements for the DITA CMS 4.2 solution. Hardware requirements TEXTML Server: TEXTML Server 4.3.6.4188 and up is required Oracle Java: Java 1.7.0_51+ is required (Java 1.8 is not supported) Eclipse SDK: Version 4.3 is required

48 Planning a DITA CMS Deployment Small Business Edition Software requirements Before installing the DITA CMS, the servers and workstations on which the software will be installed must match a set of software requirements. Software requirements for the server components The following OS versions are supported on the DITA CMS servers: Windows 2008 and 2008R2 (64 bits only) and up are recommended. The following table lists the software requirements for the DITA CMS server components: Table 3: Server software requirements Component Software requirements TEXTML Server IXIASOFT TEXTML Server 4.3.6.4188 and up Output Generator Rendering software (e.g., RenderX, Antenna House, Apache FOP) Java 1.7.0_51 or 1.7.0-80 and up (Java 1.8 is not supported) (JRE or JDK) WCR Application Java 1.7.0_51 or 1.7.0-80 and up (Java 1.8 is not supported), 64-bit version (JRE or JDK) Apache Tomcat 6.x, 64-bit version Web Author Application CMS Application Server Oracle Java version 1.7.0_51 (Java 1.8 is not supported), 64-bit version (JRE or JDK) Apache Tomcat 6.x, 64-bit version Java 1.7.0_51 or 1.7.0-80 and up (Java 1.8 is not supported) (JDK only) Oracle GlassFish Server version 3.1.2 Scheduler Java 1.7.0_51 or 1.7.0-80 and up (Java 1.8 is not supported) (JRE or JDK) Software requirements for the client components The following table lists the software requirements for the client components:

Provisioning requirements 49 Table 4: Software requirements for the client components Component Software requirements DITA CMS Eclipse Client Eclipse SDK 4.3 with the DITA CMS plug-ins Versions of OS supported: Windows 7 64-bit version is recommended, but the following are supported: Windows Vista and Windows 7 32-bit version Oracle Java 1.7.0_51+ (Java 1.8 is not supported) Note: The DITA CMS Eclipse Client requires a good communication with the server components. The latency needs to be better than 50ms and the DITA CMS Eclipse Client requires enough bandwidth to transfer a 5-MB file in a reasonable time; otherwise, the user experience will be unpleasant. One solution is to host the DITA CMS Eclipse Client using a remote application solution in the same location as the TEXTML Server and Content Store. See Deployment scenarios for more information. WCR Client and Web Author Client Internet browser On Windows: Internet Explorer 8.x and up Mozilla Firefox 3.6 and up Safari 5.1 and up Note: Chrome is not supported. 1.7.0_51+ (Java 1.8 is not supported) Related Links Web Collaborative Reviewer Application on page 36

50 Planning a DITA CMS Deployment Small Business Edition Hardware requirements The servers and workstations on which the DITA CMS solution will be installed must match the recommended hardware requirements. General assumptions The hardware recommendations described in this section are based on a deployment with the following characteristics: Number of authors Number of reviewers Number of languages Number of objects (topics, images, maps) 10 20 10 10000 Hardware requirements for the server This section provides the hardware requirements for the production and development environments. Table 5: Requirements for the Production environment Operating System CPU RAM Windows 2008 64 bit and up to Windows 2012 r2 64 bits 4 Core (8 recommended) 16 GB (32 recommended) Volume For the DITA CMS application: 5 GB + 5 GB temporary folder space. For the Content Store: 150 to 500 GB on a block device. The block device can be a local disk, a SAN volume, or a virtual disk. It should have the same characteristics as a dedicated SAS RAID 10 15K RPM (500 to 800 IO/s) with 4 KB block size (can be replaced with SSD in RAID 1). Note:

Provisioning requirements 51 If the Content Store is in a Virtual Machine, the virtual disk can be hosted on SMB, NFS, or passthrough). For the backup (if snapshot is not used): Each backup is a full backup of the Content Store; a backup storage of at least 150 to 500 GB is required (any type of drive including NAS). Table 6: Requirements for the Development / Testing environment Operating System CPU RAM Windows 2008 64 bit and up to Windows 2012 r2 64 bits 4 Core 16 GB Volume For the DITA CMS application: 3 GB + 2 GB temporary folder space. For the Content Store:150 to 500 GB. For the backup (if snapshot is not used): At least enough to contain one backup (any type of drive including NAS). Note: If the Development / Testing machine is used only for functional testing and not performance, the CPU and the memory can be reduced to a minimum value; the I/Os can be reduced by half. The disk space is still required for functional testing. Hardware requirements for the remote server This section provides the hardware requirements for a remote application server. Table 7: Requirements for the server Remote Application Server For 5 users: Quad-core (hyper threading does not count) 8 GB of RAM

52 Planning a DITA CMS Deployment Small Business Edition For 10 users: Eight-core (hyper threading does not count) 12 GB of RAM A dedicated drive is also required to store the local data for each user; about 1 GB per user is required. Hardware requirements for the client This section provides the hardware requirements for the client environment. Table 8: Requirements for the Client components Operating System CPU RAM Windows Vista 32- or 64-bit and up to Windows 8.1 32- or 64-bits (64-bits recommended) 2 Core 3 GB Volume 1 to 2 GB for the installation (between 10,000 to 50,000 files) 1 to 2 GB for working folder (between 10,000 to 50,000 files)

AAppendix: Software versioning Appendix: Software versioning Topics: DITA CMS software versioning This section describes the DITA CMS software versioning strategy.

54 Planning a DITA CMS Deployment Small Business Edition DITA CMS software versioning There are three main categories of software versions in the DITA CMS: major.minor.[build]. The version categories convey the significance of the software changes from one version to another. As the versions are released, you can infer the scope of the changes by its version number. For example: Figure 14: Example of a release cycle They are defined as follows: Major: The major number increases (for example, from 4.2.0 to 5.0.0) when there are significant changes in the DITA CMS functionality or its components (Output Generator, Web Author, Web Collaborative Reviewer, Scheduler) that require an important upgrade of the DITA CMS deployment. These include a major upgrade of the underlying framework (Java, Eclipse, etc.), an operating system that is no longer supported, a major update of the TEXTML Server version, etc. A new major software version may introduce changes that are not compatible with the configuration of an older version. In this case, an upgrade procedure is provided. Minor: The minor number increases (for example, from 4.0.0 to 4.1.0) to introduce new important features. A minor update may require configuration changes and upgrades of the DITA CMS components. A new minor software version may introduce changes that are not compatible with the configuration of an older version. In this case, an upgrade procedure is provided. Build: The build number increases (for example, from 4.1.0 to 4.1.1) to introduce bug fixes, which may require small updates to the DITA CMS components. No major upgrades are required. Minor configuration changes may be needed and are documented in the Detailed Release Notes. Any change in the software must be backward compatible. The following table describes the characteristics of each version category: Major Minor Build New features Yes Yes No

Appendix: Software versioning 55 Major Minor Build Bug fixes Yes Yes Yes OS upgrade Maybe No No Java upgrade Major Maybe No No Minor Maybe Maybe Maybe * TEXTML upgrade Major Maybe No No Minor Maybe Maybe Maybe * Eclipse SDK upgrade Maybe No No XML Editor upgrade Maybe Maybe No Web Author infrastructure upgrades (Tomcat, Glassfish) Maybe No No Configuration changes Yes Yes Maybe Documentation updates Yes Yes Maybe * In rare instances when critical bugs are found.

56 Planning a DITA CMS Deployment Small Business Edition