Installing WorldServer through Tomcat (on Linux)

Before you begin

  • Make sure that you have downloaded and installed Java 8, which you can find it in the UNIX folder of the WorldServer distribution kit. Tomcat requires javac and jdb to run. Therefore, you must have the full Java SDK installed, not just the JRE.
  • Make sure the $JAVA_HOME environment variable is set and points to the Java SDK installation root.
  • If you are installing on an SQL Server database, but you want to separate the database creation process from the installation process, you must create and populate the WorldServer database before installing WorldServer.
  • If you are installing on an Oracle database, you must create and populate the WorldServer database before installing WorldServer.
  • Depending on your installation, you may need root access. Specifically:
    • If you want the application server to listen on a port lower than 1024, you have to run the application server as root.
    • If you want to install to a standard location (for example, /user/local), you need permissions to create the folder.
    • We recommend creating a separate Linux user to own and manage the WorldServer processes. Creating this user may require root permissions.
    • If you want to configure WorldServer to start automatically on reboot, you need root access to install the necessary startup scripts.

Procedure

  1. Log in to the target machine as root.
    If your system is set up to allow sudo, you may be able to perform these instructions by prepending sudo to each command.
  2. Create a folder for the WorldServer installation, which will be referred to as <WS_HOME>:
    > mkdir /usr/local/idiom/worldserver
  3. Create a user to own the installation and set the user’s home folder to the folder you created earlier.
    This is a convenient way to collect all the WorldServer assets in a single place and to manage them. Depending on how you have set up your network, you may want to create either a local user or a NIS user. To create a local user, run the following command as root:
    > useradd –d /usr/local/idiom/worldserver wrldsrvr
  4. Set the permissions on the folder so that the new user is its owner.
    > chown –R wrldsrvr /usr/local/idiom/worldserver
  5. Log out from root and log in as the wrldsrvr user.
  6. If you are installing from the FTP website, download the following file and copy it into your installation folder:
    ws11.x.<build number>_unix.tar.gz
  7. Extract the contents of the WorldServer distribution kit:
    > cd /usr/local/idiom/worldserver
    > gunzip ws11.x.<build number>.*_unix.tar.gz
    > tar –xvf ws11.x.<build number>.*_unix.tar
  8. To enable the rcs (revision control system) application used by WorldServer, as well as various other executables (for example, wstool and diff), perform the following from the linux/bin folder:
    > chmod a+x *
  9. To ensure that your environment is set correctly every time you log in, SDL provides a sample set of login scripts. Do one of the following:
    • If your default shell is in the sh family, copy the .profile file from the unix folder.
      > cd /usr/local/idiom/worldserver
      > cp unix/.profile /usr/local/idiom/worldserver
    • If your default shell is in the csh family, copy the .login file from the unix folder.
      > cd /usr/local/idiom/worldserver
      > cp unix/.login /usr/local/idiom/worldserver
    You can then use a text editor to modify the contents of this file and provide the correct values for the WS_HOME, JAVA_HOME, and, if applicable, the ORACLE_HOME, XHIVE_HOME, and TZ environment variables. These scripts also define the path to the WorldServer binaries.
  10. Test that the new scripts are working:
    1. Log out of the wrldsrvr account.
    2. Log back in to the wrldsrvr account.
    3. Run the following command:
      > echo $WS_HOME
    The WorldServer installation folder should be displayed. You can now start the WorldServer deployment process.
  11. If you are installing from the network, download the apache-tomcat-8.0.36.tar.gz file and copy it to your <WS_HOME> folder.
  12. Extract the contents of the file to the <WS_HOME> folder:
    > cd $WS_HOME
    > gunzip apache-tomcat-8.0.36.tar.gz
    > tar -xvf apache-tomcat-8.0.36.tar
  13. Copy the WorldServer WAR files to Tomcat.
    > cp ${WS_HOME}/ws.war ${WS_HOME}/apache-tomcat-8.0.36/webapps
    > cp ${WS_HOME}/ws-legacy.war ${WS_HOME}/apache-tomcat-8.0.36/webapps
    > cp ${WS_HOME}/ws-api.war ${WS_HOME}/apache-tomcat-8.0.36/webapps
    The ws.war, ws-api.war, and ws-legacy.war files are placed in the <WS_HOME> folder.
  14. Make sure that your environment is set correctly every time you log in by modifying your login scripts.
    • If your default shell is in the sh family, add the following lines to the /usr/local/idiom/worldserver/.profile file:
      CATALINA_HOME=${WS_HOME}/apache-tomcat-8.0.36
      PATH=${CATALINA_HOME}/bin:${PATH}
    • If your default shell is in the csh family, add the following lines to the /usr/local/idiom/worldserver/.login file:
      > setenv CATALINA_HOME ${WS_HOME}/apache-tomcat-8.0.36
      > setenv PATH ${CATALINA_HOME}/bin:${PATH}
    Log out, and then log back in for the setting to take effect.
  15. Go to apache-tomcat-8.0.36/bin and start Tomcat to extract the contents of the ws.war, ws-api.war, and ws-legacy.war files. On the first run, you may need to set execute permissions on the .sh files.
    > cd $CATALINA_HOME/bin
    > chmod 777 *.sh
    > ./startup.sh
    Tomcat automatically unpacks the contents of the ws.war, ws-api.war, and ws-legacy.war files.
  16. Stop Tomcat.
    > ./shutdown.sh
    At this point, WorldServer has been deployed.
  17. Configure the WorldServer .properties files.
  18. Restart the WorldServer service.

Results

You have now finished installing the components needed for WorldServer to function at a basic level.

What to do next

At this point, you can make various other configurations or you can proceed to installing the Report Center and the File Type Support (FTS) Server.