This document describes how to manually install ExSite onto a web server. These steps are performed automatically if use use the Quick Installation procedure. They are described in detail here in case you need to customize that procedure for peculiar server setups.

System Requirements

ExSite has been installed and run successfully on Linux and OS X, but it should work on most Unix-y webserving environments. One of our developers even had it running under XP-Pro/IIS, although no real testing was done, so we doubt it was bug-free or feature-complete on that platform. It is distributed to work with MySQL, but other DBs can be used with modifications to the DB package (not included). As distributed, the following system specs are recommended:

• Webserver that supports CGI (Apache recommended)
• database (MySQL 3.23 or higher recommended - need not be on same server)
• Perl 5 (5.6 or higher recommended)
• The following Perl modules are used by ExSite, and should either be installed in the system Perl libraries, or in subdirectories of the website's cgi-bin:
• CGI*
• Carp*
• Devel::Size
• Digest::MD5*
• MIME::Base64*
• Net::SMTP* (optional - only required for sending email)
• Image::Info (optional - used for image handling)
• IO::String (optional - used for image handling)
• Spreadsheet::WriteExcel (optional - only required for reports in MS-Excel format)
• LWP* (optional - only required in some specialized distributed content management frameworks)
• The convert program (part of the ImageMagick image processing suite) is used for thumbnailing and image scaling operations, if it is available. It is also used as a fallback for Image::Info, if that package is unavailable.

* pre-installed by default on many Linux distributions.

Base Distribution

The ExSite Base distribution encompasses the following important directories:

• ./cgi - contains all programs and libraries. All CGI programs are contained directly within the cgi directory; libraries are contained in subdirectories of the cgi directory.

• ./cgi/ExSite - contains all ExSite kernel libraries.
• ./cgi/Modules - contains ExSite web applications and dynamic content modules.

• ./html - contains any static HTML, CSS, JavaScript, and image files required by the core ExSite distribution. These files are stored in:

• ./html/_ExSite - files needed by the kernel
• ./html/_Modules - files needed by web apps and dynamic content modules.

• ./doc - documentation and help files.

• ./install - installation files.

Basic Installation

You have a certain amount of flexibility in where you place the above groups of files, so ExSite can be reconfigured for a lot of different web serving environments. This section will outline a common basic installation that will configure a typical ExSite-based website. Later in this document, we will outline some alternative install procedures that can be used for other server configurations.

Basic installation has 4 steps:

1. copy the static files to your htdocs area
2. copy the CGI programs cgi-bin area
3. setup your MySQL database
4. edit your configuration file to reflect your installation

Each of these steps is described in detail, below.

Note that you will be dealing with a number of different user identities, which could get confusing. Try to keep them sorted out in your head, to prevent login and authentication difficulties later:

• Your shell account: you will use this to log on to your webserver to install ExSite. Otherwise it is not used by ExSite in any way.
• Your website user identity: this is the user identity you will eventually use to log in to your website. You can actually create numerous website login IDs here, but you will need to create at least one administrator login to get started.
• MySQL user: this is the identity under which ExSite connects to the MySQL server to authenticate itself. No person will use this identity; it is purely for internal use by ExSite. This may be provided to you by your system administrator or ISP. Otherwise you will need to create it, using the MySQL root account (see next).
• MySQL root user: if you are your own system administrator, you will need MySQL root access to create the database used by ExSite, and create the MySQL user (see previous). Otherwise, ExSite does not use the MySQL root account in any way. If your database has already been setup for you by your system administrator or ISP, you will not need the MySQL root password.

HTML Files

Copy the contents of ./html in the ExSite distribution, to your own server's "DocumentRoot" directory. In the standard ExSite distribution, all html files are located in subdirectories named _ExSite and _Modules, so they should not overwrite any existing files in your server's DocumentRoot (unless you happened to have files of those names already there -- unlikely unless you are already running ExSite). For example,

% cp -r ./html/* /var/www/html

You will need to do this under a user ID with permission to write to the webserver directories, of course.

The above example is typical of an installation to the system webserver documents directory. The actual directory may vary from system to system. If your webserver is hosting multiple websites, then you will probably be installing to a "VirtualHost" web directory, instead of the system directory. In that case, the copy destination will be your virtual host document directory, which might be something like:

% cp -r ./html/* /home/my_website/public_html

Consult your system administrator, if you are not sure.

CGI Programs

The ExSite CGI programs are those files in the ./cgi directory. They include page generation, publication, and administrator tools. They also include the kernel and dynamic content modules subdirectories, and a third subdirectory called the DBmap. (The DBmap is a mini-database that describes the schema, relational structure, and special web features of the primary ExSite database. It consists of a handful of tab-delimited text data files.)

To install your CGI programs, simply copy all of the contents of the ./cgi directory in the ExSite distribution (including subdirectories), to your system ./cgi-bin directory, eg.

% cp -r ./cgi/* /var/www/cgi-bin

(If you are running in a shared webserving environment, the target directory will be somewhat different, for example /home/my_website/public_html/cgi-bin. Consult your system administrator for the specifics on your server.)

Publishing

In order to publish your pages, the webserver needs to be able to write files into the site's htdocs area. This is done by the publish.cgi program, which must be compiled now. Change to the cgi-bin directory, and execute the command:

% cc -o publish.cgi publish.c

Now that you've created the publish.cgi program, it must be given permission to write pages into the htdocs area. There are two methods for accomplishing this:

Method 1: (if suEXEC is NOT enabled on your webserver)

Set the setuid bit on the publish CGI program, so that it can write to the htdocs directory:

% chmod +s publish.cgi

Warning: your user identity should be something other than root. Setuid root programs are automatically rejected by Apache.

Method 2: (on suEXEC-enabled Apache servers only)

Use Apache's suEXEC feature to allow the site's CGI programs to run as a user ID that can write to the htdocs area.

Configuration of suEXEC is beyond the scope of this guide, but if your server is running with suEXEC, then you do not need to modify your publish.cgi program at all. Your server must be configured so that your site runs under a user ID that can write to the htdocs area, however.

Most webservers come with suEXEC disabled by default, so Method 1 is more likely to work if you are not sure.

64-bit Encryption

If you are installing onto a 64-bit server, you will need to compile a special encryption engine, since the pure-Perl encryption engine only works on 32-bit machines:

% cc -o crypt_tea crypt_tea.c

MySQL Database

Two database installation/configuration scripts are provided with the ExSite distribution, in the install directory. You may use either one:

• exsite.sql - a MySQL script to configure a bare-bones database, which will be empty of content.
• exsite-demo.sql - a MySQL dump of a preconfigured database that contains sample sites and pages. This makes it much easier to get started if you are using the system for the first time.

Select which of these scripts you want to use to initialize your database. The last line in each script creates an ExSite user, which allows you to log in. You should edit this line (using any text editor), to change the login name and especially the password to your website user identity.

Create Database

If your database was created in advance by your system administrator or ISP, you can skip this part.

Log in as the mysql root user, and create the database:

% mysql [-h IP_ADDR] -u root -p 
Enter password: ******
mysql> create database my_database;

You will also need to create a MySQL user that can connect to this database and make queries. For instance, this command creates a user with the minimum permissions required by ExSite:

mysql> grant create,select,insert,update,delete on my_database.* 
       to username@host identified by 'password';

(my_database, username, host, and password should be changed to whatever is appropriate. host can be set to "localhost" if the MySQL server is on the same machine as the webserver.)

Strictly speaking, create priveleges are only required to run the initialization script, below. If you run the initialization script (described below) as the MySQL root user instead of as the username you just created, then you can leave create off of the list of priveleges granted in the above statement.

Note: If you are running MySQL version 4.0 or higher, you will probably need to add "lock table" to the list of permissions in the grant command, above.

Initialize Database

Once your database is ready to go, start up MySQL:

% mysql [-h IP_ADDR] -u mysql_username -p 

(The -h IP_ADDR argument is not required unless your database server is on a different machine.) mysql_username should be the normal mysql user ID that ExSite will connect to the database with (the same one you granted permissions to, if you created the database yourself). After you enter your MySQL password, you can create your database with the following commands:

mysql> use my_database
mysql> source exsite-demo.sql

(Use the exsite.sql script if you don't want to preload the database with sample content.)

Verify: Once you have run the database script, a show tables; command should return something like this:

mysql> show tables;
+------------------+
| Tables_in_db     |
+------------------+
| article          |
| attribute        |
| content          |
| content_data     |
| member           |
| member_site_link |
| page             |
| section          |
| searchterm       |
| searchurl        |
| service          |
| trash            |
+------------------+
12 rows in set (0.00 sec)

At that point, type quit to exit MySQL.

MySQL Version Configuration

Due to timestamp incompatibilities between versions of MySQL, you need to inform ExSite which version of timestamps you are running with. If running MySQL v4.1 or higher, be sure to add the following configuration setting to your conf file (see next section):

timestamp_format = text

The default is timestamp_format=num, which is compatible with older versions of MySQL. At some point, the default can be expected to change, so it may be worth explicitly adding the configuration, regardless.

Configuration File

The file ./cgi-bin/exsite.conf contains various configuration parameters that control how ExSite behaves. The most important ones from an installation standpoint are the parameters for connecting to the database. These parameters you will need to modify (using any text editor) are:

server.db.name = your_database_name
server.db.user = your_mysql_user_name
server.db.pass = your_mysql_password
server.db.server = your_mysql_server

Your MySQL server can be set to "localhost" if it runs on the same machine as your webserver. More configuration options are described below.

Testing Your Configuration

To test your setup, point your browser to the exsite-test.cgi program in your cgi-bin directory. The URL will be something like:

http://www.yourdomain.com/cgi-bin/exsite-test.cgi

This simple test program will attempt to connect to your database and execute a few rudimentary queries to verify that it can communicate with it and retrieve meaningful results. It will report on failures and suggest possible solutions. If all tests pass, it will give you a link to log in.

Note that it may complain about missing plug-ins, if you have installed just a base distro with no plugins.

If you reset your login name and password, as instructed above, then you can login using the data you provided. If not, then you can login using the default username "admin" and password "password". Obviously these are insecure and they should be changed. (Both can be changed using the My Profile tool on the administrator web-top. However, once you do this, your current login identity becomes invalid, and you will have to login again to re-authenticate.)

If you used the exsite-demo.sql database configuration script, then you will have a full set of sites and pages to test other aspects of the system. For instance, after logging in to the administrator web-top, use the "My Website" application:

1. launch "My Website", by clicking on its icon
2. preview the home page, by clicking on its preview button

Optional Configuration Steps

The following configuration steps are optional, but may be useful in some cases:

Live link to help files

If you would like to be able to read the HTML documentation through your website, then you must copy or symlink the ExSite doc directory somewhere into your HTML documents directory. To keep it out of the way of your regular site directories and files, you can place the help files under the _ExSite subdirectory in your HTML documents directory, eg.

% cd DOCUMENT_ROOT/_ExSite
% cp -r EXSITE_DISTRO_DIR/doc help
or...
% ln -s EXSITE_DISTRO_DIR/doc help

Then, add (or modify) the line in your cgi-bin/exsite.conf file pointing to the help file location:

help_url = /_ExSite/help/index.html

NB: the symlink option only works if the followSymLinks option is enabled for your website.

Configuration parameters

The file cgi-bin/exsite.conf can contain many configuration parameters (review the source code of cgi-bin/ExSite/Config.pm for details). Some of the ones you may want to set or change immediately:

site.name = your_website_name
site.identity_cookie = the name of the cookie that holds login info
site.administrator = your_email_address

ExSite attempts to auto-configure itself to determine details such as host/domain info, protocols, and diskpaths and URLs to its document and cgi directories. If your installation or server configuration is a little irregular, then ExSite may have difficulties auto-configuring itself, in which case you can help it out by providing configuration values for any of these parameters:

• server.HTMLpath = the relative URL (no domain) to the base HTML documents directory that ExSite works from (empty string if using the base HTML docs directory for the website).
• server.HTMLroot = the server's disk path to the base HTML documents directory for the website (eg. "/var/www/html").
• server.CGIpath = the relative URL (no domain) to the base cgi-bin directory that ExSite works from (typically "/cgi-bin" or "/cgi" if using the base cgi-bin directory for the website).
• server.CGIroot = the server's disk path to the base cgi-bin directory for the website (eg. "/var/www/cgi").
• server.CSSpath = the URL path to the default ExSite css files ("/_ExSite/css" if using the base HTML docs directory for the website).
• server.protocol = the webserver protocol (usually either "http" or "https").
• server.host = the site host name (eg. "www").
• server.domain = the site domain name (eg. "yourdomain.com").
• server.port = the server port number, if not the default.
• server.server = the full server URL, which is a combo of the protocol, host, domain, and possibly port parameters.

You can specify any of the above that need to be explicitly specified. If you want to manually specify all of them, then disable auto-configuration entirely:

server.auto = 0

Logo

You can define a site logo that will be used in certain generic situations (eg. login screens). Simply specify the logo HTML (typically an <img> tag) in the site.logo parameter:

site.logo = 

Logging

ExSite can automatically log events and transactions to simple text logfiles, which is handy for monitoring system use, profiling, debugging, auditing, and collecting stats. There are three logfiles:

• db - records events and problems associated with database queries, and automatic report and form generation. (Most logging traffic goes here.)
• cms - records events and problems associated with the content management system
• diag - records general diagnostics that don't fit the other two categories.

Each log has a logging level from 0 (log nothing) to 3 (log everything). Generally speaking, log level 1 records errors (task could not be completed), level 2 records warnings (task had problems, but they were worked around), and level 3 records informational diagnostics (task had no problems, but recorded a benchmark in its progress). Set the log level you want to use for each log in the exsite.conf file, eg.

# record database errors and warnings
log.db = 2
# record CMS errors only
log.cms = 1

You can also specify the logfiles themselves (the defaults are db.log, cms.log, diag.log), eg.:

log.logfile.db = /var/log/exsite/db.log
log.logfile.cms = /var/log/exsite/cms.log
log.logfile.diag = /var/log/exsite/diag.log

(If you don't specify the path to the logfiles, they will be written to the cgi-bin directory.) You should create the log files and ensure that the webserver has permission to write to them, eg.

% touch db.log
% chmod 666 db.log

Logs can be viewed online using the exsite_log.cgi program.

Other Configurations

This section outlines a number of variations on the general install procedure, above.

• Adding ExSite to an Existing Website

  The danger here is that you don't want to overwrite existing files in the site's htdocs or cgi-bin directories. The easiest way to do this is to place ExSite into a subdirectory of the existing site. In other words, copy ExSite's ./cgi files to cgi-bin/exsite/ in your website's area. Similarly, copy ExSite's ./html files to html/exsite/ in your website's area. (You can use any subdirectory name you like, although it is better for autoconfiguration if you use the same name in both the cgi-bin and html directories.)

  ExSite attempts to auto-configure itself, so it may be able to automatically find its parts and know to confine itself to these subdirectories (including when publishing). Warning: as there are many ways to configure sites and servers, there is no guarantee that ExSite will auto-configure itself correctly. Always back up your files and perform tests before publishing, as there is a chance that it could overwrite existing files.

• Multi-Site Server, with Shared Code Base

  Say you are managing many different websites, but they are all hosted on the same server. You would like to use ExSite to manage many/all of them, but you don't want to have to install (and update) it many different times. There are several ways for multiple websites to share a single installation of ExSite:

  For instance, you can install the kernel files (./cgi/ExSite/...) in a location that is accessible to all sites, such as in the Perl system library directories (eg. /usr/lib/perl5/site_perl). If you want your dynamic content modules to be accessible system-wide, then install them similarly. To keep dynamic content modules restricted to particular sites, install them under each site's cgi-bin/Modules directory only. You will still have to install the .cgi files into each site's cgi-bin directory.

  Alternatively, keep your ExSite distribution in its own repository, and set up symbolic links to it from each site. Then a single update of the repository will automatically bring all sites up to date. Your sites must have the FollowSymLinks option enabled for their cgi-bin directories for this to work.

• Multi-Site Server, with Shared Database

  Whether or not you share the ExSite code between your sites, you also have the option of sharing the same database. The advantages of this are better sharing of computer and human resources, since single accounts can access and administer multiple sites. The disadvantage is that each site's data is not clearly separated/isolated from the others', which may be a security or reliability concern.

  To share a database, simply use the same database configuration parameters in each site's exsite.conf file.

Installing Plug-ins

Choosing Plug-ins

The following plug-ins are useful for a minimal system:

• CMS
• Member
• MySite
• PhotoAlbum
• Search
• Security
• SimpleMenu
• Trash
• WebDB

The following optional plug-ins are popular, and do not require any special database extensions, which makes them easy to install:

• DMenu
• Document
• ExLib
• Feedback
• Gallery
• Google
• GoogleMaps
• HomePage
• ImageRotate
• MailTo
• PrintFriendly
• Query
• SlideShow
• StripGallery
• TellAFriend
• Upload
• VersionMenu
• Webalizer

Other plug-ins have specialized functions and may require extending the base system's database (see below).

Plug-in Distribution

Each plug-in is distributed in a set of directories:

• ./cgi - contains all programs, libraries, and configuration files required by the plug-in. The subdirectory structure matches that of the base distribution. In the simple case, there will be only a ./cgi/Modules/[PLUGIN].pm file.

• ./html - contains any static files that may be served to the client (eg. images, stylesheets, help files, etc.)

A plug-in bundle may include multiple plugins, each in its own subdirectory that is organized as above.

Basic Installation

Copy the files under ./cgi to the matching directories in your main installation's CGI-BIN.

Copy the the files under ./html to [HTDOCS]/_Modules/[PLUGIN-NAME]/. For example, when installing the Foo plugin:

mkdir $HTDOCS/_Modules/Foo
cp -r ./html/* $HTDOCS/_Modules/Foo

The simple utility script install-dcd.pl performs the above procedure. This script is included in the bin directory of the ExSite Base Districution, and should be executed from the cgi-bin directory of your site. It prompts you for your preferences, and provides defaults in many cases. Here is an example of how it works:

$ ../bin/install-dcd.pl 

This script installs a dynamic content driver (DCD) into a website.

Continue? [y] 

We will install a dynamic content module from your local module
repository.  This is a directory containing copies of all the dynamic 
content modules that are available to this system.  You must provide
the repository base path.

Base path to modules: [/home/exware/exsite-plugins] 

The available dynamic content modules are: 

	BannerAd
	CMS
	CMenu
	Calendar
	Catalog
	.
	.
	.
	Trash
	Upload
	VersionMenu
	WebDB
	WebDir
	Webalizer
	Zine

Which module are you installing? CMS,Gallery,Member,MySite,Security,SimpleMenu,WebDB

Install method ('copy' or 'symlink'): [symlink] 

We are going to install CMS,Gallery,Member,MySite,Security,SimpleMenu,WebDB into 
/home/mywebsite/cgi-bin
using the symlink method.
Continue? [y] 

Database Extensions

If the plug-in distrubtion includes any files under ./cgi/dbmap/..., then it extends the database, and extra database setup will be required. If your plug-in does not include any special instructions, the following procedure is usually sufficient.

1. Each regular file in ./cgi/dbmap/* corresponds to one new table in the database. Ensure that these files have been copied to the matching directory in your CGI-BIN area.

2. There may also be two dot-files in ./cgi/dbmap/*: .datatype and .table. These should be appended to the matching files in your CGI-BIN area.

3. With the above files in place, you can generate a new database create script with the following command executed from your CGI-BIN directory:

   perl -e 'use ExSite::DBmap; $d=new ExSite::DBmap(name=>"dbmap"); \
   $d->make_sql_create_script;' > make.sql

   Alternatively, use the makesql.pl utility script in the bin directory of the ExSite base distribution:

   ./makesql.pl > make.sql

   However, the latter create script will include a command to insert a new admin user at the end of the script. Delete that.

   The make.sql script contains all of the MySQL CREATE TABLE commands you need to generate your entire MySQL schema. In practice, you don't want to create all of your tables again, but the create script should use the "CREATE TABLE IF NOT EXISTS..." syntax, so there should be no harm in running it on an existing database. However, it is always a good idea to back up your database before doing any work like this.

4. With your database backed up, you can create the new tables inside MySQL by simply running the create script you just made:

   mysql> use my_db
   mysql> source make.sql

Configuration File

If the plug-in distrubtion includes any files under ./cgi/conf/..., then it has its own configuration files. These files may need to be edited to get useful behaviours, but the details will vary between plug-ins. Consult the files in question for details.