Non-root proxy

Task

To build Apache 2 & mod_perl 2 for ePrints 3, installed as a standard user, with no superuser-like access to core services (including Perl and mySQL). The ePrints server will run as a normal user, and be accessed through a central proxy

Preparation

As we are installing software as a normal user (I'll use MyUser in this example), we are not adding any additional Perl modules centrally, but into a local tree. We need a directory to install this tree:

%> mkdir ~/perl5

We also need to be able to install some Perl packages from CPAN, so we need a configuration for that:

To set up cpan install as a non-root user, you need to set up your own ~/.cpan/CPAN/MyConfig.pm file. Copy one from another user, or find the system-wide one. You need to edit the values of a few keys in $CPAN::Config:

• 'build_dir', 'cpan_home', & 'keep_source_where' all need to be set to the full path for the users .cpan directory (eg: 'build_dir' => q[/home/MyUser/.cpan/build], )
• 'makepl_arg' needs to be set to PREFIX=/home/MyUser/perl5

You will need to set up a PERL5LIB environment variable for the shell (to run the various ePrints scripts). The easy way to work out what you need here is to see what the default library path is, and modify it for your user:

%> perl -V
Summary of my perl5 (revision....
[snip]
  @INC:
    /some/path/lib/perl5/5.8.0/sun4-solaris
    /some/path/lib/perl5/5.8.0
    /some/path/lib/perl5/site_perl/5.8.0/sun4-solaris
    /some/path/lib/perl5/site_perl/5.8.0
    /some/path/lib/perl5/site_perl

(This was developed on a Sun box, you may have something different to [i]sun4-solaris[/i])

We replace "/some/path" with the path to our new PREFIX (as defined above):

%> export PERL5LIB=/home/MyUser/perl5/lib/perl5/site_perl/5.8.0/sun4-solaris/: \
            /home/MyUser/perl5/lib/perl5/5.8.0/sun4-solaris: \
            /home/MyUser/perl5/lib/perl5/5.8.0: \
            /home/MyUser/perl5/lib/perl5/site_perl/5.8.0/MyUser: \
            /home/MyUser/perl5/lib/perl5/site_perl/5.8.0: \
            /home/MyUser/perl5/lib/perl5/site_perl

Add this to the users login/profile scripts (eg .bashrc)

Now we can start installing software.

Apache

Install a base Apache (previously downloaded into ~/distributions):

%> cd ~/distributions/
%> tar xvf httpd-2.2.x.tar
%> cd httpd_2.2.x

If you are returning to an existing source-tree, rather than a brand new untar'd bundle, clear any previous setup:

%> make distclean

Now configure and install an initial Apache server:

%> ./configure --prefix=/home/MyUser/www --disable-userdir --disable-status
%> make
%> make install

Edit http.conf (essentially, the port the server is listening on) and start the web server. Check the error log:

%> cat ~/www/logs/error_log
[...] Apache/2.2.x (Unix) Configured -- resuming normal operations

Mod-Perl

Stop web server and install the Mod-Perl extensions (previously downloaded into ~/distributions):

%> cd ~/distributions/
%> tar xvf mod_perl-2.0-current.tar
%> cd mod_perl-2.0.x

If you are returning to an existing source-tree, rather than a brand new untar'd bundle, clear any previous setup:

%> make clean 

Now configure and install mod-perl into the Apache tree, and (re)install Apache. In this example, I am specifying a version of Perl to use:

%> /path/to/specific/perl Makefile.PL PREFIX="/home/MyUser/perl5" MP_USE_DSO=1 \
   MP_APXS="/home/MyUser/www/bin/apxs" \
   MP_AP_CONFIGURE="--prefix=/home/MyUser/www --disable-userdir \
   --disable-status --enable-module=mod-perl"
%> make
%> make install

NOTE: Notice that there is a PREFIX defined, which matches the prefix in the CPAN configuration; that we are stating we want mod-perl as a DSO; the full path to the previously installed Apache "apxs" command; and that the configure parameters to be passed to the apache rebuild include enabling mod-perl

Editing the new apache config file

We need to enable the mod-perl module, which I do using one of the Includes:

• In ~/www/conf/httpd.conf, add:

# Mod-Perl
Include conf/extra/httpd-perl.conf

• Create ~/www/conf/extra/httpd-perl.conf:

#
# Load the Mod_perl DSO.
#
LoadModule perl_module modules/mod_perl.so
PerlSwitches -I/home/MyUser/perl5/lib/perl5/site_perl/5.x.y/sun4-solaris/ \
             -I/home/MyUser/perl5/lib/perl5/5.x.y/sun4-solaris \
             -I/home/MyUser/perl5/lib/perl5/5.x.y \
             -I/home/MyUser/perl5/lib/perl5/site_perl/5.x.y/sun4-solaris \
             -I/home/MyUser/perl5/lib/perl5/site_perl/5.x.y \
             -I/home/MyUser/perl5/lib/perl5/site_perl

• NOTE: the "PerlSwitches" line tells the Apache server where to look for extra libraries, and matches the PERL5LIB environment variable set earlier.

Start the web server. Check the error log:

%> cat ~/www/logs/error_log
[...] Apache/2.2.x (Unix) Configured -- resuming normal operations
[...] caught SIGTERM, shutting down
[...] Apache/2.2.x (Unix) mod_perl/2.0.x Perl/v5.x.y configured -- resuming normal operations

Stop the web server again.

---

ePrints

Before you can install ePrints, you need to check the Package requirements. CGI.pm builds against the installed Mod-Perl modules, so may well be wrong. You may need to install your own version.

eg:

%> /path/to/specific/perl -MCPAN -e shell
[snip]
cpan> install CGI
[...]
cpan> quit

Now we can install the ePrints software (previously downloaded into ~/distributions):

%> cd ~/distributions/
%> tar xvf eprints-3.zzz.tar
%> cd eprints-3.zzz./

There is no option to clean a previously configured eprints tree, so keep going..

%> ./configure -prefix=/home/MyUser/ePrints -with-perl=/path/to/specific/perl -with-user=MyUser \
    -with-group=MyUserGroup -with-toolpath=/path/to/tools

Note: the same version of perl is being defined again, and the /path/to/tools is a directory to find various external tools (tar, wget, (g)unzip, pdftotext, lynx, etc)

... and install:

%> ./install.pl

As we do not have root access to the MySQL database, you will need to get the database administrator to add a user to provide access the MySQL database. Note: Assuming your user is not given GRANT ALL (its a big security risk) you will need CREATE TEMPORARY TABLES as well as CREATE privilages.

Now we set up out basic ePrints environment

%> cd /home/MyUser/ePrints

First we need to set up the database connection. I fed in the values, but didn't get the table made, as that had already been done by the MySQL administrator. You need to decide the ARCHIVEID now, as this is used all over the place.

• Creating the archive

Run bin/configure_archive. The answers to the questions asked by this script are:

Archive ID? ARCHIVEID
Hostname? public.server.name
Webserver Port [80]? 8084
Alias (enter # when done) [#] ? #
Administrator Email? ******
Archive Name? ******
Database Name [bucm] ? eprints.database
MySQL Host [localhost] ? mysql.server.name
MySQL Port (# for no setting) [#] ? #
MySQL Socket (# for no setting) [#] ? #
Database User [bucm] ? ******
Database Password ? ******
Create database ?eprints.database? [yes] ? no
MySQL Root Password ? *******
Create config files [no] ? yes
Hit return to continue [] ? 

You have to use your own values for the fileds replaced by ****** and for ARCHIVEID, public.server.name, eprints.database, mysql.server.name. Note: public.server.name is the hostname of the web server that will catch the request, and be proxied through to the backend server, however the port number is the backend server port. The database details are the ones created by the db administrator above.

• Configuration files modifications

We need to make some changes to the basic ePrints install 'cos we are running through a proxy, and the eprints install doesn't cope with this...

We have to change one EPrints configuration file so all the software processes to be run in the future correctly implement the base URL we want to deploy (http://public.server.name/). The change required is simply commenting code lines and including a new one, as you can see below:

edit archives/ARCHIVEID/cfg/ArchiveConfig.pm, in the section "Server of static HTML + images, including port"

# Server of static HTML + images, including port
# $c->{base_url} = "http://$c->{host}";
# if( $c->{port} != 80 )-]
# {
#     # Not SSL port 443 friendly
#     $c->{base_url}.= ":".$c->{port};
# }
# $c->{base_url} .= $c->{urlpath};
$c->{base_url} = "http://public.server.name/";

Note: I also have to set disable_df => 1 in perl_lib/EPrints/SystemSettings.pm

%> bin/configure_archive

Finally, build the website:

%> bin/create_tables ARCHIVEID
%> bin/import_subjects ARCHIVEID
  [long process]
%> bin/generate_static ARCHIVEID
%> bin/create_user ARCHIVEID UID EMAIL admin PASSWORD
  [an initial "admin" user, with a login ID of UID, a password of PASSWORD,
   and an email address of EMAIL]
%> bin/generate_views ARCHIVEID
  [long process]
%> bin/generate_apacheconf 

Now edit httpd.conf to include the generated apache.conf:

# EPrints
Include /home/MyUser/ePrints/cfg/apache.conf

Finally, I had to make a couple of other changes to make the service work:

1. Move the document root and cgi-bin stuff from the httpd.conf file (the name and the <directory> section)

1. Add access permissions to the <Directory "/home/MyUser/ePrints/cgi"> section in ePrints/archives/<ARCHIVEID>/cfg/auto-apache.conf:

    Order deny,allow
    Allow from all

Start web server. Check the error log:

%> cat ~/www/logs/error_log
[...] Apache/2.2.0 (Unix) Configured -- resuming normal operations
[...] caught SIGTERM, shutting down
[...] Apache/2.2.0 (Unix) mod_perl/2.0.2 Perl/v5.8.0 configured -- resuming normal operations
[...] [notice] caught SIGTERM, shutting down
EPrints archives loaded: <ARCHIVEID>
EPrints archives loaded: <ARCHIVEID>
[...] Apache/2.2.0 (Unix) mod_perl/2.0.2 Perl/v5.8.0 configured -- resuming normal operations

GLORY IN YOUR NEW EPRINTS SYSTEM!!!!

To modify the general layout of the page, edit ePrints/archives/<ARCHIVEID>/cfg/template-en.xml and then re-run .../bin/generate_static <ARCHIVEID>