Installation Guide

Chapter 1   Introduction

This chapter presents an overview of the SilverStream Application Server and the SilverStream installation program. The SilverStream installation program is self-documenting--that is, it includes documentation in the installation screens. There are some decisions you should make before installing SilverStream. This chapter helps you make those decisions.

The chapter includes the following sections:

• SilverStream components and packaging

• Application server configurations

• About the installation program

• Installation decisions

• Migrating to Version 3

• Contacting Technical Support

    For the latest information on hardware and software requirements and supported databases, see the Release Notes. In Windows, you can access the Release Notes from the SilverStream program group or from SilverStream online help.

SilverStream components and packaging

The SilverStream Application Server product family consists of the following:

• Developer Edition: An application server and full set of tools for developing applications

• Workgroup Edition: A deployment or development server licensed by user

• Enterprise Edition: A deployment or development server licensed by CPU

    For more information about these editions, see Application server configurations.

The SilverStream package contains the following:

• SilverStream Application Server

  The Enterprise Data Connectors are included in the Developer Edition and can be used to develop only. They are sold separately for deployment in a production environment in the Enterprise Edition.

• Java 2 JRE

• jBroker

• jBroker MQ

• Fulcrum SearchServer for full-text search

• Cloudscape

• Sybase Adaptive Server Anywhere (Developer Edition only)

• Java compiler

Application server configurations

SilverStream is both a development and deployment product. It is available in these configurations:

• Developer Edition (SDE). The Developer Edition is a full set of tools and application server software for building and testing Java applications based on the Java 2, Enterprise Edition (J2EE) standards. It includes a single-user version of the SilverStream server as well as a number of components to help developers build applications quickly. These components include, among others, the SilverStream Designer, SilverCmd, the SilverStream Management Console (SMC), SilverJRunner, SilverJ2EEClient, jBroker, jBroker MQ, Fulcrum SearchServer, Cloudscape, Sybase Adaptive Server Anywhere, Help database, and sample applications.

  In a multideveloper environment, the recommended configuration is for each developer to have a SilverStream server and Designer running on the same machine. Each developer should also have a standalone database (such as Cloudscape or Sybase Adaptive Server Anywhere) on their machine, so that each server can store its own version of the design data. In addition, you should install a source control system to ensure that changes made by developers are not overwritten by other developers.

  The chief benefit of configuring one server per designer is that each developer can have a sandbox environment--that is, a space to develop, test, and build applications independently. A developer is not affected by changes made by other developers on a shared server, until that developer chooses to get those changes from source control.

  If this multideveloper model is not appropriate for you, you can use the Developer Edition along with the Workgroup or Enterprise Edition to do development using a shared server: you would install the Designer (tools) component from the Developer Edition and use the server from the Workgroup or Enterprise Edition.

• Workgroup Edition (SWE). The Workgroup Edition is designed for workgroup-scale application deployment or application development by small teams of developers where it is not practical for each developer to have their own server. In this situation, each developer would have a Developer Edition installed on their workstation (using a Designer-only install) and use a shared Workgroup Edition server on another machine.

  It includes the SilverStream server, SilverCmd, SilverJRunner, SilverJ2EEClient, the SilverStream Management Console (SMC), Fulcrum SearchServer, Cloudscape, jBroker, and jBroker MQ. It does not include development tools or Sybase Adaptive Server Anywhere.

  The Workgroup Edition server is licensed by number of users.

• Enterprise Edition (SEE). The Enterprise Edition is designed for medium- and high-volume application deployment. It includes the SilverStream server, SilverCmd, SilverJRunner, SilverJ2EEClient, the SilverStream Management Console (SMC), Fulcrum SearchServer, Cloudscape, jBroker, jBroker MQ, support for deploying Enterprise Data Connectors, and support for clustering (load-balancing) servers. It does not include development tools or Sybase Adaptive Server Anywhere.

  As with the Workgroup Edition, you can also use Enterprise Edition in group development environments.

  The Enterprise Edition server is licensed by CPU.

About the installation program

The Windows NT installation program is a wizard-based InstallShield program that allows you to select and install the various components of the SilverStream server, Designer, documentation, and sample applications. This program also provides an interface to the Sybase Adaptive Server Anywhere Installation program.

The UNIX installation script install.sh starts a PERL script to install and configure the SilverStream Application Server on UNIX and Linux.

The SilverStream installation performs the following tasks:

• Copies files from the distribution CD to the specified directories.

• Creates a SilverStream program group with entries for the SilverStream server, SilverStream Management Console (SMC), SilverStream Help, Release Notes, and SilverStream Designer (Windows only).

• Creates the SilverStream Windows registry keys (hkey_local_machine\software\SilverStream Software Inc.\SilverStream) (SilverStream proprietary registry on UNIX).

• Asks which database you want to use for the SilverMaster (see Choosing a database for SilverMaster).

• Executes the SilverMasterInit program.

  The SilverMasterInit program creates the SilverMaster database tables and uploads the SilverStream resources needed to support both the design-time and runtime environments into the SilverMaster database.

• Asks for a license key to be applied to the SilverStream server. The license key is uploaded and stored in the SilverMaster database.

Installation decisions

Before you install SilverStream, you should decide the following:

• Which database will you use for your SilverMaster?

  The SilverStream server requires that one database be set up as the SilverMaster database.

      For more information about SilverMaster, see the next section.

• Do you want to install the Fulcrum SearchServer engine?

  The Fulcrum SearchServer engine allows you to use full-text search in applications or in the SilverStream Help database.

• Do you want to access the sample applications?

  The sample databases shipped with the SilverStream product are Sybase Adaptive Server Anywhere and Cloudscape databases. You must install Sybase Adaptive Server Anywhere or Cloudscape to access these databases (Cloudscape is provided with all editions of the server; Adaptive Server Anywhere is provided with Developer Edition only).

• Do you want to access SilverStream's help system from a database or file system?

  SilverStream delivers the help system as a file system and as a Sybase Adaptive Server Anywhere database. Installing the help system as a database lets you use Fulcrum's full-text search. You must install Adaptive Server Anywhere to access it (a version of Adaptive Server Anywhere is provided with Developer Edition).

• What kind of install do you want to perform?

  You can install the full SilverStream product or just specified components.

      For more information, see Choosing the installation type.

Choosing a database for SilverMaster

The SilverMaster database catalog is a database used by SilverStream. There is one SilverMaster catalog for each SilverStream server or SilverStream cluster. The SilverMaster keeps track of all of the application databases used by the SilverStream server and also holds the SilverStream system tables--for example, tables containing security group and user information.

NOTE   Do not put any other database objects in your SilverMaster database catalog, as you may lose SilverStream objects if you have to rebuild your SilverMaster database.

SilverStream provides Sybase Adaptive Server Anywhere and Cloudscape, though you can choose any supported DBMS.

The SilverStream server is capable of communicating with multiple database engines at once. For example, you can install your SilverMaster database on Sybase Adaptive Server Anywhere and have all of your application databases in another database, such as Oracle.

Preparing the database to be a SilverMaster

You need to create a database to use as your SilverMaster before installing the SilverStream server (unless you are using Cloudscape or the bundled version of Adaptive Server Anywhere as your SilverMaster on Windows, in which case the installation program can create a database for you).

The SilverStream server must connect to a database that is to be used as the SilverMaster and any other databases you want to access from SilverStream. The SilverStream server acts as a database client, so the server requires any database client software, ODBC driver, JDBC driver, and any configuration necessary for an application connecting to a particular database.

The steps for setting up a database differ for each database type. See the appropriate chapter in this guide for more information about setting up your database type.

    For more information about the SilverMaster database, see the Administrator's Guide.

Choosing the installation type

SilverStream provides several types of installation that let you tailor the environment to your needs. Your choices include:

Choice	Description
Typical Install	Installs all the necessary SilverStream software program files for the edition you are installing. For the Developer Edition, this includes the Help database (SilverHelp, a Sybase Adaptive Server Anywhere database) and all of the sample applications. It creates any ODBC settings that are needed by the sample databases, but it does not add them to your server. You must perform an Add Database in order to access a particular sample application database. This installation is recommended for most users. With Enterprise Edition and Workgroup Edition, this option installs the SilverJRunner Installers on the server. These Installers allow your end users to download SilverJRunner (and SilverJ2EEClient) from a page that is running on the server. If you are installing Developer Edition and want to install the SilverJRunner Installers on the server, you need to choose Full or Custom Install. This option is available with all SilverStream products.
Full Install	Installs all the necessary software for your edition. For the Developer Edition it also adds all of the sample application databases to your server (if Sybase Adaptive Server Anywhere is found on your system). If you do this type of install, the SilverStream server starts all of the database engines for the sample application databases as part of the server startup. This option is provided for the convenience of users who want to explore SilverStream's sample applications at once. This option installs the SilverJRunner Installers on the server with all editions. This option is available with all SilverStream products.
Designer Only	Installs the SilverStream Designer, SilverJRunner, SilverJ2EEClient, and the file system-based version of Help. The SilverStream server will not be installed. This option should be used only if you will be developing all of your applications against a SilverStream Workgroup or Enterprise Edition Server located on another computer. This option is available for the SilverStream Developer Edition.
SilverJRunner	Installs SilverJRunner (which allows end users to run SilverStream Java forms and views) and SilverJ2EEClient (SilverStream's J2EE application client container). Note that end users can also download SilverJRunner and SilverJ2EEClient from a running SilverStream server (this is true with Developer Edition servers only if the server was installed using Full or Custom Install). This option is available for the SilverStream Developer Edition.
Cluster Managers	Installs the SilverStream Load Balancer, Dispatcher, and Cache Manager. This option is for server administrators who want to install the load balancing tools on a different computer than the SilverStream server. This option is available for the SilverStream Enterprise Edition.
Custom Install	Allows you to choose exactly which components are installed. Use this option to install the Enterprise Data Connector components. This option is available with all SilverStream products.

About the sample applications

SilverStream provides many sample applications that can be used as programming examples or can be run in a user environment.

    For information about sample J2EE applications, see Sample J2EE Applications in the server's Core Help.

    For information about sample applications that use classic SilverStream technologies, such as pages and forms, see Sample Applications in the server's Classic Development Help.

Installing the SilverStream server and programs to run as a service or a daemon

When you are running high-availability servers in a multiuser environment, it often makes sense to run servers as a Windows NT service or as a UNIX daemon. Running the SilverStream server and the database server as a service or daemon on the same machine ensures that both services will restart automatically when the machine reboots. You can set the SilverStream server to run as a service or a daemon using the Installation program. By default, the SilverStream server runs as a desktop program, not as a service or a daemon.

Running the SilverStream server as a service or a daemon allows you to:

• Avoid security risks caused by keeping the server program logged in on the computer running the server

• Automatically start the server whenever Windows NT or UNIX is started

• Start the server remotely with the NT Service Manager or with a UNIX shell

• Pass startup parameters to the server

• Run the server with administrative account privileges while you run other programs using your local accounts

• Avoid tying the server to a specific user ID

NOTE   To view or log server debugging information when running the SilverStream server as a service or a daemon, use the Server Console in the Designer. For more information, see the section on using the Server and Java consoles in the Main Designer chapter in the Tools Guide of the server's Classic Development Help. For information about generating and storing server logs, see the section on SilverStream server logging when run as a service in the Administrator's Guide.

SilverStream programs that can run as services or daemons

The following table lists the SilverStream programs that can also run as services or daemons.

Program	Description	Runs as
SilverStream server	Serves applications	By default, runs as a desktop program
Load Manager	Manages the activity of the servers in a cluster	Usually run as a desktop program
SilverMonitor	Monitors the server status and attempts to restart the server if it terminates abnormally	Usually run as a desktop program
Dispatcher	Redirects requests to SilverStream servers	Usually run as a desktop program
Cache Manager	Keeps server caches for clusters in sync	Usually run as a desktop program

NOTE   By default, Sybase Adaptive Server Anywhere or Sybase SQL Anywhere run as desktop programs, though they can also be run as services. For more information, see Configuring Sybase Adaptive Server Anywhere and SQL Anywhere Databases.

Guidelines on setting SilverStream to run as a service or a daemon

You can configure the SilverStream server to run as a service or daemon when you initially install the server using the Installation program. However, it's often easier to install the SilverStream server as a desktop program, then test it before configuring it to run as a service or daemon. The following steps are recommended when installing the server as a service or daemon.

To set up the SilverStream server to run as a service or daemon:

1. Install the SilverStream server as a program (not a service or a daemon) and create a SilverMaster database as described in Installing SilverStream on Windows or Installing SilverStream on UNIX.

2. After your SilverMaster database has been created or updated, configure your database server to start as an automatic service using NT services.

   NOTE   The SilverStream server service requires the database to be running when the server starts. By default, the Sybase Adaptive Server Anywhere database is not installed as a service. For more information, see Step 4: Run Sybase ASA or SQL Anywhere as a service.

3. If you haven't already done so, set up any other services that you want to run with the SilverStream server, such as Fulcrum or SNMP.

4. Verify that the SilverStream server is running properly. For more information, see Testing the install for NT or Testing the install for UNIX.

5. Run the SilverStream Installation program a second time using one of the following procedures:

   • Installing the SilverStream server as a service.

   • Setting the SilverStream server and cluster components to run as daemons.

   Because you already installed the server as a program in Step 1, no files are copied when you change the server to run as a service. You also will not need to run SilverMasterInit or create any properties files.

6. If you are using NT security in your application, you should change the NT Security settings on your machine using the NT User Manager.

       For more information on setting User Rights Policy for SilverStream, see the section on NT Security in the Administrator's Guide. For more information about the operation and administration of services, see the Windows NT documentation.

Migrating to Version 3

You cannot upgrade directly from SilverStream Version 1.x to Version 3. You must first upgrade to SilverStream Version 2. Contact your sales representative to obtain the appropriate software.

Migrating a SilverMaster

During installation, you are asked if you want to upgrade a Version 2 SilverMaster. To migrate from Version 2 to Version 3, choose use an existing database for your SilverMaster. (If instead you specify to create a new SilverMaster or initialize an existing SilverMaster, you will need to respecify all your previous server properties, including your users and groups, and re-add databases to the server.)

Upgrading application databases

When you start the Version 3 SilverStream server, it upgrades every database referenced by the SilverMaster. Once upgraded to Version 3, you cannot access it with a Version 2 Designer or Server.

Once you have successfully started your Version 3 SilverStream server and all of the databases have been upgraded to Version 3, you can turn off the auto-upgrade feature to reduce server startup time. Set the following line in the SilverStream\resources\httpd.props file:

  http-server.com.sssw.srv.autoupgrade.25=FALSE

    For complete information about migrating from a previous version of SilverStream, see the migration document in Getting Started of the server's Classic Development Help.

Maintaining multiple versions of SilverStream

If you want to maintain both Version 2 and Version 3 of SilverStream (or different versions of SilverStream Version 3) on one machine, then you must:

1. Create a new SilverMaster database for the SilverStream Version 3 server.

2. Create an ODBC DSN entry for the new database (if required for that database type).

3. During the installation procedure, choose Use an existing database for SilverMaster and Initialize the SilverMaster database and point the installation program to the new SilverMaster database.

   (If you are using Cloudscape or the authenticated version of Adaptive Server Anywhere as your SilverMaster, you don't need to perform the previous steps. You can have the installation program create a new version-specific SilverMaster.)

4. Continue with the install and respond to the installation wizard as appropriate for your database type.

If you install a new version of the help database or the sample applications, you will not be able to use them from an earlier version of SilverStream.

If you want to run both SilverStream servers at once, you must specify different ports.

    For more information, see the chapter on running the server in the Administrator's Guide.

Contacting Technical Support

SilverStream provides extensive online product support at its Web site: www.silverstream.com.

In the Support section of the SilverStream Web site, you can learn about the Technical Support programs and how to contact Technical Support. You can also access FAQs, tips and tricks, known customer issues, patches, links to related information, and so on. You can also use this area to submit problems, questions, and enhancement requests.

To access the member area, you must provide a user ID and password, which you receive when you register your product. The Installation program provides the opportunity to register the product after you complete the install.

If you contact SilverStream Technical Support for assistance, you will be asked to provide the information about your environment contained in the following checklist.

Category	Description
SilverStream version	You can obtain the build number by right-clicking the microhelp line at the bottom of the Main Designer. Also: The build number is displayed at server startup The build number is displayed in the SilverStream Management Console (SMC) in the General panel in Configuration options
Product type	Developer Edition, Workgroup Edition, or Enterprise Edition
Operating system	The platform for your Designer and server (NT, Linux, or UNIX platform)
Database platform for SilverMaster	The DBMS you are using for your SilverMaster
Database	Type or types of DBMSs you are using with the SilverStream server, including versions
Database driver	The type and version of the database driver you are using
Browser and Designer configuration	Whether the Designer and browser are running on the same machine
Browser	The version of Internet browser you are using
Java Virtual Machine version (JVM)	Display the version of your JVM by starting the SilverStream server with the -jvmversion startup option
Proxy servers and firewalls	Whether you are using a proxy server or firewall in your system configuration

In addition, be prepared to provide the following information about the problem you have:

• Does the problem occur in the development environment or at runtime?

• What was the specific action that caused the error?

• What exact error message did you see?

• Can the problem be recreated consistently?

• What are the exact steps to recreate the error? Please be prepared to provide an example.

Installation Guide

Copyright © 2001, SilverStream Software, Inc. All rights reserved.