Homec4science
Diffusion invenio-infoscience (maint-1.0) Browse

R3600/INSTALL
17c4d54bdff1maint-1.0

Last Change
Raw File

INSTALL
View Options

CERN DOCUMENT SERVER SOFTWARE (CDSware) INSTALLATION
====================================================
Revision: $Id$
About
=====
This document specifies how to build, customize, and install the CERN
Document Server Software (CDSware). (See 'UNINSTALL' file if you look
for information on how to uninstall the system!)
Contents
========
0. Prerequisites
1. Quick instructions for the impatient CDSware admin
2. Detailed instructions for the patient CDSware admin
3. Configuration philosophy explained and elucidated
0. Prerequisites
================
Here is the software you need to have around before you
start installing CDSware:
a) Apache server, compiled with PHP and MySQL support:
<http://httpd.apache.org/>
<http://www.php.net/>
b) PHP compiled as a standalone command-line executable
(in addition to Apache module) is required, too:
<http://www.php.net/manual/en/install.commandline.php>
c) MySQL server (may be on a remote machine), and MySQL client
(must be available locally too):
<http://mysql.com/>
d) WML - Website META Language:
<http://www.engelschall.com/sw/wml/>
e) Python, featuring MySQLdb module:
<http://python.org/>
<http://sourceforge.net/projects/mysql-python>
f) If you want to be able to search for words in the fulltext files
(i.e. to have fulltext indexing), then you need as well to install
some of the following tools:
* for PDF files: pdftotext or pstotext
<http://www.foolabs.com/xpdf/home.html>
<http://www.cs.wisc.edu/~ghost/doc/AFPL/>
* for PostScript files: pstotext or ps2ascii
<http://www.cs.wisc.edu/~ghost/doc/AFPL/>
* for MS Word files: antiword, catdoc, or wvText
<http://www.winfield.demon.nl/index.html>
<http://www.ice.ru/~vitus/catdoc/index.html>
<http://sourceforge.net/projects/wvware>
* for MS PowerPoint files: pptHtml and html2text
<http://www.xlhtml.org/>
<http://userpage.fu-berlin.de/~mbayer/tools/html2text.html>
* for MS Excel files: xlhtml and html2text
<http://chicago.sourceforge.net/xlhtml/>
<http://userpage.fu-berlin.de/~mbayer/tools/html2text.html>
Note that the configure script checks whether you have all
the prerequisite software installed and that it won't let
you to continue unless everything is in order. It also warns you
if it cannot find some optional, but recommended software.
1. Quick instructions for the impatient CDSware admin
=====================================================
$ mysql -h sqlserver.domain.com -u root -p mysql
mysql> CREATE DATABASE cdsware;
mysql> GRANT ALL PRIVILEGES ON cdsware.* TO cdsware@webserver.domain.com IDENTIFIED BY 'myp1ss';
$ sudo vi /path/to/apache/conf/httpd.conf ## see below in part 2
$ sudo vi /path/to/php/conf/php.ini ## see below in part 2
$ sudo /path/to/apache/bin/apachectl graceful
$ cd /usr/local/src/
$ wget http://cdsware.cern.ch/download/cdsware-0.9.tar.gz
$ tar xvfz cdsware-0.9.tar.gz
$ cd cdsware-0.9
$ ./configure --with-htdocsdir=/www/data/ \
--with-cgibindir=/www/cgi-bin/ \
--with-dbutildir=/usr/local/bin/ \
--with-htdocsurl=http://webserver.domain.com/CDSware/ \
--with-cgibinurl=http://webserver.domain.com/cgi-bin/CDSware/ \
--with-dbhost=sqlserver.domain.com \
--with-dbname=cdsware \
--with-dbuser=cdsware \
--with-dbpass=myp1ss
$ vi ./config/config.wml ## optional, but strongly recommended
$ gmake
$ gmake create-tables ## optional
$ gmake install
$ gmake load-sample-data ## optional
$ gmake clean-sample-data ## optional
$ netscape http://webserver.domain.com/CDSware/admin/ ## optional
2. Detailed instructions for the patient CDSware admin
======================================================
The CERN Document Server Software (CDSware) uses standard GNU autoconf
method to build and install its files. This means that you proceed
as follows:
$ mysql -h sqlserver.domain.com -u root -p mysql
mysql> CREATE DATABASE cdsware;
mysql> GRANT ALL PRIVILEGES ON cdsware.* TO cdsware@webserver.domain.com IDENTIFIED BY 'myp1ss';
You need to create a dedicated database on your MySQL server
that the CDSware can use for its purposes. Please
contact your MySQL administrator and ask him to execute the
above commands that will create the "cdsware" database, a
user called "cdsware" with password "myp1ss", and that will
grant all rights on the "cdsware" database to the "cdsware"
user.
(Of course, you are free to choose your own user credentials
and the database name; the above values were just an
example. See also the configure line below.)
$ sudo vi /path/to/apache/conf/httpd.conf ## see below in part 2
Please ask your webserver administrator to put the following
lines in your "httpd.conf" configuration file:
AddType application/x-httpd-php .php .shtml
AddType application/x-httpd-php-source .phps .shtmls
DirectoryIndex index.shtml index.php index.html
This is to ensure that "*.shtml" files will be interpreted
by the web server as PHP files, and that "index.shtml" will
be considered as directory index file.
$ sudo vi /path/to/php/conf/php.ini ## see below in part 2
Please ask your webserver administrator to put the following
lines in your "php.ini" configuration file:
session.save_handler = user
session.auto_start = 0
session.name = SESSIONID
session.gc_probability = 0
session.gc_maxlifetime = 60000
session.cookie_lifetime = 0
log_errors = on
display_errors = off
expose_php = off
max_execution_time = 160
This is to tell PHP that we will be using our own session
handler and our own garbage collector. Also, it sets up
some other relevant PHP variables.
$ sudo /path/to/apache/bin/apachectl graceful
Please ask your webserver admin to restart the Apache server
after the above "httpd.conf" and "php.ini" changes.
$ cd /usr/local/src/
Change to a directory where we will configure and build the
CDS Software. (The built files will be installed later on
into Apache htdocs and cgi-bin trees.)
$ wget http://cdsware.cern.ch/download/cdsware-0.9.tar.gz
Fetch CDSware package from the CDSware distribution server.
$ tar xvfz cdsware-0.9.tar.gz
Untar the distriburion tarball.
$ cd cdsware-0.9
Go to the source directory.
$ ./configure --with-htdocsdir=/www/data/ \
--with-cgibindir=/www/cgi-bin/ \
--with-dbutildir=/usr/local/bin/ \
--with-htdocsurl=http://webserver.domain.com/CDSware/ \
--with-cgibinurl=http://webserver.domain.com/cgi-bin/CDSware/ \
--with-dbhost=sqlserver.domain.com \
--with-dbname=cdsware \
--with-dbuser=cdsware \
--with-dbpass=myp1ss
Configure essential CDSware parameters, as the installation
directories for HTDOCS files, CGI scripts and DB utilities,
the URL of the homepage and CGI scripts, and database host,
database name, and database user credentials.
The first two directories must be within the Apache's htdocs
and cgi-bin paths. The DB utilities may be installed
anywhere on the system. Note that CDSware won't install in any
other directories but the three mentioned in the above
configure line.
This configuration step is mandatory, and is referred to as
"pre-compile time configuration step a)" in the elucidative
explanatory commentary below.
$ vi ./config/config.wml ## optional, but strongly recommended
Optionally, customize your CDSware installation. We
strongly recommend you to edit at least the top of this file
where you can define some rather essential CDSware
parameters like the name of your CDSware document server or
the email address of the local CDSware administrator. (The
latter is needed if you want to use admin. modules in
general.)
The rest of the "config.wml" file enables you to change the
CDSware web page look and feel, and otherwise to influence
its behaviour and default parameters.
This configuration step is optional, but strongly
recommended. It is referred to as "compile time
configuration step b)" in the elucidative explanatory
commentary below.
$ gmake
Launch the CDSware build. All the pages will be pre-created
based on the config you have edited in the previous step.
$ gmake create-tables ## optional
Optionally, create CDSware tables on the MySQL server. You
probably want to do this step only once, i.e. only if you
have not created any CDSware databases yet.
$ gmake install
Install the web pages, cgi scripts and database utilities
in the respective directories, as specified earlier by the
configure command.
After this step, you should be able to point your browser to
the chosen URL of your local CDSware installation and see it
running!
$ gmake load-sample-data ## optional
Optionally, load some sample data to be able to test the
CDSware installation.
$ gmake clean-sample-data ## optional
Optionally, remove the sample data and prepare a blank CDSware
installation for production purposes.
$ netscape http://webserver.domain.com/CDSware/admin/ ## optional
Optionally, do further runtime configuration of the CDSware,
like definition of data collections, document types,
document formats, word file tables, etc.
This configuration step is optional, and is referred to as
"runtime configuration step c)" in the elucidative
explanatory commentary below.
3. Configuration philosophy explained and elucidated
====================================================
As you could see from the above, the configuration of the CDSware is
threefold:
(a) pre-compile time configuration phase
[uses command line options / while doing "configure"]
(b) compile time configuration phase
[uses WML / after "configure", while doing "make && make install"]
(c) runtime configuration phase
[uses MySQL / after "make install", while doing "netscape http://webserver.domain.com/CDSware/admin/"]
What is the difference, and why?
(a) pre-compile time configuration phase
[uses command line options / while doing "configure"]
This configures essential CDSware parameters that makes your
CDSware copy installable and runable. The essential parameters
include: install directories for HTML documents, CGI scripts
and DB utilities; the base URL of the HTML documents and CGI
scripts; and MySQL user and server credentials.
This configuration step uses standard GNU autoconf approach,
i.e. you will run the standard "configure" script. Note
that the only arguments that CDSware takes into consideration
are CDSware-specific "--with-foo" arguments, see the end of
"configure --help" output.
This configuration step is mandatory. Without knowing
theses essential parameters there is nothing to install and
nothing to run.
Usually, you do this step only once.
(b) compile time configuration phase
[uses WML / after "configure", while doing "make && make install"]
Optionally, you may choose to influence CDSware behaviour, to
set up CDSware system name, to choose its default parameters,
to change its look and feel, to add your local web pages, etc.
This configuration step uses WML, the Website META Language.
The most important configuration file is "config/config.wml"
that you can edit at your will. Optionally, if you are an
advanced user, you may edit other WML files in the
distribution tree.
After that, when you type "make", the CDSware pages will be
pre-generated. We prefer that this configuration step is
done during compile-time and not runtime, because of
multiple reasons: (i) the pre-generated pages impose less
load on the web and the database server and so they are
served faster to the web client; (ii) we use several
different languages (PHP, Perl, Python) so that by using
compile-time configuration options we can share the same
variables across many heterogeneous applications; (iii) use
of WML and page templates enables you to easily change
anything in the CDSware system, even in its deepest level.
Usually, if you are changing parameters and/or look and feel
of CDSware pages, you do this step several times:
$ vi config/config.wml
$ gmake install
$ netscape http://webserver.domain.com/CDSware/
$ vi config/config.wml
$ gmake install
[...]
until you are satisfied with the result.
(c) runtime configuration phase
[uses MySQL / after "make install", while doing "netscape http://webserver.domain.com/CDSware/admin/"]
Optionally, you will most probably want to define specific
data collections, to configure submit and search page for those
collections, to specify search options and word files to
search in, etc.
This configuration step uses MySQL configuration tables and
is done during the runtime, for your convenience. It means
that after previous configuration step (b), and after
successful "gmake install", if you are happy with its result
you no longer edit WML files within the CDSware source tree but
rather configure "working" CDSware installation via its
Administration web interface.
Usually, you will do this step many times in the future, to
tweak the running installation, to add new collections and
data types, etc.
(Note that if you want to change something "deeper" in a
running CDSware installation, such as look and feel of pages,
or to add some new pages, then you need to go back to WML
source, so you may want to leave your customized copy of
the CDSware WML source tree around.)
We hope that this explains why we have chosen this three-level
configuration model, and that you will find it convenient in real
life.
Good luck, and thanks for choosing the CERN Document Server Software.
- CDS Development Group
<cds.support@cern.ch>
<http://cdsware.cern.ch/>
c4science · Help