|
m |
| (20 intermediate revisions not shown.) |
| Line 1: |
Line 1: |
| - | <p>This document explains how to install the DLXS middleware and XPAT software. After reading and following instructions here, there may be class specific installation issues, in which case there will be a link to those specific instructions</p>
| + | [[DLXS Wiki|Main Page]] > Installing DLXS |
| - |
| + | |
| - | ==Overview of the DLXS Installation Process==
| + | |
| | | | |
| - | On the open source CD you'll find:
| + | If you are installing DLXS on Solaris, please see [[DLXS on Solaris Tips]]. |
| | | | |
| - | * gzipped tarfiles for middleware and open source binaries
| + | ==[[System Requirements]]== |
| - | * <tt>Installer.pl</tt>
| + | |
| - | * an installation configuration file: <tt>main.cfg</tt>
| + | |
| | | | |
| - | XPAT is on the second CD.
| + | ==[[Installation Instructions]]== |
| | | | |
| - | There are several methods you can choose from to do the open source install:
| + | ==[[Directory Structure]]== |
| | | | |
| - | * Run the installation directly from the mounted CD
| + | ==[[DLPS Development Environment]]== |
| - | * Copy the files from the CD to a directory and install from there
| + | |
| - | * Download the .iso image from www.dlxs.org. Mount it and install from the mount point,
| + | |
| | | | |
| - | The installer only installs the middleware, not the open source binaries or the XPAT binaries.
| + | *[[Setting up cron jobs for DLXS]] |
| | + | *[[DLXS Daemon: Installing and Configuring]] |
| | | | |
| - | <p>You can break the DLXS software installation into three parts:</p>
| + | ==[[Step-by-Step Installation Instructions|Step-by-step Installation Screen Printout]]== |
| | | | |
| - | * Pre-install steps
| + | ==[[Installing and Upgrading the Database]]== |
| - | Deciding where to install, extracting XPAT, binaries, and getting Perl modules.
| + | |
| - | * Running the Installation Script
| + | |
| - | Creates an initial working system that can function using the sample collection data.
| + | |
| - | * Post-install steps: operations not handled by the Installer
| + | |
| - | Change permissions of a few directories, configure Apache web server, install database sample data.
| + | |
| | | | |
| - | <p>There are two main pieces of software that need to be installed: XPAT and other binaries and the middleware. You will need to install MySQL unless you plan to run a CSV database. We do not recommend the CSV database option and will deliver the sample database as a MySQL dump in release 13. Further, the database upgrade program will no longer offer the option of CSV. </p>
| + | ==[[Multiple Releases]]== |
| | | | |
| - | * <b>XPAT</b>, and a few related binary files, are to be installed by a sysadmin (or someone with root access to the machine). The sysadmin will decide where the XPAT binaries should go and install them there.
| + | ==[[Installation Troubleshooting]]== |
| - | * The <b>Middleware</b> files will be installed under one directory (whose name should be set up as the <a href="../intro/dirstruct.html#dlxsrootenv">DLXSROOT environment variable</a>). The installation script <i>does not</i> require root access, just write access to the $DLXSROOT directory which it will create during the installation process.
| + | |
| | | | |
| - | | + | ==[[User Submitted Documentation]]== |
| - | ==Pre-install Steps== | + | *[[Installation]] |
| - | | + | |
| - | ===Extracting/Installing XPAT / tif2web / mrsid_retrieve / kdu_expand / cjpeg===
| + | |
| - | | + | |
| - | Installer will ask for a path to a directory that initially should <b>not</b> exist: <tt>/l1/workshop/text02/dlxs</tt>. Installer will create <tt>dlxs</tt> under <tt>/l1/workshop/text02/dlxs</tt> and populate it.
| + | |
| - | | + | |
| - | We refer to this path as <b>DLXSROOT</b> and the middleware accesses it via the <tt>DLXSROOT</tt> environment variable set by the web server. You should set <tt>DLXSROOT</tt> in your shell and Apache virtual host configuration. For more information on virtual host configuration, see the [[#Apache config sample files]] section. Set <tt>DLXSROOT</tt> in the shell when running some DLXS command line scripts or debugging the middleware at the command line.
| + | |
| - | | + | |
| - | Super-user privileges are not required; you only need user-write access to the directory containing DLXSROOT. Set your <b>unmask</b> to 022 so files/directories will be created 664/775.
| + | |
| - | | + | |
| - | <p><b>NOTE</b>: <i>tif2web</i> is a program used by the middleware (<a href="../class/text/pageviewer.html">Pageviewer</a>) to convert TIFF files to GIF and PNG formats. The installation of <i>tif2web</i> will closely follow the steps for installing XPAT.</p>
| + | |
| - | | + | |
| - | <p><b>NOTE</b>: <i>mrsid_retrieve</i> is a program used by the ImageClass middleware to decompress MrSID files generating JPEG output for delivery to browsers. As with <i>tif2web</i>, the installation of <i>mrsid_retrieve</i> will closely follow the steps for installing XPAT.</p>
| + | |
| - | | + | |
| - | <p><b>NOTE</b>: <i>kdu_expand</i> is a program used by the ImageClass middleware to decompress jpeg2000 files generating JPEG output for delivery to browsers. As with <i>tif2web</i>, the installation of <i>kdu_expand</i> will closely follow the steps for installing XPAT.</p>
| + | |
| - | | + | |
| - | <p><b>NOTE</b>: <i>cjpeg</i> used in conjunction with kdu_expand for JPEG2000 web delivery. As with <i>tif2web</i>, the installation of <i>kdu_expand</i> will closely follow the steps for installing XPAT.</p>
| + | |
| - | | + | |
| - | <p>Uncompress and untar the XPAT tarfile where you would like to store the XPAT executables. For example, at many sites, this is <i>/usr/local/.</i> You would typically use the following command, replacing all items in curly braces (i.e., { }) with appropriate values:</p>
| + | |
| - | | + | |
| - | <p><b><i>Local CD, local destination </i></b></p>
| + | |
| - | <pre>
| + | |
| - | cd {path-to-XPATinstall}
| + | |
| - | tar xf {cdrom-mount-point}/{path-to-tarfile}/XPAT-{version}.tar </pre>
| + | |
| - | | + | |
| - | You should include this directory in your shell PATH environment variable. This enables Installer to offer you their actual locations when it prompts.
| + | |
| - | | + | |
| - | <p>Unlink any previous symlink from a version-specific directory of XPAT to an XPAT directory (i.e., one without a specific version name). For example: </p>
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | cd {path-to-XPATinstall}
| + | |
| - | rm xpat </pre>
| + | |
| - | | + | |
| - | <p>Create a symlink from the new version-specific directory of XPAT to an XPAT directory (i.e., without version name). For example: </p>
| + | |
| - | | + | |
| - | <pre>
| + | |
| - | cd {path-to-XPATinstall}
| + | |
| - | ln -s xpat-{version} {path-to-XPATinstall}/xpat</pre>
| + | |
| - | | + | |
| - | ===Installing Other Binaries=== | + | |
| - | <p>There are several other binaries that you may need. Install these on your system as required for the DLXS classes you plan to use, and include them in $PATH. Adding them to $PATH is not required but if you add them, the installer will be able to offer you their actual locations when it prompts. <i>xpat</i>, <i>mrsid_retrieve</i>, <i>kdu_expand</i>, <i>cjpeg</i> and <i>tif2web</i> are part of the DLXS distribution.</p>
| + | |
| - | | + | |
| - | * <b>c42pdf</b> (required for TextClass pageviewer) | + | |
| - | * <b>tif2web</b> (required for TextClass pageviewer)
| + | |
| - | * <b>mrsid_retrieve</b> (required for ImageClass)
| + | |
| - | * <b>kdu_compress, kdu_expand</b> (required if you use ImageClass .jp2 files)
| + | |
| - | * <b>cjpeg</b> (required if you use ImageClass .jp2files)
| + | |
| - | * <b>dlxsd</b> (required if you access data remotely)
| + | |
| - | * <b>utf8conditioner</b> (required if you use OAITransform)
| + | |
| - | * <b>xpatutf8check</b> (optional utf-8 validity-checking program)
| + | |
| - | | + | |
| - | The installation steps for these binaries are identical to the XPAT installation steps.
| + | |
| - | | + | |
| - | <p>In addition you will need standard unix utilities installed and present in $PATH: make, mkdir, ln, cat, chmod.</p>
| + | |
| - | | + | |
| - | * <i>c42pdf</i> is not part of the DLXS distribution. You can get it at http://c42pdf.ffii.org/. We are currently using version 0.12 for Linux.
| + | |
| - | | + | |
| - | ===Required Perl modules===
| + | |
| - | | + | |
| - | <p>We recommend you use the version of <b>Perl</b> specified in the [[System Requirements]] page.</p>
| + | |
| - | | + | |
| - | <p>In addition you will need to install additional Perl modules. You can find the list of these additional Perl modules in the [[System Requirements]] page. The Installer checks for the existence of these modules. You may install them after you install DLXS.</p>
| + | |
| - | | + | |
| - | <p> During DLXS middleware installation, you may see Installer complain about an already installed Perl module due to dependencies it has on other not yet installed Perl modules. These will go away when all reported Perl modules are installed in your Perl distribution.</p>
| + | |
| - | | + | |
| - | ==MySQL configuration==
| + | |
| - |
| + | |
| - | <p>For DLXS installations you will use MySQL as your data store. You should execute the following commands to create an empty database, user accounts, and access permissions required for use
| + | |
| - | with DLXS middleware. </p>
| + | |
| - | | + | |
| - | # Start the SQL monitor with the command <tt>mysql -u root -p mysql</tt> (you will be prompted for the MySQL system password).
| + | |
| - | # Create the DLXS database with the command <tt>create database dlxs;</tt>. Note that you should use the database name you chose when prompted for the name of the database during DLXS middleware installation rather than simply <tt>dlxs</tt>. We suggest you should choose a name that reflects the version number of the database delivered with the middleware release or perhaps the release number of the middleware.
| + | |
| - | # Create the <tt>dlxsadm</tt> (administrative) account and grant full privileges to it with the command <tt>grant all privileges on dlxs.* to dlxsadm identified by '<i>password</i>';</tt>, where <i>password</i> is the password to be used for DLXS database administration.
| + | |
| - | # Grant FILE privilege to the <tt>dlxsadm</tt> account with the command <tt>grant file on *.* to dlxsadm;</tt>.
| + | |
| - | # Create the <tt>dlxs</tt> account and grant basic privileges to it with the command <tt>grant select,insert,update,delete,references on dlxs.* to dlxs identified by '<i>password</i>';</tt>, where <i>password</i> is the password to be used for general DLXS database usage (such as from within the DLXS middleware).
| + | |
| - | # Activate the changes with the command <tt>flush privileges;</tt>.
| + | |
| - | # Exit the SQL monitor with the command <tt>quit</tt>.
| + | |
| - | | + | |
| - |
| + | |
| - | ===Decide where to install DLXS Middleware===
| + | |
| - | <p>You may want to give some consideration to how you will manage the installation of a subsequent DLXS release. The main consideration is where you want a later release to reside in your file system, i.e. what its DLXSROOT should be. You can find a detailed discussion of installing multiple releases in [[Multiple DLXS Releases]]</p>
| + | |
| - | | + | |
| - | <p>The Installer will ask for a path to a directory that initially should not yet exist,
| + | |
| - | e.g. <i>/usr/local/dlxs</i>. The installer will create <i>dlxs</i> under
| + | |
| - | <i>/usr/local</i> and populate it. This path will be referred to as <b>$DLXSROOT</b>
| + | |
| - | and is accessed by the middleware as an environment variable. You should set
| + | |
| - | the <a href="../intro/dirstruct.html#dlxsrootenv">DLXSROOT environment variable</a>:</p>
| + | |
| - | | + | |
| - | * in your unix shell (setting DLXSROOT in the shell is necessary when running some DLXS command line scripts)
| + | |
| - | * in the Apache web server [[#web server configuration]] info below).
| + | |
| - | | + | |
| - | <p>We recommend you install as a normal user with a <b>umask</b> of 002, which creates files that are group-writable.</p>
| + | |
| - | | + | |
| - | ==Installation Script: Outline==
| + | |
| - | | + | |
| - | <p>A general outline of the interactive installation script follows. This installation script will first confirm the location of various resources, install the middleware and some sample data, and then configure the middleware.</p>
| + | |
| - | | + | |
| - | # create needed subdirectories under $DLXSROOT
| + | |
| - | # check dependencies
| + | |
| - | ## Perl
| + | |
| - | ## installation locations of required and optional binaries
| + | |
| - | # install middleware
| + | |
| - | # install sample HTML and HTML template files
| + | |
| - | # install sample data
| + | |
| - | # change variables in configuration files
| + | |
| - | # replace Perl "hash bang" strings in certain utility programs with local Perl path.
| + | |
| - | # substitute local value of DLXSROOT environment variable in sample data indexes.
| + | |
| - | # run processing scripts on installed sample data.
| + | |
| - | # generate snippets of text that should be added, by the Sysadmin, to several non-DLXS configuration files, e.g.,
| + | |
| - | ## Apache virtual host directives
| + | |
| - | ## Unix cron job commands to manage session expiration
| + | |
| - | | + | |
| - |
| + | |
| - |
| + | |
| - | ==Step-by-Step Installation Instructions==
| + | |
| - | <p>Click here to see <a href="stepbystep.html">step-by-step instructions</a> on running the installation program.</p>
| + | |
| - |
| + | |
| - | ==First Time Installation vs. Update==
| + | |
| - | <p>If this is a first time installation of the DLXS middleware at your site, little
| + | |
| - | will be required beyond following the installation script and having your Sysadmin
| + | |
| - | do the tasks requested by the installation script outline (for example, insert configuration snippets into the Apache server conf file, create and make "nobody"
| + | |
| - | the owner of the DLXSROOT/web/cache directory, install sample database data, etc.).</p>
| + | |
| - | | + | |
| - | <p>However, if this is not your first time installing DLXS middleware, some or all of the following additional steps may be necesary:</p>
| + | |
| - | | + | |
| - | * if the middleware requires database format changes, instructions will be given to run the programs required to convert the collection database. This includes the possibility that you are running a CSV database for DLXS.
| + | |
| - | | + | |
| - | * Although changes to the middleware are made to be backward-compatible, you should check any program files you have changed to see whether they will work with the new version. A simple UNIX diff can be helpful. A version control system (at DLPS, we use CVS) can help with comparing and merging code.
| + | |
| - |
| + | |
| - |
| + | |
| - | ==Post-Installation Steps==
| + | |
| - | | + | |
| - | <p> After these post-installation steps are complete you can test you installation by visiting the URLs below in your browser. Substitute your actual virtual host for the string "YOURVIRTUALHOST" below.</p>
| + | |
| - | | + | |
| - | <table border="1" width="50%" align="CENTER">
| + | |
| - | <tr>
| + | |
| - | <td><b>Collmgr:</b></td> <td><code>http://YOURVIRTUALHOST/cgi/c/collmgr/collmgr</code></td>
| + | |
| - | </tr>
| + | |
| - | <tr>
| + | |
| - | | + | |
| - | <td><b>BibClass:</b></td> <td><code>http://YOURVIRTUALHOST/cgi/b/bib/bib-idx</code></td>
| + | |
| - | </tr>
| + | |
| - | <tr>
| + | |
| - | <td><b>FindaidClass:</b></td> <td><code>http://YOURVIRTUALHOST/cgi/f/findaid/findaid-idx</code></td>
| + | |
| - | </tr>
| + | |
| - | <tr>
| + | |
| - | | + | |
| - | <td><b>ImageClass:</b></td> <td><code>http://YOURVIRTUALHOST/cgi/i/image/image-idx</code></td>
| + | |
| - | </tr>
| + | |
| - | <tr>
| + | |
| - | <td><b>TextClass:</b></td> <td><code>http://YOURVIRTUALHOST/cgi/t/text/text-idx</code></td>
| + | |
| - | </tr>
| + | |
| - | </table>
| + | |
| - | | + | |
| - | | + | |
| - | ===Change directory and file permissions===
| + | |
| - | | + | |
| - | <p>The <tt>$DLXSROOT/web/<b>cache</b></tt> is created by the Install program with <tt>777</tt> permissions. Alternatively, you may want to change permissions on this directory to make it writeable only to the UID of the web server.</p>
| + | |
| - | | + | |
| - | ===Apache config sample files===
| + | |
| - | | + | |
| - | <p>Examine <tt>$DLXSROOT/bin/installer/config-examples/httpd.conf.dlxs</tt>. You may integrate this segment into your Apache configuration file, adapting as necessary. It assumes you want to run your DLXS installation on a virtual host called <i>dlxs.</i></p>
| + | |
| - | | + | |
| - | <p>If you would like to run your DLXS installation on a different virtual host, please consult your Apache documentation.</p>
| + | |
| - | | + | |
| - | <p>You <i>may</i> comment out the section in <tt>httpd.conf.dlxs</tt> which implements
| + | |
| - | basic authentication for the collmgr. If you disable this be aware that the collmgr
| + | |
| - | requires some form of authentication that sets the REMOTE_USER environment variable
| + | |
| - | for proper operation. So, to run "out of the box," the easiest thing
| + | |
| - | to do is to use the "Basic Auth" sample configuration. See
| + | |
| - | <a href="../auth/index.html">DLXS Authentication and Authorization</a>
| + | |
| - | for more information.</p>
| + | |
| - |
| + | |
| - | <p>The file <tt>$DLXSROOT/bin/installer/config-examples/htpasswd.dlxs</tt> codes the administrative password <b>dlxsadm</b> for the collmgr with the password <b><i>collmgr. </i></b>You will probably also want to change the password to a different value using the Apache program:</p>
| + | |
| - | | + | |
| - | <pre> % htpasswd passwordfile username </pre>
| + | |
| - | | + | |
| - | <p>where <tt>passwordfile</tt> is <tt>APACHE/conf/htpasswd.dlxs</tt> and <tt>username</tt> is <tt>dlxsadm</tt>. Note <tt>htpasswd.dlxs</tt> will then need to be placed in the <tt>conf</tt> subdirectory of your Apache installation. For more information, see [http://www.apache.org the Apache Web Site].
| + | |
| - | | + | |
| - |
| + | |
| - |
| + | |
| - | ===Database conversion and migration following installation</h2>
| + | |
| - |
| + | |
| - | <p>If you have a DLXS installation that is Release 9 or
| + | |
| - | later, you will need to run the <tt>upgrade_<i>N_N+1</i></tt> utilities (one or
| + | |
| - | more) that are delivered with the DLXS software. This should be done following a successful installation. These will migrate your data from one version of the database to another. For example, if you are currently running Release 12 of the software, which uses
| + | |
| - | version 5 of the database, and are installing Release 13, which uses
| + | |
| - | database version 6, you should run <tt>upgrade_5_6</tt> to move your
| + | |
| - | current data into the new format. See the
| + | |
| - | <a href="../collmeta/upgrade.html">upgrade documentation</a> for more information</p>
| + | |
| - |
| + | |
| - | <p>For first-time installations, your database will be MySQL. You will have created an empty database as described <a href="#mysqlconfig">above</a>. The next step is to install the sample database data contained in <tt> $DLXSROOT/misc/db/db-dump-v6.0-release.sql</tt> as follows. Let <b>dlxs_v6</b> be the database name you chose for this installtion. Load the dump via the <b>mysql</b> command line client like this:<br/><br/><center> <code>% mysql -u dlxsadm -p dlxs_v6 < $DLXSROOT/misc/db/db-dump-v6.0-release.sql</code></center></p>
| + | |
| - | | + | |
| - |
| + | |
| - | ===Configuration Example Files===
| + | |
| - | | + | |
| - | <p>The configuration example files generated by the
| + | |
| - | installation script will be found in the <tt>$DLXSROOT/bin/installer/config-examples</tt> directory. The Sysadmin should be notified of these and s/he should use them to make the changes necessary, e.g., the web server configuration file, <a href="../intro/cronjobs.html">crontab</a>.</p>
| + | |
| - | | + | |
| - | ===Sysadmin tasks===
| + | |
| - | | + | |
| - | <p>The $DLXSROOT/bin/installer/config-examples directory will also contain a file called README-postinstall that will contain a set of instructions that someone with sysadmin rights will need to follow. These include setting specific permissions on special directories:</p>
| + | |
| - | | + | |
| - | * Permissions on <tt>$DLXSROOT/web/cache</tt>: this directory too will need to be owned by the runner of the web server processes, again, often "nobody".
| + | |
| - | | + | |
| - | * Configure crontab:
| + | |
| - | | + | |
| - | The DLXSROOT/bin/managesessions.pl, DLXSROOT/bin/manageportfolios.pl and DLXSROOT/bin/managecache.sh scripts are typically run by a cron job to periodically expire user sessions, remove temporary ImageClass portfolios and maintain DLXSROOT/web/cache at the desired size. An example crontab can be found in DLXSROOT/bin/installer/config-examples/crontab.dlxs.
| + | |
| - | | + | |
| - | <p>If you are running the web server on one machine and the data resides on another you will have to <a href="../intro/daemoninstall.html">install the daemons</a> that allow for the two hosts to communicate. This requires root access.</p>
| + | |
| - | | + | |
| - |
| + | |
| - | ===Collection Manager Authorization===
| + | |
| - | | + | |
| - | <p>The [[Working with the Collection Manager|DLXS collection manager]] requires user authentication (i.e., access by username and password) to be able to check in, check out, and release changes. If you do not wish to use these functions, then at a bare minimum, it requires access by username and password as the administrator user, dlxsadm.</p>
| + | |
| - | | + | |
| - | <p>For your convenience, DLXS is installed with this minimum configuration using standard HTTP Basic Authentication. When you access the collection manager, you will be prompted for a username and password; enter "dlxsadm" with the password "collmgr", and you will be given access.</p>
| + | |
| - | | + | |
| - | <p> DLXS recommends that you change the default password after installation with the following command, which will prompt you for a new password:</p>
| + | |
| - | | + | |
| - | <p><code><apache>/bin/htpasswd <apache>/conf/htpasswd.dlxs dlxsadm</code></p>
| + | |
| - | | + | |
| - | <p> where <code><apache></code> is the directory in which Apache is installed on your system.</p>
| + | |
| - | | + | |
| - | <p>You may permit other users to the collection manager, collmgr, using this mechanism;
| + | |
| - | see your Apache documentation for more information on configuring Basic Authentication.
| + | |
| - | You may also replace the authentication method entirely, so long as it provides
| + | |
| - | the name of the authenticated user in the environment variable
| + | |
| - | <a href="../collmeta/collmgr.html#remoteuserenv">REMOTE_USER</a>. Also see
| + | |
| - | <a href="../auth/index.html">DLXS Authentication and Authorization</a>
| + | |
| - | for more information.</p>
| + | |
