Version 3.0

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 the same server as their web site. Medium and high traffic sites will want to purchase a dedicated server for AdvertPro. The use of cloud servers is also supported provided that you can install the required software.

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 2,750,000 hourly impressions (65 million daily)

Extreme Traffic: Up to 4,150,000 hourly impressions (100 million daily)

Software Requirements

Operating System

AdvertPro is cross-platform software. It is supported on all flavors of Linux, Mac OS X, Solaris and Windows 2000/2003/2008.

Java

Compatible with the official Sun and Oracle JDK 1.4, 1.5 (5.0), 1.6 (6.0) and 1.7 (7.0) platforms

Application Server

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

Database Server

Compatible with MySQL versions 3.23, 4.0, 4.1, 5.0, 5.1 and 5.5

JDBC Driver

Compatible with MySQL Connector/J versions 3.0, 3.1, 5.0 and 5.1

Web Server

Compatible with Apache versions 1.3 and 2.x. Requires using either mod_jk or mod_proxy_ajp for application server integration. Other servers with proxying support such as Nginx and Microsoft IIS are also compatible. However, we recommend running your application server in standalone mode because AdvertPro is optimized for that type of configuration. Using Apache, Nginx or IIS is completely optional unless required for running other applications on the same server as AdvertPro.

Installation

Startup & Shutdown

Linux

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

Windows

Windows users will need to open the Windows Control Panel, then navigate to Administrator Tools > Services and finally right click on Apache Tomcat to start, restart or stop it.

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 {$TOMCAT_HOME}/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://{$DOMAIN}/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 {$TOMCAT_HOME}/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 down time. If you follow these steps correctly you should have no more than a minute of 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. If you have a huge MySQL database and the statistics data loss would be a problem for you though, consider using MySQL replication instead of the mysqldump transfer method we recommend here to avoid losing any data.

  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. Drop the MySQL database on the new server and create a new empty database with the same name:
    DROP DATABASE 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. Reconfigure the old server to proxy HTTP traffic to the new server. If you use HTTPS you can proxy that as well. Ultimately this step is optional, however, it helps prevent losing more statistics data while the DNS changes are propagated. Many methods exists to do this. We've found that using Nginx is the ideal solution because it supports caching to minimize latency and it also allows for HTTP header modification so you can keep things like geographic targeting working through the proxy! Be warned that using TCP/IP tunneling (i.e. 6tunnel) will break geographic targeting because it hides the clients true IP address. Obviously you should have Nginx set up and ready to go beforehand if you're going to do this. When you're ready to cut over to the new server, simply stop the application server (i.e. Tomcat) and then start up Nginx. In fact, you could even start using Nginx to proxy to localhost before you do the migration and then simply reconfigure Nginx to point to the IP address of new server and restart it when you're ready to cut over.
    user nginx;
    pid /var/run/nginx.pid;
    error_log /var/log/nginx/error.log crit;
    
    worker_processes 12;
    worker_rlimit_nofile 32768;
    
    events {
      worker_connections 4096;    # (12*(4096/4) = 12,288 max clients
    }
    
    http {
      include /etc/nginx/mime.types;
    
      default_type application/octet-stream;
    
      access_log off;
    
      gzip on;
      gzip_comp_level 6;
      gzip_http_version 1.1;
      gzip_min_length 0;
      gzip_types application/json application/x-javascript text/plain text/css text/javascript text/xml;
      gzip_vary on;
    
      sendfile on;
      tcp_nopush on;
    
      keepalive_timeout 60;
    
      proxy_cache_path /var/lib/nginx/cache levels=1:1:2 keys_zone=shared:100m inactive=60m max_size=2500m;
      proxy_cache_use_stale updating;
    
      server_tokens off;
    }
    
    upstream newserver {
      server NEW_SERVER_IP_ADDRESS:80;
    }
    
    server {
      listen 80;
      server_name _;
    
      location / {
        proxy_pass http://newserver;
    
        proxy_connect_timeout 30;
    
        proxy_set_header Host $http_host;
    
        proxy_set_header Accept-Encoding "";
        proxy_set_header User-Agent $http_user_agent;
        proxy_set_header Referer $http_referer;
    
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    
        proxy_redirect http://$http_host $scheme://$http_host;
      }
    
      location /servlet/files {
        proxy_pass http://newserver;
        proxy_cache shared;
        proxy_cache_key "$scheme$http_host$request_uri";
      }
    
      location ~* \.(css|html|js|txt|xml)$ {
        proxy_pass http://newserver;
        proxy_set_header Host $http_host;
        proxy_set_header Accept-Encoding "";
        proxy_cache shared;
        proxy_cache_key "$scheme$http_accept_encoding$http_host$request_uri";
      }
    
      location ~* \.(gif|jpg|png|jar)$ {
        proxy_pass http://newserver;
        proxy_cache shared;
        proxy_cache_key "$scheme$http_host$request_uri";
      }
    }
    
  13. 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 a day or two as some clients may cache DNS longer than the TTL says they should. However, if you leave the proxy running for a few days you will be fine doing it after a few hours.

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.