ExSite Installation Guide

System Requirements

Distribution

The ExSite distribution encompasses the following important directories:

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.

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

The following step is necessary to enable the publish-on-demand feature of ExSite:

From the shell, in your website's ./cgi-bin directory, you will need to configure the publication wrapper. This is to give the webserver permission to publish pages to your htdocs directory:

% cc -o publish.cgi publish.c
% chmod +s publish.cgi
If this works, then the command ls -l publish.cgi should show something like this:
-rwsrwsr-x    1 yourname   yourgroup    13789 Dec 19 14:54 publish.cgi

It is important that the letters "s" and "x" appear in the first sequence of letters, in order for publish-on-demand to work.

MySQL Database

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

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.

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.

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 mysql user ID that you are allowed to 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     |
+------------------+
| content          |
| content_data     |
| member           |
| member_site_link |
| page             |
| section          |
+------------------+
6 rows in set (0.00 sec)

At that point, type quit to exit MySQL.

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.

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 website editor to navigate to the home page of "My Website":

  1. launch the website editor, by clicking on its icon
  2. open "My Website", by clicking on its icon
  3. open "index.html", by clicking on its icon
  4. from the menu, select View > Preview

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 emabled 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:

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 = <IMG SRC=/path/to/logo.gif>

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:

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.