AdvertPRO - Linux Installation

Prerequisites

Linux Distributions

There are many different distributions of Linux based operating systems. Every distribution has its own recommended way of installing and configuring packages. Some parts of these instructions assume that you are working with a Linux distribution that has RPM support, which includes the popular CentOS and Red Hat Linux. For other distributions, you may need to refer to their specific Java and MySQL installation instructions.

Apache Web Server

If you are running Apache Web Server to host other web sites or applications on the same server as AdvertPRO is going to be installed on, please follow these alternate instructions for configuring Apache Tomcat to connect with Apache Web Server using the mod_proxy_ajp module: Apache + mod_proxy_ajp + Tomcat Installation

Step #1: Download Files

AdvertPRO

  1. Open a browser window to: https://services.renegadeinternet.com/download/
  2. Enter your Customer ID and E-mail Address into the form.
  3. Select the operating system your server is running from the Platform list box.
  4. Select the Install package for a clean installation from the Package list box.
  5. Click on the Download Package button to proceed.
  6. Check your e-mail and you should receive an e-mail with a download link within a few minutes.

Java Development Kit

  1. Open a browser window to: http://www.oracle.com/technetwork/java/javase/downloads/
  2. Click on the Download JDK button for JDK 6.
  3. Click on the Download button on the next page.
  4. Select your Platform, which will be Linux if you have 32-bit system or Linux x64 if you have a 64-bit system and then click on the Continue button.
  5. Click on the second link to download the JDK with RPM installer.

Note Note

JDK 1.4 and 1.5 are also supported, however we recommend using JDK 6.0 (1.6.x) for new installations.

Java Libraries

  1. Download the JavaMail 1.4 library from http://www.oracle.com/technetwork/java/javamail-1-4-140512.html.
  2. Download the JAF 1.1 library from http://www.oracle.com/technetwork/java/jaf11-139815.html.

MySQL Database Server

In most cases your distribution of Linux probably already has MySQL included with it. We recommend using that version of MySQL rather than trying to remove it and install a different version. The reason being that the developer of your distribution has certified that version of MySQL to be stable with it. However, if you still wish to download MySQL and install it you may obtain it using the following instructions.

  1. Open a browser window to: http://dev.mysql.com/downloads/mysql/
  2. Select your version of Linux for the Platform.
  3. Download the following MySQL 5.1.x packages making sure to choose (x86, 32-bit) packages for 32-bit systems or if you have a 64-bit system instead choose the (x86, 64-bit) packages:

Note Note

We fully support the MySQL 4.0, 4.1 and 5.0 series, however we recommend using MySQL 5.1 for new installations.

MySQL Connector/J JDBC Driver

  1. Open a browser window to one of the following, depending on your chosen version of MySQL:
  2. Download the TAR Archive package.

Apache Tomcat Server

  1. Open a browser window to: http://tomcat.apache.org/download-60.cgi
  2. Scroll down to the listing for Tomcat 6.0.x.
  3. Download the Binary Distribution labeled Core: tar.gz.

Step #2: Installation

Java Development Kit


chmod 755 jdk-<version>-linux-x64-rpm.bin
./jdk-<version>-linux-x64-rpm.bin

Note Note

You will find more complete installation instructions here: http://www.oracle.com/technetwork/java/javase/index-137561.html#linux

MySQL Database Server


rpm -i MySQL-server-community-<version>.x86_64.rpm
rpm -i MySQL-client-community-<version>.x86_64.rpm
rpm -i MySQL-devel-community-<version>.x86_64.rpm
rpm -i MySQL-shared-community-<version>.x86_64.rpm
rpm -i MySQL-shared-compat-<version>.x86_64.rpm

Note Note

You will find more complete installation instructions here: http://dev.mysql.com/doc/refman/5.1/en/linux-rpm.html

Apache Tomcat Server


mv apache-tomcat-<version>.tar.gz /usr/local
cd /usr/local
tar -xzvf apache-tomcat-<version>.tar.gz
mv apache-tomcat-<version> tomcat
rm -rf apache-tomcat-<version>.tar.gz
cd tomcat
chmod 755 bin/*.sh
cd webapps
rm -rf *
mkdir ROOT

Apache Tomcat APR Library


yum install apr-devel
yum install zlib-devel
cd /usr/local/tomcat/bin
tar -xzf tomcat-native.tar.gz
cd tomcat-native*
cd jni/native
./configure --with-java-home=/usr/java/latest --with-apr=/usr/bin/apr-1-config --with-ssl=no
make
make install

Java Libraries


unzip javamail-<version>.zip
cp javamail-<version>/mail.jar /usr/local/tomcat/lib/mail.jar
unzip jaf-<version>.zip
cp jaf-<version>/activation.jar /usr/local/tomcat/lib/activation.jar

MySQL Connector/J JDBC Driver


tar -xzvf mysql-connector-java-<version>.tar.gz
cd mysql-connector-java-<version>
cp mysql-connector-java-<version>-bin.jar /usr/local/tomcat/lib/mysql.jar

AdvertPRO


cp advertpro-<version>.war /usr/local/tomcat/webapps/ROOT
cd /usr/local/tomcat/webapps/ROOT
/usr/java/latest/bin/jar -xf advertpro-<version>.war
rm -f advertpro-<version>.war

Step #3: Configuration

Environment Variables


export JAVA_HOME=/usr/java/latest
export PATH=$PATH:$JAVA_HOME/bin

Note Note

Consult your operating system documentation to figure out where you need to put system wide environment variables. On most RPM compatible systems, these export commands can be defined in the /etc/profile file. We recommend placing these commands at the very end of that file and also run them in your existing shell so that you don't need to log out and then log back in again for them to take effect!

MySQL Settings

Replace the entire contents of the /etc/my.cnf with the following recommended configuration:


[client]
port            = 3306
socket          = /var/lib/mysql/mysql.sock

[mysqld]
bind-address    = 127.0.0.1
datadir         = /var/lib/mysql
port            = 3306
socket          = /var/lib/mysql/mysql.sock
skip-locking
set-variable    = max_connections=384
set-variable    = key_buffer=64M
set-variable    = table_cache=256
set-variable    = sort_buffer=4M
set-variable    = record_buffer=1M
set-variable    = max_allowed_packet=16M
set-variable    = myisam_sort_buffer_size=64M
set-variable    = thread_cache=8
server-id       = 1
old_passwords   = 1

[mysql.server]
user=mysql
basedir=/var/lib

[mysqld_safe]
err-log=/var/log/mysqld.log
pid-file=/var/run/mysqld/mysqld.pid

[mysqldump]
quick
set-variable    = max_allowed_packet=16M

[mysql]
no-auto-rehash

[isamchk]
set-variable    = key_buffer=128M
set-variable    = sort_buffer=128M
set-variable    = read_buffer=2M
set-variable    = write_buffer=2M

[myisamchk]
set-variable    = key_buffer=128M
set-variable    = sort_buffer=128M
set-variable    = read_buffer=2M
set-variable    = write_buffer=2M

[mysqlhotcopy]
interactive-timeout
        

Note Note

These settings are for MySQL 5.1.x, which is the version we recommend using for new installations. However, they are also compatible with and can be used with the MySQL 5.0.x and 4.1.x versions. If you are using an even older version of MySQL, please contact technical support for configuration guidance if needed.

Apache Tomcat Environment

Edit /usr/local/tomcat/bin/catalina.sh and add the following after the comments/instructions at the top.


# Tomcat Home.
CATALINA_HOME="/usr/local/tomcat"

# Java Home.
JAVA_HOME="/usr/java/latest"

#
# Change -Xms and -Xms if necessary to allocate more or less memory.
# It is important that they have the same value for optimal performance.
# Note that on some operating systems you may need to increase the value of
# -Xss to 512k or higher (do not exceed 1024k) if you experience stability
# problems or start seeing stack overflow exceptions in your application
# server logs.
#
# If you've changed -Xms and -Xms, you should change -XX:NewSize and
# -XX:MaxNewSize to have values equal to half of the -Xms and -Xmx
# values.
#
# Suggested values based on available physical server memory (RAM):
#
#  2 GB RAM    -Xms1024m     -Xmx1024m     -XX:NewSize=512m     -XX:MaxNewSize=512m
#  4 GB RAM    -Xms2048m     -Xmx2048m     -XX:NewSize=1024m    -XX:MaxNewSize=1024m
#  8 GB RAM    -Xms4096m     -Xmx4096m     -XX:NewSize=2048m    -XX:MaxNewSize=2048m
# 16 GB RAM    -Xms8192m     -Xmx8192m     -XX:NewSize=4096m    -XX:MaxNewSize=4096m
# 32 GB RAM    -Xms16384m    -Xmx16384m    -XX:NewSize=8192m    -XX:MaxNewSize=8192m
#
CATALINA_OPTS="$CATALINA_OPTS -server -Xms512m -Xmx512m -Xss128k -XX:+DisableExplicitGC"
CATALINA_OPTS="$CATALINA_OPTS -XX:NewSize=256m -XX:MaxNewSize=256m"

#
# If you're using a multi processor system, uncomment the following
# options and set the value of -XX:ParallelGCThreads equal to the
# number of processors that are in your system.
#
#CATALINA_OPTS="$CATALINA_OPTS -XX:+UseParNewGC -XX:ParallelGCThreads=4"
#CATALINA_OPTS="$CATALINA_OPTS -XX:+UseConcMarkSweepGC -XX:CMSInitiatingOccupancyFraction=80"
#CATALINA_OPTS="$CATALINA_OPTS -XX:SurvivorRatio=128 -XX:MaxTenuringThreshold=0"

#
# APR Connector JNI Library
#
CATALINA_OPTS="$CATALINA_OPTS -Djava.library.path=/usr/local/apr/lib"

#
# Uncomment the following options to help debug garbage collection
# related performance problems.
#
#CATALINA_OPTS="$CATALINA_OPTS -verbose:gc -Xloggc:/usr/local/tomcat/logs/gc.txt -XX:+PrintGCDetails"

#
# Java Options.
#
JAVA_OPTS="$JAVA_OPTS -Djava.awt.headless=true -Dsun.net.inetaddr.ttl=28800 -Dsun.net.inetaddr.negative.ttl=60"

#
# Raise open file limit and stack size.
#
ulimit -n 524288
ulimit -s 2048

Apache Tomcat Settings

Replace the entire contents of the /usr/local/tomcat/conf/server.xml with the following recommended configuration:


<?xml version="1.0" encoding="utf-8"?>

<Server port="8005" shutdown="SHUTDOWN">

  <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="off" />
  <Listener className="org.apache.catalina.core.JasperListener" />
  <Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" />
  <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />

  <GlobalNamingResources>
    <Resource name="UserDatabase" auth="Container"
              type="org.apache.catalina.UserDatabase"
              description="User database that can be updated and saved"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="conf/tomcat-users.xml" />
  </GlobalNamingResources>

  <Service name="Catalina">

    <Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
               acceptCount="128"
               connectionTimeout="10000"
               disableUploadTimeout="false"
               enableLookups="false"
               maxKeepAliveRequests="100"
               keepAliveTimeout="15000"
               maxThreads="512"
               pollTime="2000"
               pollerSize="2048"
               useSendfile="true"
               sendfileSize="1024"
               port="80"
               redirectPort="443"
               URIEncoding="UTF-8"/>

    <Engine defaultHost="localhost" name="Catalina">

      <Host name="localhost" appBase="webapps" unpackWARs="true">

        <Context docBase="ROOT" path="" privileged="false" swallowOutput="true" />

      </Host>

      <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/>

    </Engine>

  </Service>

</Server>
        

Tip Tip

For high traffic sites, you should increase the values of the maxThreads and pollerSize options. If you have 8GB of RAM it's suggested to increase them to 2048 and 8192. When you have 16GB of RAM or more it's recommended to set them to 4096 and 16384.

Note Note

These settings are for Tomcat 6.0.x, which is the version we recommend using. If you are using an older version of Tomcat, please contact technical support for configuration guidance if needed.

Apache Tomcat Startup

Create /etc/rc.d/init.d/tomcat using the following recommended settings.


#!/bin/bash
#
# Startup script for the Tomcat Web Server
#
# chkconfig: 345 92 16
# description: Tomcat is a World Wide Web server.  It is used to serve \
#              HTML, JSP, and servlets, and CGI if needed.
# processname: java

CATALINA_HOME=/usr/local/tomcat

case "$1" in
  start)
        rm -rf $CATALINA_HOME/work
        mkdir $CATALINA_HOME/work
        $CATALINA_HOME/bin/startup.sh
        ;;
  restart)
        $CATALINA_HOME/bin/shutdown.sh
        sleep 45
        killall -9 java
        sleep 2
        rm -rf $CATALINA_HOME/work
        mkdir $CATALINA_HOME/work
        $CATALINA_HOME/bin/startup.sh
        ;;
  stop)
        $CATALINA_HOME/bin/shutdown.sh
        sleep 45
        killall -9 java
        sleep 2
        ;;
  *)
        echo $"Usage: tomcat {start|restart|stop}"
        exit 1
esac

exit 0
        

Note Note

Consult your operating system documentation to figure out where you need to put startup scripts. On most RPM compatible systems, either /etc/rc.d/init.d/tomcat or /etc/init.d/tomcat will work.

Run Level Configuration


chmod 755 /etc/rc.d/init.d/mysqld
/sbin/chkconfig --add mysqld
/sbin/chkconfig --level 2345 mysqld on
/sbin/chkconfig --list mysqld
chmod 755 /etc/rc.d/init.d/tomcat
/sbin/chkconfig --add tomcat
/sbin/chkconfig --level 345 tomcat on
/sbin/chkconfig --list tomcat

Note Note

Again, consult your operating system documentation here. The chkconfig commands may not be available on your operating system, in which case you'll need to manually link your startup script to the proper run levels. Most RPM compatible systems have the chkconfig command.

Firewall Configuration

AdvertPRO needs the following ports to be open in your firewall in order to function properly:

Port NumberProtocolAllow InputAllow OutputClient/Source AddressDestination AddressUsed By
25TCPYesYesAnyAnySMTP
80TCPYesYesAnyAnyHTTP
443TCPYesYesAnyAnyHTTPS
3306TCPYesYeslocalhostlocalhostMySQL
9000TCPNoYeslocalhostwebsvc1.advertpro.com
websvc2.advertpro.com
AdvertPRO
9001TCPNoYeslocalhostwebsvc1.advertpro.com
websvc2.advertpro.com
AdvertPRO
9002TCPNoYeslocalhostwebsvc1.advertpro.com
websvc2.advertpro.com
AdvertPRO
9003TCPNoYeslocalhostwebsvc1.advertpro.com
websvc2.advertpro.com
AdvertPRO
9004TCPNoYeslocalhostwebsvc1.advertpro.com
websvc2.advertpro.com
AdvertPRO
9005TCPNoYeslocalhostwebsvc1.advertpro.com
websvc2.advertpro.com
AdvertPRO

Failure to open the aforementioned ports in your firewall will cause the AdvertPRO setup utility to abort.

Step #4: Startup

MySQL Database Server


/etc/rc.d/init.d/mysql start

Apache Tomcat Server


/etc/rc.d/init.d/tomcat start

Step #5: Finishing Up

MySQL Database

Log in to the MySQL client of your choosing and execute the following SQL queries to create the AdvertPRO database and user to access it.


CREATE DATABASE advertpro;
GRANT ALL PRIVILEGES ON advertpro.* TO advertpro@"localhost" IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON advertpro.* TO advertpro@"localhost.localdomain" IDENTIFIED BY 'password';
FLUSH PRIVILEGES;

Warning Warning

It is strongly recommended that you grant all privileges except for Grant to the database. However, if desired the Create_view, Show_view, Create_routine, Alter_routine, and Execute privileges are unused and may be revoked. Do not revoke any other privileges as doing so will prevent the normal operation of AdvertPRO!

Keep in mind that the database will be created using the default MySQL character set, which is specified by the character_set_system option in the my.cnf configuration file. For older versions of MySQL the option is named character_set instead. By default MySQL uses the Latin1 character set, so if you wish to use UTF-8 to support non-Latin1 characters create the MySQL database using this command unless you already changed the default MySQL character set to UTF-8:


CREATE DATABASE advertpro CHARACTER SET utf8 COLLATE utf8_general_ci;

When the AdvertPRO setup utility asks you for the JDBC URL you should changed it to specify that you want to use UTF-8 unless again you already changed the default MySQL character set to UTF-8 as the driver will always use the default MySQL character set regardless of the character set of your database:


jdbc:mysql://localhost:3306/advertpro?useUnicode=true&characterEncoding=UTF-8

GeoIP Database

If you have purchased the GeoIP Country or City database, you should install that prior to running the AdvertPRO setup utility.

  1. GeoIP Country Installation
  2. GeoIP City Installation

AdvertPRO Setup

  1. Open a browser window to: http://ads.yoursite.com/servlet/setup
  2. Follow the setup utility instructions.
  3. Make sure to follow the post-install instructions given by the setup utility too!

Note Note

It may take about 30 seconds from the time you start Apache Tomcat for it to automatically deploy AdvertPRO the first time.