9 2:Production environment on Linux

From Pnet-Community

Jump to: navigation, search

Contents

[edit] Installing Project.net on a Linux System

This document guides a user through the process of installing Project.net, version 9.2.*, on a Tomcat 6.0 application server running on a Lin*x system. In addition to the application server, a Project.net installation will also require: web server, database server, mail (SMTP) server, document vault (file server) and LDAP server (optional).

[edit] Review checklist of requirements

Please review the complete list of hardware and software requirements as described in Project.net Deployment Requirements. Make sure you can meet these requirements before installing Project.net. You will also need to read Installing Project.net.

[edit] Unpack the Project.net Installation Package

The installation package includes the Project.net software in a zip archive file. The first step to installing Project.net is to unpack the software onto an accessible file location.

  1. If it does not exist, create a temporary directory to unpack the installation package, suggested /tmp/pnet, /var/tmp or /opt/pnet. These instructions will refer to this location throughout the steps.
  2. Unzip the zip file from your download into the directory chosen above. Once unpacked, you will have /tmp/pnet/v9.2.0_OS directory.

[edit] Install and configure the Oracle database server

Project.net requires an Oracle database server. Follow the instructions in this section to install and configure an Oracle database server, if one is not prepared.

[edit] Prerequisites

[edit] Instructions

  1. Install Oracle 10.2 Enterprise or Express Edition.

[edit] Create and configure the Project.net database

This section will guide you through the steps of creating the tables, stored procedures and such for the Project.net database.

[edit] Prerequisites

  • An Oracle database server, installed as above.
  • A working copy of sqlplus. Normally, this is installed with the Oracle database, but if not, the Oracle instant client is sufficient.
  • The system password for the Project.net database instance.
  • You will need to know the database server’s hostname.

[edit] Instructions

After you have downloaded Oracle xe just run following commands as a root user and answer for some questions about admin passwords and Oracle starting at boot:

  1. Install Oracle XE via RPM or DEB depending on your Linux distribution
  2. Run "/etc/init.d/oracle-xe configure" to configure Oracle
  3. Specify the HTTP port that will be used for Oracle Application Express [8080]:8080
  4. Specify a port that will be used for the database listener [1521]:1521
  5. Specify a password to be used for database accounts. Note that the same password will be used for SYS and SYSTEM. (* make sure you remember this password *)
  6. Do you want Oracle Database 10g Express Edition to be started on boot (y/n) [y]: y

To access the Database Home Page go to “http://127.0.0.1:8080/apex”. Now you have installed Oracle Express Edition on your server.

  1. Insert into /etc/profile
    ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server
    export ORACLE_HOME
    export ORACLE_SID=XE
    export NLS_LANG=AMERICAN.AL32UTF8
    export PATH=$PATH:$ORACLE_HOME/bin
  2. Check TNS connect identifier with tnsping <database SID>.
  3. Also, check that sqlplus system/<database admin password>@<database name> connects.

Configuration and creation of the Oracle database.

  1. Change directory into the /tmp/pnet/v9.2.0_OS/database/create-scripts/versions/9.2.0/new/ directory.
  2. Using the editor, edit the pnetMasterDBBuild.sh file. Set the environment variables in this script to be appropriate for your installation. Further instructions are available in the file.
    • Important Notes:
      • The database scripts were created on a Windows system. If you are installing on a Lin*x-based system you may need to convert the end-of-line characters from Windows-format to Lin*x-format so the scripts will run correctly. dos2unix is a handy utility to do this for you, it should be already installed on your Lin*x system.
      cd <Install package>/database
      find . -type f -exec dos2unix {} \;
      • The PNET_BUILD_DB_SCRIPTS_PATH should be set to /tmp/pnet/v9.2.0_OS/database/create-scripts/versions/9.2.0/new/ directory.
      • If you are using Oracle Express set the PNET_BUILD_DB_DATABASE_NAME variable to the value XE.
      • The directory specified for PNET_BUILD_DB_LOG_PATH must exist; create it if it does not. Suggested is /tmp/pnet_logs.
      • The PNET_BUILD_DB_DATAFILE_PATH should be set to the directory where Oracle keeps the database - it will be in the oradata directory in the Oracle folder area (ex. /usr/lib/oracle/xe/oradata/XE/)
      • Change the default password for the system account PNET_BUILD_SYSTEM_PASSWORD=manager (ex. PNET_BUILD_SYSTEM_PASSWORD=mysyspass)
      • Change the default password for the schema owner PNET_BUILD_USER_PASSWORD=pnet (ex. PNET_BUILD_USER_PASSWORD=mypass)
      • Change the default password for the database user PNET_BUILD_APP_USER_PASS=pnet_user (ex. PNET_BUILD_APP_USER_PASS=mypass)
  3. To start the database installation, run the batch command pnetMasterDBBuild.sh from the database/create-scripts/versions/9.2.*/new directory. The script will take some time to run; you can monitor its progress by checking the log file you specified inside of pnetMasterDBBuild.
  • If the script fails and you need to re-run it to clean everything up before trying again.
    a. Go to the database/create-scripts/tools folder
    b. Start Sqlplus with sqlplus pnet/<pnet password>@<database SID>
    c. Drop the existing database with @drop_pnet_and_user_schemas.sql

[edit] Install and Update Java Runtime Environment

[edit] 5.1: Install the Java 6.0 Runtime Environment

[edit] Prerequisites

[edit] Instructions (Linux installations)

The installation instructions for Linux systems will vary depending upon the version of Linux in question. Follow the installation instructions for your specific operating system. After you downloaded the java JRE , extract it in some folder, for example in /opt/jvm

  1. Insert the following lines inside /etc/profile
    export JAVA_HOME=/opt/jvm/jre<jre_version>
    export PATH=$PATH:$JAVA_HOME/bin
  2. Save the change and do the following
  3. source /etc/profile

[edit] 5.2: Update the Java Security for Strong Encryption

[edit] Prerequisites

[edit] Instructions

  1. Copy /tmp/pnet/v9.2.0_OS/lib/jce6/*.jar to the jre/lib/security directory of the Java runtime location.
  • Place the files directly into the security directory, overwriting any existing files that conflict.

[edit] Install and Configure the Apache Tomcat Server

This section outlines the Apache Tomcat installation and configuration for a production deployment of the Project.net application.

[edit] 6.1: Install the Tomcat Application Server

[edit] Prerequisites

  • A copy of Apache Tomcat as specified in the Summary of Project.net 9.2.* Deployment Requirements.
  • Java Runtime Environment 6.0 as specified in the Project.net Deployment Requirements

[edit] 6.1.2 Instructions (Linux installations)

  1. If you have already downloaded the binary, simply copy it to the directory you want to install it under and expand the file. For example, if the downloaded Tomcat tar file is in /home/someuser/downloads, to install it under /opt, follow these steps. As root user:
    cp /home/someuser/downloads/apache-tomcat-6.x.xx.tar.gz /opt
    tar -zxvf apache-tomcat-6.x.xx.tar.gz
  2. A directory called apache-tomcat-6.0.xx will be created and the Tomcat files will expanded under it. You may want to create a symbolic link to a the /opt/tomcat directory for easier upgrades and configuration.
    ln -s /opt/apache-tomcat-<tomcat-version> /opt/tomcat
  3. To Start tomcat
    $CATALINA_HOME/bin/startup.sh
  4. If Tomcat does not start and you downloaded the zip file, the cause is probably due to permissions. Ensure that the following files are executable : inside $CATALINA_HOME/bin directory,
    chmod +x startup.sh
    chmod +x shutdown.sh
    chmod +x tomcat.sh
  5. To Stop tomcat
    $CATALINA_HOME/bin/shutdown.sh

[edit] 6.2: Configure Tomcat application server

[edit] Prerequisites

  • Apache Tomcat installed as above.
  • A user name and password for the Tomcat Manager.
  • For more information on configuring and administering Apache Tomcat 6.0, see the following documentation:Tomcat Setup

[edit] Instructions

  1. Activate Tomcat Manager
  • Sample "tomcat-users.xml" file with a new user named "manager" and "manager" role associated with it (Note: it is strongly recommended that you use secure passwords in place of those listed below):
    <?xml version='1.0' encoding='utf-8'?>
    <tomcat-users>
    <role rolename="tomcat"/>
    <role rolename="role1"/>
    <role rolename="manager"/>
    <user username="tomcat" password="tomcat" roles="tomcat"/>
    <user username="role1" password="tomcat" roles="role1"/>
    <user username="manager" password="manager" roles="manager"/>
    </tomcat-users>


  • Add Libraries for Tomcat 6.0
  1. Copy /tmp/pnet/v9.2.0_OS/lib/mail.jar and /tmp/pnet/v9.2.0_OS/lib/activation.jar to CATALINA_HOME/lib.
  2. Copy /tmp/pnet/v9.2.0_OS/lib/jdbc/ojdbc14.jar to CATALINA_HOME/lib.
  3. Create the CATALINA_HOME/endorsed folder and copy serializer.jar, xalan.jar, xercesImpl.jar and xml-apis.jar from /tmp/pnet/v9.2.0_OS/lib/endorsed.
  • Change the port of Tomcat 6.0
  1. Edit the tomcat/conf/server.xml
  2. Change the port to 9090
  3. Restart tomcat

[edit] 6.3 Setting Java parameters

In order to ensure reliable service the Java virtual machine (JVM) will need to have its parameters tuned.

  • The Xmx parameter controls the maximum heap size the JVM can address.
    • For a development or test server -Xmx512m (512 MB) will be OK.
    • For a production server, the value should be at least -Xmx1024m (1024 MB), but not more than 3/4 the amount of RAM installed in the system.
    • On a 32-bit operating system it cannot exceed -Xmx2048m (2 GB)
  • The Xss parameter controls the stack size for the JVM.
    • Use -Xss128k for a 32-bit operating system.
    • Use -Xss256k if the system has a 64-bit JVM, like HP-UX or IBM-AIX.

[edit] Instructions (Linux systems)

  • Add the following lines near the top of TOMCAT_HOME/bin/catalina.sh
  if [ -z "$JAVA_OPTS" ]
  then
  JAVA_OPTS="-Xms256m -Xmx<see above>m -XX:MaxPermSize=384m -Xss<see    
  above>k -Djava.awt.headless=true"
  else
  JAVA_OPTS=${JAVA_OPTS}" -Xms256m -Xmx<see above>m -XX:MaxPermSize=384m   
  -Xss<see above>k -Djava.awt.headless=true"
  fi
  • You need to use this line if you are using following java versions "1.6.0_26, 1.6.0_27 ..... 1.6.0_31"

JAVA_OPTS="-server -Djava.awt.headless=true -Xms256m -Xmx<>m -XX:MaxPermSize=384m -Xss<>k"

[edit] 6.4 Configure Tomcat logging (Optional)

[edit] Prerequisites

http://commons.apache.org/downloads/download_logging.cgi

[edit] Instructions

Turning on logging is an optional step but will come in handy when monitoring or troubleshooting your server; logging can be activated at any time, but it requires restarting Tomcat. Finally, the default level of logging is DEBUG, which is very verbose, you will want to change this to WARN or ERROR when creating the log4j.properties configuration file described below.

  1. Follow the four steps for configuring Logging in Tomcat http://tomcat.apache.org/tomcat-6.0-doc/logging.html

[edit] 6.5 Configure Tomcat to automatically start on boot-up

The production configuration strategy is to have the Tomcat server run as a Lin*x service, while the Project.net application is managed and restarted by Tomcat. This will allow Project.net to automatically start when the host system boots up and automatically restart if it ever fails.

This is an example of a tomcat6 init script for Linux:

 
#!/bin/sh
#
# Startup script for Tomcat 6.0, the Apache Servlet Engine
#
# chkconfig: - 80 20
# description: Tomcat 6
# processname: tomcat
# pidfile: /var/run/tomcat6.pid
# config:
#

# Source function library.
if [ -x /etc/rc.d/init.d/functions ]; then
. /etc/rc.d/init.d/functions
fi

# Get Tomcat config

# PID_FILE - must match CATALINA_PID in catalina.sh
PID_FILE=/opt/apache-tomcat/bin/startstop.pid

# Path to the tomcat launch script (direct don't use wrapper)
TOMCAT_SCRIPT=/opt/apache-tomcat/bin/catalina.sh

# Tomcat name
TOMCAT_PROG=tomcat

# SYSTEM lock file
SYSTEM_LOCK_FILE=/opt/apache-tomcat/bin/startstop.lock

# How long to wait for shutdowns
SHUTDOWN_WAIT=15

# if TOMCAT_USER is not set
if [ -z "$TOMCAT_USER" ]; then
    TOMCAT_USER="pnet"
fi

# Since the daemon function will sandbox $tomcat
# no environment stuff should be defined here anymore.

RETVAL=0

# See how we were called.
start() {
    echo -n "Starting $TOMCAT_PROG: "

        if [ -f $SYSTEM_LOCK_FILE ] ; then
                if [ -f $PID_FILE ]; then
                        read kpid < $PID_FILE
                        if checkpid $kpid 2>&1; then
                                echo "process allready running"
                                return -1
                        else
                                echo "lock file found but no process running for pid $kpid, continuing"
                                /bin/rm -f $SYSTEM_LOCK_FILE $PID_FILE
                        fi
                fi
        fi

        export CATALINA_PID=$PID_FILE

        if [ -x /etc/rc.d/init.d/functions ]; then
                daemon --user $TOMCAT_USER $TOMCAT_SCRIPT start
        else
                su - $TOMCAT_USER -c "$TOMCAT_SCRIPT start"
        fi

        RETVAL=$?
        echo
        [ $RETVAL = 0 ] && touch $SYSTEM_LOCK_FILE
        return $RETVAL
}

stop() {
    echo -n "Stopping $TOMCAT_PROG: "

    if [ -f $SYSTEM_LOCK_FILE ] ; then
      if [ -x /etc/rc.d/init.d/functions ]; then
          daemon --user $TOMCAT_USER $TOMCAT_SCRIPT stop
      else
          su - $TOMCAT_USER -c "$TOMCAT_SCRIPT stop"
      fi
      RETVAL=$?

      if [ $RETVAL = 0 ]; then
        count=0;

        if [ -f $PID_FILE ]; then

            read kpid < $PID_FILE
            let kwait=$SHUTDOWN_WAIT

            until [ `ps --pid $kpid | grep -c $kpid` = '0' ] || [ $count -gt $kwait ]
            do
                echo "waiting for processes to exit";
                sleep 1
                let count=$count+1;
            done

            if [ $count -gt $kwait ]; then
                echo "killing processes which didn't stop after $SHUTDOWN_WAIT seconds"
                kill -9 $kpid
            fi
        fi

        rm -f $SYSTEM_LOCK_FILE $PID_FILE
    fi

    fi
}


# See how we were called.
case "$1" in
  start)
        start
        ;;
  stop)
        stop
        ;;
  restart)
        stop
        sleep 2
        start
        ;;
  condrestart)
        if [ -f $PID_FILE ] ; then
                stop
                start
        fi
        ;;
  *)
        echo "Usage: $TOMCAT_PROG {start|stop|restart|condrestart}"
        exit 1
esac

exit $RETVAL

The init script should be edited for your environment and should go into /etc/init.d/ (for almost all linux distribution) and then you should set it to start at boot using your distribution command (chkconfig, update-rc.d, rc-update, etc.) or manually create symbolic links in /etc/rc.X

[edit] Install Apache ActiveMQ

On the application server:

  1. The JAVA_HOME environment variable must be set to the directory where the Java runtime (JDK or JRE) is installed. If set, the following command should display the path to the Java runtime: echo $JAVA_HOME
  2. The java binary from JAVA_HOME should be available in the PATH variable, you can check if it's set by running echo $PATH and look for the path to the $JAVA_HOME/bin directory. In case a wrong version of java is in the path (such as for example gcj) please remove it.
  3. Download the latest stable Unix/Linux/Cygwin distribution of activemq from http://activemq.apache.org/download.html
  4. Extract the tarball in /opt or at a location of your choice
  5. To install it as a service daemon follow these steps:
a. Go into the installation directory where you've unpacked the activemq tarball for example /opt/apache-activemq-5.3.2
b. In case you are running a 32 bit Linux installation edit the following files:
  • Change the ACTIVEMQ_HOME in <apache_activemq_install_dir>/bin/linux-x86-32/activemq to point to your <apache_activemq_install_dir>, for example ACTIVEMQ_HOME=/opt/apache-activemq-5.3.2
  • Change both set.default.ACTIVEMQ_HOME and set.default.ACTIVEMQ_BASE in <apache_activemq_install_dir>/bin/linux-x86-32/wrapper.conf to point to your <apache_activemq_install_dir>, for example set.default.ACTIVEMQ_HOME=/opt/apache-activemq-5.3.2 and set.default.ACTIVEMQ_BASE=/opt/apache-activemq-5.3.2
c. In case you are running a 64 bit Linux installation edit the following files:
  • Change the ACTIVEMQ_HOME in <apache_activemq_install_dir>/bin/linux-x86-64/activemq to point to your <apache_activemq_install_dir>, for example ACTIVEMQ_HOME=/opt/apache-activemq-5.3.2
  • Change both set.default.ACTIVEMQ_HOME and set.default.ACTIVEMQ_BASE in <apache_activemq_install_dir>/bin/linux-x86-64/wrapper.conf to point to your <apache_activemq_install_dir>, for example set.default.ACTIVEMQ_HOME=/opt/apache-activemq-5.3.2 and set.default_ACTIVEMQ_BASE=/opt/apache-activemq-5.3.2
d. Create a soft-link for the activemq daemon to your daemon init script directory:
  • If you are running on 32 bit Linux Installation: ln -s /<apache_activemq_install_dir>/bin/linux-x86-32/activemq /etc/init.d/activemq
  • If you are running on 64 bit Linux Installation: ln -s /<apache_activemq_install_dir>/bin/linux-x86-64/activemq /etc/init.d/activemq
e. Set the service to start automatically when the system boots up: chkconfig --add activemq
f. Startup the activemq using service activemq start
g. Check in the logs that activemq started successfully: tail /<apache_activemq_install_dir>/data/wrapper.log
h. You should have a message "INFO TransportConnector - Connector vm://localhost Started"

For more information please visit the ActiveMQ website at http://activemq.apache.org

[edit] Deploy Project.net to Tomcat Server

[edit] Prerequisites

  • Apache Tomcat installed as above.
  • Administrator's (manager) password for Tomcat installation.
  • Edit CATALINA_HOME/config/context.xml to configure the database connection pool and the connection to the SMTP mail server.
    <Context debug="5" reloadable="true" crossContext="true">
    <Resource name="jdbc/PnetDB" auth="Container"
    type="javax.sql.DataSource" username="pnet_user" password=" <pnet_user password>"
    driverClassName="oracle.jdbc.OracleDriver" url="jdbc:oracle:thin:@<dns of db listener>:<listener port>:<db SID>"
    maxActive="125" maxIdle="25"/>
    <Resource name="mail/PnetSession" auth="Container"
    type="javax.mail.Session"
    mail.smtp.host="<SMTP host>"/>
    </Context>
  • Start Tomcat
    • Linux - CATALINA_HOME/bin/startup.sh
  • Note:
    • In the default oracle-xe configuration the <listener port> is 1521, the Web Application port is 8080.

[edit] Instructions (Manual Deployment)

  1. If you want to deploy application as ROOT, delete the existing CATALINA_HOME/webapps/ROOT folder since the Project.net application will be associated with the / URL and will be installed in this folder.
  2. Copy /tmp/pnet/v9.2.0_OS/app/pnet.war to CATALINA HOME\webapps directory, this will install Project.net in the pnet context. To deploy as the default application, rename pnet.war to ROOT.war or, if you want to deploy the application as a different context, rename war file as <Your desired application name>.war.
  3. Start Tomcat, or restart it if it is running.
  4. Wait a minute, then log into !http://localhost:9090/<Your desired application name>/ OR http://localhost:9090/ ( if application is deployed as ROOT.war ) as appadmin.

[edit] Instructions (Using Tomcat Manager)

Project.net cannot be deployed as the default or Root application using the Tomcat Manager, since the Manager runs as the default application.

  1. Log into http://localhost:9090/manager/html/, use Username 'manager' and the password you defined in Step 7 (the default is 'manager').
  2. Browse WAR file to upload. If you want to deploy application as NON-ROOT context you can rename war file as <Your desired application name>.war.
  3. Log into !http://localhost:9090/<Your desired application name>/ as user appadmin.

[edit] Web server front-end integration

The final step is to link the Tomcat server to a web server. This is useful if you want Project.net to act as the default (Port 80) website on the system. Using Tomcat's built in web server to handle requests on Port 80 opens a security hole, therefore, you will need to use Apache httpd web server. The web server will handle the requests coming from the user and marshal the appropriate ones to the Tomcat server for processing by the Project.net application.

[edit] Prerequisites

[edit] Instructions (Apache installations)

[edit] Linux

  1. Install and configure Apache2.2 httpd
  2. Enable mod_proxy and mod_proxy_ajp
  3. Integrate apache httpd to tomcat via ajp (add this in your configuration or your desired virtual host)
    # tomcat integration
    ProxyPreserveHost On
    ProxyPass / ajp://<application server dns name>:8009/ min=5 ttl=120 keepalive=On ping=1
    ProxyPassReverse / ajp://<application server dns name>:8009/
  4. Restart Apache

[edit] Configuration and License Properties

Once the servers are set up and the software installed, you must configure a few basic Project.net settings in order to use the application:

  1. Update the application administrator user account
  2. Configure Project.net System Settings
  3. Install the Master License Properties for your Server

Follow Configuration and License Properties to finish these three steps and begin using Project.net.


[edit] More Help

Personal tools