Creating an instance by using the Configuration Manager

Every WebSphere Commerce installation requires at least one instance to function. Create an instance, and then create and deploy stores to your WebSphere Commerce server.

Warning:
  • WebSphere Commerce instance creation is not supported with WebSphere Commerce fix packs that require Java 8 until version 8.0.4.30. If you need to create a new WebSphere Commerce instance, you must use WebSphere Commerce 8.0.4.30 or greater. Alternatively, you can use an older Java 7 fix pack, such as 8.0.4.25, before upgrading to Java 8 and a more recent WebSphere Commerce fix pack.
  • For IBM i OS operating systemNew instance creation is not supported on IBM i.
Note: If you are creating an instance as part of a migration from WebSphere Commerce Version 7.0, the following instance properties must match your version 7.0 instance:
  • Instance name
  • Merchant key
  • Database name
  • Default language
  • Web server configurations
To verify your version 7.0 instance properties, review your createInstance.properties file, under your WC_installdir/instances/instance_name/properties/ directory of your version 7.0 environment.

WebSphere Commerce supports the creation of multiple WebSphere Commerce instances. However, you cannot create more than one instance at a time. Attempting to create multiple instances at the same time can cause errors.

  • WebSphere Commerce instances have global security enabled by default during the instance creation process.
    Important: WebSphere Application Server administrative security is enabled, but application security is disabled by default for performance reasons. The primary administrative user is a user from the built-in file registry. The instance creation process creates the user by initially taking the credentials that you used to login to the Configuration Manager. You can change the primary administrative user in the WebSphere Application Server Administrative Console.

    When you need to stop the WebSphere Commerce application, you must use the user name and password. For example, if you are using the stopServer script, you must provide the -username and -password arguments.

  • You are not required to create the WebSphere Application Server Administrative Console profile before you create your WebSphere Commerce instance. The Configuration Manager automatically creates the WebSphere Application Server Administrative Console profile that is used by the WebSphere Commerce instance.
You can use the following table to record your instance information so that you have the information handy.
Object Instance variable New instance variable
WebSphere Commerce instance name WC_instance
IP address xxx.xxx.xxx.xxx
Host name host
Domain name domain
Fully qualified host name host.domain
WebSphere Commerce database name WC_db
WebSphere Commerce data file name Oracle_datafile
WebSphere Commerce database user ID Oracle_user
WebSphere Commerce table space name WC_instanceTBLSPC
If you have an existing instance, you do not have to modify any of the parameter values for that instance in order to add an instance. You might want to modify some parameters of your original instance in order to better organize your multi-instance environment.

Before you begin

  1. Review the information in the following topic, Database considerations during WebSphere Commerce instance creation.
  2. If you are using a remote Configuration Manager client, it must be at the same level as the Configuration Manager server.
  3. If you plan to start the Configuration Manager from a remote Configuration Manager machine, disable the firewall on the Configuration Manager server machine.
  4. If your web server is remote from your WebSphere Commerce server, you must create a directory to hold the web server configuration files and log files:
    1. Although any directory name can be used, it is recommended that you create the following directory:
      • WindowsWC_installdir\instances\instance_name.
      • LinuxWC_installdir/instances/instance_name.
      • AIXWC_installdir/instances/instance_name.
      • For IBM i OS operating system/QIBM/UserData/CommerceServer80/instances/instance_name.
      Note: When you create your instance through the WebSphere Commerce instance creation wizard, the path must be entered in the Remote Configuration Directory field of the Web server panel.
      Where:
      instance_name
      This variable represents the name of the WebSphere Commerce instance with which you are working (for example, demo).
    2. Your FTP and NFS users must have write permissions for these locations.
  5. LinuxAIXThe systems on which you are starting the Configuration Manager server and the Configuration Manager client use a supported locale. Ensure that the locale of the non-root user with which you are starting the Configuration Manager server and the Configuration Manager client use a supported locale.
  6. LinuxAIXWindowsEnsure that you started your WebSphere Commerce database server.
  7. LinuxAIXDB2WindowsEnsure that the DB2 Fenced user group is assigned to the DB2 user ID.
  8. Ensure that you apply the most recent WebSphere Commerce maintenance package. For information about the latest maintenance packages, see Latest maintenance packages for WebSphere Commerce.
  9. LinuxAIXDB2 The non-root user must be added to the db2_instance_group on the client side. Verify that your non-root user is part of the DB2 instance group by running the following commands:
    id non-root-user
    Ensure that the db2 instance group is on the list. If not, run the following command to fix it:
    WC_installdir/bin/wcnonroot.sh
    If you are using a remote database, make sure that the non-root user is part of the db2 instance group on the WebSphere Commerce node.
  10. DB2Ensure that the WebSphere Commerce non-root user is part of the DB2 user group
  11. WindowsOracleIf you want to use an Oracle database, ensure that Oracle HTTP service is stopped before you create your instance.
  12. WebSphere Commerce Version 8.0.4.0If you want to use an Oracle 12cR2 database, you must configure your environment to use ojdbc7 and libocijdbc12 drivers.
    1. Download the oracle instant client 12.1.0.2.0 zip file.
    2. Unzip the install client 12.1.0.2.0 zip file in temp directory.
    3. Copy the ojdbc7.jar file to your ORACLE_HOME/jdbc/lib/ directory.
    4. Copy the libocijdbc12.so file to your ORACLE_HOME/jdbc/lib/ directory.
    5. Open your WC_installdir/bin/setenv.sh file for editing.
    6. Search for all instances of the ORACLE_HOME/jdbc/lib/ojdbc6.jar, then update the values to point to the ojdbc7.jar file. For example, ORACLE_HOME/jdbc/lib/ojdbc7.jar.
  13. For IBM i OS operating systemIf you want to configure your IBM i system to use a remote database instead of a local database, complete the following steps.
    1. Start the DDM TCP/IP server on the remote IBM i system by completing one of the following steps:
      • In the System i Navigator on your remote IBM i system, use the Network option.
      • Run the following command: STRTCPSVR SERVER(*DDM)
      Note: When the DDM server and the native JDBC driver are used, the QCCSID system value must be a valid CCSID other than 65535.
    2. Ensure that the DDM server is running on your IBM i system. To do so, check for job QRWTLSTN in subsystem QSYSWRK.
    3. Ensure that there is an entry for the remote database where the schema for your instance will be created. To do so, on the IBM i system where WebSphere Commerce is installed, run the WRKRDBDIRE command.
    4. On the IBM i system where WebSphere Commerce is installed, run the following command: 
      RUNJVA CLASS(com.ibm.db2.jdbc.app.DB2PackageCreator) PARM('database_name' 'user' 'password')
      Where:
      database_name
      The name of the database where the schema for the instance will be created. On this remote system, use the WRKRDBDIRE command and record the Relational Database value that is defined as *LOCAL.
      user
      A profile with authority to create new objects on the remote IBM i system.
      password
      The password that is associated with the user.

      The command opens a Java Shell Display. The following message displays after the command completes: Java program completed

    5. Create a user profile on the remote system. The user profile must have the same name as the WebSphere Commerce instance that you are creating. Configure the user profile so that the language settings match the language you intend to choose as the default language for your WebSphere Commerce instance.
      Note: The password for the user profile must be the same as on the *LOCAL system (the machine where WebSphere Commerce is installed). This is the password that will be entered in the Instance Logon Password field of the Schema page when you use the Configuration Manager to configure your instance.
    6. Ensure that the user profile for the instance you just created has authority to access the *SQLPKG objects in library QGPL. To do so, run the following command:
      GRTOBJAUT OBJ(QGPL/*ALL) OBJTYPE(*SQLPKG) USER(instance_name) AUT(*CHANGE)
  14. For IBM i OS operating systemIf you configured your IBM i system to use a remote database, ensure that you installed the Remote WebSphere Commerce Management Utilities on a Windows PC.

About this task

Important: Modify only the following web server properties, and any WebSphere Commerce related properties, through the Configuration Manager GUI (and not through the web server GUI nor the WebSphere Application Server Administrative Console):
  • SSL (enabling or disabling.)
  • Web server instance name or port number.
  • SSL port number.
    The default SSL port is 443. If you change this port to a different value, you must manually update the following configurations to use your new SSL port.
    • The http.conf and plugin-cfg.xml files.
    • Some store JSP files are hardcoded to use 443 for the HTTPS port.
  • System IP address (Payments server host).
The GUI ensures that all configuration files, not just the web server configuration files, are updated properly with the correct information.

Procedure

  1. LinuxAIX Ensure that you are logged as the WebSphere Commerce non-root user.
  2. Start Configuration Manager.
  3. Expand WebSphere Commerce > hostname > Commerce; then right-click Instance List.
  4. From the resulting menu, select Create Instance. The Instance Creation wizard starts.
  5. Complete each panel of the Instance Creation wizard.
    For more information about the Instance Creation wizard, see WebSphere Commerce Configuration Manager online help by clicking Help.
    Note:
    • OracleAvoid including a dash (or hyphen) in the instance_name. For some WebSphere Commerce features, such as content versioning, the instance_name is used by default to specify the database schema in which applicable database objects are created. Some Oracle Java APIs have problems with the presence of dashes or hyphens in the schema name.
    • You must go to panels by clicking Next or Previous. Clicking the tab is not recommended. If you click the tab, your data might not be validated, which might cause an instance creation failure.
    • WebSphere Commerce Version 8.0.4.0OracleIn the WebSphere Application Server panel, your JDBC Driver Location must point to the ojdbc7.jar, which is under your Oracle JDBC directory. For example, /opt/oracle/product/12.2.0.1/dbhome_1/jdbc/lib/ ojdbc7.jar.
    • To create a production environment, on theStaging panel, ensure that the Use staging server box is cleared. When the box is cleared, a drop-down menu appears where you can select Production.
  6. When you complete the necessary information in the panels, the Finish button is enabled. Click Finish to create the WebSphere Commerce instance.
    The time that is needed to create an instance depends on the speed of your system. You can also verify the progress of the instance creation by checking the following log file:
    WC_installdir/instances/instance_name/logs/createInstanceANT.log

    When instance creation is complete, a dialog box opens that contains a summary like the following example: 

    Commerce instance demo is created under WebSphere Application 
Server profile demo. The WebSphere Application Server administrative console 
port is 9060. Restart your web server to apply the changes to your web server 
configuration file.
  7. Review the summary and record the port number listed. This port is needed to access the WebSphere Application Server administrative console. Click OK to close the dialog box. Other dialog boxes might open that contain more instruction. Ensure that you review the contents of the dialog boxes.
  8. Exit Configuration Manager by selecting Console > Exit.
  9. Consider changing the default WebSphere Application Server isolation level.
    Important: By default most WebSphere Commerce code runs database queries at specified isolation levels that are within safe tolerances for those individual queries. You can ensure optimal performance of your site by setting the default isolation level for WebSphere Application Server to Cursor Stability. For more information about how to set the default level of isolation for WebSphere Application Server, see Changing the default isolation level for non-CMP applications and describing how to do so using a new custom property webSphereDefaultIsolationLevel.

What to do next

Verifying instance creation