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
- 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
* pre-installed by default on many Linux distributions.
The ExSite Base distribution encompasses the following important
./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.
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.
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
Basic installation has 4 steps:
- copy the static files to your htdocs area
- copy the CGI programs cgi-bin area
- setup your MySQL database
- 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.
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.
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.)
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
- 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.
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
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.
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.
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.
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
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:
- launch "My Website", by clicking on its icon
- 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
% cd DOCUMENT_ROOT/_ExSite
% cp -r EXSITE_DISTRO_DIR/doc help
% 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.
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
server.auto = 0
You can define a site logo that will be used in certain generic
situations (eg. login screens). Simply specify the logo HTML
(typically an tag) in the site.logo
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.
This section outlines a number of variations on the general install
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
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.
The following plug-ins are useful for a minimal system:
The following optional plug-ins are popular, and do not require
any special database extensions, which makes them easy to install:
Other plug-ins have specialized functions and may require extending
the base system's database (see below).
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
./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.
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:
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:
This script installs a dynamic content driver (DCD) into a website.
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:
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
using the symlink method.
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
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.
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.
With the above files in place, you can generate a new database
create script with the following command executed from your CGI-BIN
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.
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
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