Version 4.5

AdvertPro - System Administrators Guide

Table of Contents

This system administrators guide has been created to help you through the planning, deployment and management stages of operating AdvertPro.

Hardware Requirements

Low traffic sites can run AdvertPro on pretty much any cloud server with 2 GB of memory. Medium traffic sites will want to purchase a dedicated server for AdvertPro. High traffic sites will most certainly want to set up a cluster of load-balanced dedicated servers.

Low Traffic: Up to 125,000 hourly impressions (3 million daily)

Medium Traffic: Up to 1,250,000 hourly impressions (30 million daily)

High Traffic: Up to 5,000,000 hourly impressions (120 million daily)

Scaling AdvertPro to serve more impressions can be accomplished by setting up a cluster of load-balanced servers. You may also wish to configure AdvertPro for failover. This can also be accomplished by setting up a cluster with just two load-balanced servers.

Software Requirements

Operating System

AdvertPro is designed to work best with CentOS and Red Hat Enterprise Linux. All of our development, testing and support staff training is done with CentOS. For this reason, we strongly recommend that you choose one of these supported Linux distributions.

Java

Compatible with the official Oracle JDK 7 as well as older Sun or Oracle JDK 1.4, 1.5 (5.0) and 1.6 (6.0) platforms

Application Server

Compatible with Apache Tomcat 7.0 as well as 4.x/5.x/6.0, Caucho Resin 3.x/4.0, JBoss 3/4/5/6/7.0 and JRun 4.0

Database Server

Compatible with MySQL 5.5 as well as older versions: 3.23, 4.0, 4.1, 5.0 and 5.1

JDBC Driver

Compatible with MySQL Connector/J 5.1 as well as older versions: 3.0, 3.1 and 5.0

Web Server

Compatible with Apache 2.x with the mod_proxy_ajp module and Nginx 1.x with the ey_balancer module, however, web server software is not required as Tomcat can be installed to act as both an application server and a web server.

Installation

Startup & Shutdown

Assuming that you followed our installation instructions and used Tomcat you can start, restart and stop it with the following commands:

Configuration

Configuration of AdvertPro is done entirely through the AdvertPro control panel. Log in as the admin user and click on the Settings icon in the toolbar. There are hundreds of settings, however, many users are fine with most of the default settings. If you need help, just click on the (?) icon above any of the settings for a detailed description of them.

Data Backups & Recovery

AdvertPro creates daily SQL dumps of the MySQL database and stores them as ZIP files in the /usr/local/tomcat/webapps/ROOT/backups directory.

By default backups are retained for the last 7 days. You can increase or decrease the backup retention time by going to Settings > Expert > Cleanup in the AdvertPro control panel.

These backups are a lifesaver if you accidentally delete some data and need to recover it. You should not be completely reliant on them though. If a disk crash occurs the backups could be corrupted and lost. In the event of a natural disaster they might not be accessible to you. For this reason we recommend that you mirror your backups to a server in another location. Typically this is done with rsync over SSH although other methods exist. This will give you ultimate protection from data loss and will satisfy any disaster recovery requirements you might have.

Monitoring

AdvertPro has a special monitoring page located at http://ads.example.com/servlet/monitor that is designed for automated agents to check regularly to detect service problems.

The simplest test would be to check if the monitor page is accessible.

More advanced checks can be done by scanning the monitor page content for the words WARNING or FAILED to detect minor and service affecting problems.

The warning state is used exclusively when there is a problem accessing the MySQL database. AdvertPro can actually serve ads while MySQL is down since the ad server uses an in-memory database, however, the control panel will be non-functional until MySQL comes back online. This is nice because you can actually perform MySQL upgrades without interrupting ad delivery. If you have a MySQL slave server you can actually take the slave offline and run your own backups on it rather than using the built-in AdvertPro backups. AdvertPro will automatically redirect queries to the master until the slave comes back online.

Diagnostics

AdvertPro makes a lot of diagnostics information available to you that will help diagnose configuration and performance problems. All of this information can be accessed under Maintenance > Diagnostics in the AdvertPro Control Panel. Here is a overview of the information contained on each of the diagnostics pages:

Logging

AdvertPro creates daily error_log and event_log files in the /usr/local/tomcat/webapps/ROOT/logs directory.

The recommended error logging level for production servers is critical so that only serious errors are logged. It is often useful when troubleshooting problems to reduce the logging level to error or warning by going to Settings > Expert > Logging in the AdvertPro control panel. Never use lower logging levels such as debug on a production server! If you do this you run the risk of your hard drive filling up very quickly on a busy server due to the amount of data logged at those levels.

By default the error_log and event_log files are retained for the last 14 days. You can increase or decrease the log file retention time by going to Settings > Expert > Cleanup in the AdvertPro control panel.

Upgrades

We put a lot of effort into making new versions of AdvertPro backwards compatible. As you may be aware we operate a hosted version of AdvertPro. When we release a new version of AdvertPro it gets automatically deployed to all of our AdvertServe customers. If we introduce something new that breaks backwards compatibility it would instantly wreck tons of customers sites! Obviously we would never do that, so you can rest assured that upgrading AdvertPro is not going to break anything for you.

Do keep in mind that AdvertPro may not be forwards compatible with newer versions of required software though! Say for example that you run AdvertPro with MySQL 5.5 right now. Fast forward to MySQL 6.0 reaching GA status and you decide to upgrade. At this point you should stop and make sure that we have certified your version of AdvertPro to work with MySQL 6.0 before you proceed to upgrade! MySQL has a history of breaking backwards compatability so you may in fact need to do an AdvertPro upgrade to address any such issues before you attempt to upgrade MySQL.

Server Migrations

We have performed a lot of AdvertPro server migrations over the years with minimal service impact. If you follow these steps correctly you should have absolutely no down time! You will, however, lose some period of statistics data during the time it takes to transfer your MySQL database from the old server to the new server. In most cases it shouldn't take more than 10-15 minutes, but keep in mind that your ads will still be serving normally from the old server during this time so that isn't too bad.

  1. Change the DNS time-to-live (TTL) setting for the domain name used by AdvertPro (i.e. ads.example.com) to be very short (i.e. 5-10 minutes).
  2. Perform a clean installation of AdvertPro on the new server.
  3. Test the new server to make sure AdvertPro is functioning properly. There is a slick way to do this. Edit your computers hosts file and create a local DNS entry that points ads.example.com to the IP address of the new server. This will allow you to test everything simply by accessing your live site. When you are done don't forget to remove the entry from the hosts file!
  4. Stop the application server software (i.e. Tomcat) on the new server.
  5. Create a new empty database named advertpro:
    CREATE DATABASE advertpro CHARACTER SET utf8 COLLATE utf8_general_ci;
    
  6. Use mysqldump to create an SQL backup of the database on the old server:
    mysqldump -u root -p --opt advertpro | gzip > datadump.sql.gz
    
  7. Transfer the SQL dump file from the old server to the new server using SCP, SFTP or some other file transfer software.
  8. Load the SQL dump file into the empty database on the new server:
    gunzip < datadump.sql.gz | mysql -u root -p -D advertpro
    
  9. Start the application server software (i.e Tomcat) back up on the new server.
  10. Use the hosts file trick from step #3 to test the new server again before you switch over to it.
  11. Update the DNS for ads.example.com to point to the IP address of the new server.
  12. Finally, after a few hours you should be fine to change the TTL setting on your DNS back to its normal value. To be safe you can wait 24 hours. This is recommended just in case you have problems and need to revert to the old server quickly!

Password Recovery

AdvertPro stores encrypted hashes of passwords which makes it impossible to recover your passwords if you happen to lose them. You can easily reset them by using the Forgot your password? utility on the AdvertPro log in screen though. However, if you no longer have access to the e-mail address associated with your account you will be unable to reset your password with this utility. In this case you will need to have the user with the admin username log in and change your password for you.

If you have lost the password for the admin username and no longer have access to the e-mail address associated with that account you have a real problem :(

Fortunately there is a solution! What you will have to do is edit the administrator_info table in the MySQL database to update your e-mail address. Then you will be able to use the Forgot your password? utility to reset your password. Please be aware, however, that you must restart your application server (i.e. Tomcat) in order for any changes you make to the MySQL database to be detected. This is the only situation where it is really OK to make direct modifications to the database.