Getting Started

This chapter provides information about the requirements for running DirX Identity Web Center and how to prepare your development environment.

Deploying Web Center

This section describes how to deploy Web Center using the DirX Identity Configuration program and how to deploy multiple Web Center instances manually.

Deploying Web Center with the DirX Identity Configuration Program

Web Center is usually deployed into Tomcat with the DirX Identity Configuration program.Since Web Center requires Tomcat 8.5 or 9.0 running with Java 11, make sure that an appropriate Tomcat is installed and runs with Java 11 before starting the Web Center configuration.

After you install and configure DirX Identity, you will find the Web Center application in the folder install_path/web/webCenter-domain/webCenter.

The context descriptor file webCenter-domain.xml serves to integrate the Web Center application into Tomcat.The file must be located in Tomcat’s context descriptor folder.The exact name of the folder depends on Tomcat configuration details.The general name scheme is tomcat_home/conf/enginename/hostname.On most servers, the folder is named tomcat_home/conf/Catalina/localhost or tomcat_home/conf/Standalone/localhost.

The context descriptor file contains a Context element with a docBase attribute pointing to the Web Center installation directory, for example

<Context docBase="C:/Program Files/DirX/Identity/web/webCenter-My-Company/webCenter" …>

The DirX Identity Configuration creates the file and fills in the correct docBase. The docBase points to the folder install_path/web/webCenter-domain/webCenter.

The configuration program changes some settings in web.xml (like LDAP server address and domain name) and password.properties.

The DirX Identity Configuration also copies the jar file dxmStorageURL.jar to folder tomcat_home/dxilib. The folder is created if not yet existing. The jar file is added to Tomcat’s Java classpath.

On Windows systems where Tomcat is installed as a Windows service the configuration program stops and restarts the service.

After configuration, check that the context descriptor file has been created and refers to the correct document base. Check the content of web.xml and password.properties. Make sure that the dxilib folder exists and contains the required library and that Tomcat’s Java classpath has been updated. And finally check that Tomcat is up and running. If not, start it.

To start Web Center, just open a browser (supported are reasonably new versions of Edge, Internet Explorer, Firefox and Chrome) and enter the URL

http://localhost:8080/webCenter-domain

Host name, port and scheme (http or https) may vary depending on Tomcat configuration. The application path (webCenter-domain) is identical to the name of the context descriptor file. If you rename the file to myWebCenter.xml and use HTTPS on port 8443, the URL changes to

https://localhost:8443/myWebCenter

Deployment of Web Center via the DirX Identity Configuration may fail (in parts or totally) for example due to missing permissions to create or modify files in the Tomcat installation folder or insufficient access rights to stop and start the Windows service.

Deploying Web Center Manually

You can manually deploy another Web Center instance

  • Into the same Tomcat server the default instance is deployed into.

  • Into a different Tomcat server on the same machine.

  • Into a Tomcat server on another machine. You don’t even need to install DirX Identity on this machine.

To deploy a Web Center instance manually:

  • Stop Tomcat.

  • On the machine with the Tomcat server, create a new Web Center application directory webCenter_app_path (Don’t create it in Tomcat’s webapps folder).

  • Copy the application folder webCenter from the folder install_path/web/webCenter-domain to webCenter_app_path. Note that install_path refers to the DirX Identity installation folder, which may reside on a different machine.

  • Copy the context descriptor file webCenter.xml from folder install_path/web/webCenter-domain to Tomcat’s context descriptor folder; for example, tomcat_home/conf/Catalina/localhost.

  • Edit file webCenter.xml. Fill in the correct value for the docBase attribute of the Context element:

    <Context docBase="webCenter_app_path/webCenter" …>

  • Navigate to the directory webCenter_app_path/webCenter/WEB-INF.

  • In file web.xml, configure the LDAP server connection and the DirX Identity domain.

  • In file password.properties, enter the password for the domainAdmin user of your Provisioning domain with the key ldap.

  • Create the folder tomcat_home/endorsed if it doesn’t exist already.

  • Copy the following file to folder tomcat_home/dxilib:

    • install_path/webCenter-domain/endorsed/lib/dxmStorageURL.jar

  • Add the jar file to Tomcat’s Java classpath.

  • Make sure that the Tomcat server has the access rights to load the libraries in the dxilib folder and in Web Center’s WEB-INF/lib folder and to read the files of the Web Center application and the context descriptor file.

  • Start Tomcat.

Now you can access your Web Center instance with the URL

http://localhost:8080/webCenter

Deploying Additional Web Center Instances

You can deploy additional Web Center instances into the same Tomcat service by just copying the context descriptor webCenter.xml to a new context path; for example, webCenterCust.xml.

If you don’t change the docBase in the new file, both instances will use the same application folder so that changes to the files in the application folder affect both instances.The only good reason to deploy two applications this way is to assign different values to the configuration parameters (like Struts configuration file names) in the new deployment descriptor.

You may as well copy the application folder of the first instance and let the docBase in the new instance’s context descriptor point to the new folder.This way, changes to one application folder don’t affect the other application.

Note that Tomcat monitors the context descriptor folder.On detection of a new context descriptor, Tomcat loads the new application.On detection of a changed context descriptor (new modification date), Tomcat reloads the affected application.

Therefore, Tomcat will automatically load the new Web Center instance after a short time, and you can access it via the URL

http://localhost:8080/webCenterCust

Preparing the Development Environment

To set up an environment for Web Center development, we recommend that you start Tomcat as a console application rather than running it as a service.The advantages of running Tomcat as console application are:

  • You can start Tomcat faster by double-clicking the Tomcat icon on the desktop.

  • You can stop Tomcat faster by closing the Tomcat window.

  • You can view debug messages in the Tomcat console window.

  • You can view error messages caused by syntax errors in the configuration files.

To run Tomcat as a console application:

  • Stop the Tomcat service.

  • Change the startup type of the service to manual.

  • Navigate to folder tomcat_home/bin.

  • Create a shortcut for tomcat8.exe or tomcat9.exe.

  • Place the shortcut on the desktop.

Next, create a copy of your Web Center default installation as described in the section “Deploying Web Center". Using a copy of the Web Center installation allows you to configure Web Center without changing the original product.

In the file WEB-INF/web.xml, enable debug mode by setting the context parameter com.siemens.webMgr.log.level to level 2:

<context-param>
    <!-- Allowed debug switches: 0=SEVERE,1=INFO,2=FINEST,
                                 3=WARNING,-2=log4j.properties -->
    <param-name>com.siemens.webMgr.log.level</param-name>
    <param-value>2</param-value>
</context-param>