The ExSite 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.
./html - contains any static HTML, CSS, JavaScript, and image files required by the core ExSite distribution. These files are stored in:
./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 configurations.
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
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.cgiIf 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.
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.
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.
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.
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.
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":
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 helpThen, add (or modify) the line in your cgi-bin/exsite.conf file pointing to the help file location:
help_url = /_ExSite/help/index.htmlNB: 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_addressExSite 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 protocal (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 = 0Logo
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:
- 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 = 1You 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.logLogs can be viewed online using the exsite_log.cgi program.
This section outlines a number of variations on the general install procedure, above.
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 to 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.
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.
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.