Difference between revisions of "How to set up EPrints on virtual directories other than root"

From EPrints Documentation
Jump to: navigation, search
 
Line 1: Line 1:
!EPrints setup under virtual directories other than / (or how to share EPrints with other web applications on the same server)
+
==EPrints setup under virtual directories other than / (or how to share EPrints with other web applications on the same server)==
  
 
Perhaps you have ever wondered if it's possible to use the same web server for EPrints and other web applications, and you've faced with the fact that EPrints software requires, as for Apache configuration respects, that two important virtual directories (/ and /perl) are redirected to EPrints proprietary physical directories (/opt/eprints2/archives/archiveID/html/ and /opt/eprints2/cgi respectively, as stated in ''/opt/eprints2/archives/archiveID/cfg/auto-apache.conf''). This condition makes impossible, in a first approach, to share EPrints web server with other applications than EPrints itself.
 
Perhaps you have ever wondered if it's possible to use the same web server for EPrints and other web applications, and you've faced with the fact that EPrints software requires, as for Apache configuration respects, that two important virtual directories (/ and /perl) are redirected to EPrints proprietary physical directories (/opt/eprints2/archives/archiveID/html/ and /opt/eprints2/cgi respectively, as stated in ''/opt/eprints2/archives/archiveID/cfg/auto-apache.conf''). This condition makes impossible, in a first approach, to share EPrints web server with other applications than EPrints itself.
  
 
However, this small document explains in detail how to overcome this limitation. It closely mimics the situation at Complutense University, Madrid, Spain.
 
However, this small document explains in detail how to overcome this limitation. It closely mimics the situation at Complutense University, Madrid, Spain.
!!Starting environment
+
 
 +
==Starting environment==
 +
 
 
We have at our disposal one corporative web server ([=http://server.name/=]) with the following setup, imposed by our computing services:
 
We have at our disposal one corporative web server ([=http://server.name/=]) with the following setup, imposed by our computing services:
  
*The main Apache listens to requests on HTTP port #80 and has not built-in mod_perl support.
+
* The main Apache listens to requests on HTTP port #80 and has not built-in mod_perl support.
*The main campus web site is located under [=http://server.name/=].
+
* The main campus web site is located under [=http://server.name/=].
*The secondary Apache listens to requests on HTTP port #8000 and has built-in mod_perl support. This is the one to be used for EPrints. We'll use port #8084.
+
* The secondary Apache listens to requests on HTTP port #8000 and has built-in mod_perl support. This is the one to be used for EPrints. We'll use port #8084.
*Both Apaches run under user nobody.
+
* Both Apaches run under user nobody.
  
In order for our customers to be able to acces EPrints service from the main campus web site, we'll configure Apache and EPrints so the software be accessible through [=http://server.name/eprints/=].
+
In order for our customers to be able to acces EPrints service from the main campus web site, we'll configure Apache and EPrints so the software be accessible through http://server.name/eprints/.
  
 
EPrints version used for this tests is 2.3.11.
 
EPrints version used for this tests is 2.3.11.
!!Web server configuration steps
+
 
 +
==Web server configuration steps==
 +
 
 
To be performed in the following order.
 
To be performed in the following order.
  
*Main Apache configuration (campus web site)
+
* Main Apache configuration (campus web site)
->As for EPrints concerns, this Apache has to redirect all requests for [=http://server.name/eprints=] to the 8084 port of the secondary Apache with mod_perl. So its file ''httpd.conf'' needs to be modified like this:
 
  
-->[-[=ProxyPass /eprints http://server.name:8084=]-]
+
As for EPrints concerns, this Apache has to redirect all requests for [=http://server.name/eprints=] to the 8084 port of the secondary Apache with mod_perl. So its file ''httpd.conf'' needs to be modified like this:
-->[-[=ProxyPassReverse /eprints http://server.name:8084=]-]
 
  
->These lines have to be included at the end of the file, outside the virtual hosts sections (if any). Of course, replace server.name with your server name, as fixed in your DNS, and /eprints with the name of the virtual directory you'd like to be used.
+
ProxyPass /eprints http://server.name:8084
 +
ProxyPassReverse /eprints http://server.name:8084
  
*Secondary Apache configuration (EPrints one)
+
These lines have to be included at the end of the file, outside the virtual hosts sections (if any). Of course, replace server.name with your server name, as fixed in your DNS, and /eprints with the name of the virtual directory you'd like to be used.
->It has to manage HTTP requests redirected from the main Apache to its 8084 port, so you have to define a virtual host for HTTP port #8084, as well as a default virtual host (required if you want to use virtual hosts; see Apache documentation). The ''httpd.conf'' file must be like this:
 
  
-->[-### Section 1: Global Environment-]
+
* Secondary Apache configuration (EPrints one)
--->[-...-]
 
--->[-Listen 8000-]
 
--->[-Listen 8084-]
 
--->[-...-]
 
-->[-### Section 2: 'Main' server configuration-]
 
--->[-...-]
 
--->[-Port 8000-]
 
--->[-Port 8084-]
 
--->[-...-]
 
-->[-### Section 3: Virtual Hosts-]
 
--->[-[=NameVirtualHost=] *:8000-]
 
--->[-[=<VirtualHost=] _default_:8000>-]
 
---->[-[=ServerName=] server.name:8000-]
 
---->[-[=DirectoryIndex=] index.php index.html index.htm-]
 
--->[-[=</VirtualHost>=]-]
 
--->[-[=<VirtualHost=] *:8084>-]
 
---->[-[=ServerName=] server.name:8084-]
 
---->[-[=DirectoryIndex=] index.html-]
 
--->[-[=</VirtualHost>=]-]
 
  
-->[-Include /opt/eprints2/cfg/apache.conf-]
+
It has to manage HTTP requests redirected from the main Apache to its 8084 port, so you have to define a virtual host for HTTP port #8084, as well as a default virtual host (required if you want to use virtual hosts; see Apache documentation). The ''httpd.conf'' file must be like this:
 +
 
 +
### Section 1: Global Environment
 +
...
 +
Listen 8000
 +
Listen 8084
 +
...
 +
### Section 2: 'Main' server configuration
 +
...
 +
Port 8000
 +
Port 8084
 +
...
 +
### Section 3: Virtual Hosts
 +
NameVirtualHost *:8000
 +
<VirtualHost _default_:8000>
 +
    ServerName server.name:8000
 +
    DirectoryIndex index.php index.html index.htm
 +
</VirtualHost>
 +
<VirtualHost *:8084>
 +
    ServerName server.name:8084
 +
    DirectoryIndex index.html
 +
</VirtualHost>
 +
 
 +
Include /opt/eprints2/cfg/apache.conf
 +
 
 +
Please be aware that this configuration example is very simplistic. Virtual hosts sections can have lot of directives. We've only reflected here the minimum required. Once again, you'll have to customize server.name.
 +
 
 +
==EPrints installation==
  
->Please be aware that this configuration example is very simplistic. Virtual hosts sections can have lot of directives. We've only reflected here the minimum required. Once again, you'll have to customize server.name.
 
!!EPrints installation
 
 
The most time consuming task is to find the appropriate parameters to be used during EPrints installation and initial archive creation. After several tests, this are the keys for success, following the steps from official EPrints documentation (http://software.eprints.org/docs/php/installation.php), and modified when needed. The whole process is run under user nobody (the owner of Apache).
 
The most time consuming task is to find the appropriate parameters to be used during EPrints installation and initial archive creation. After several tests, this are the keys for success, following the steps from official EPrints documentation (http://software.eprints.org/docs/php/installation.php), and modified when needed. The whole process is run under user nobody (the owner of Apache).
  
*Unpack the eprints tar.gz file:
+
* Unpack the eprints tar.gz file:
-->''% gunzip eprints-2.something.tar.gz''
+
 
-->''% tar xf eprints-2.something.tar''
+
% gunzip eprints-2.something.tar.gz
 +
% tar xf eprints-2.something.tar
 +
 
 +
* Run the "configure" script:
 +
 
 +
% cd eprints-2.something
 +
% ./configure --with-user=nobody --with-group=nobody --with-apache=1
 +
 
 +
It is very important that you do not specify the parameter --with-virtualhost. EPrints doesn't need it, and so you won't have to take care of certain additional configuration files. The parameter --with-apache=1 is employed here because our Apache releases are 1.x.
 +
 
 +
* Run install.pl:
 +
 
 +
% ./install.pl
 +
 
 +
==EPrints configuration==
 +
 
 +
* Creating the archive
 +
 
 +
From EPrints directory (/opt/eprints2 by default) run ''bin/configure_archive''. The answers to the questions asked by this script are:
  
*Run the "configure" script:
+
Archive ID? archiveID
-->''% cd eprints-2.something''
+
Hostname? server.name
-->''% ./configure --with-user=nobody --with-group=nobody --with-apache=1''
+
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] ? yes
 +
MySQL Root Password ? *******
 +
Create config files [no] ? yes
 +
Hit return to continue [] ?
  
->It is very important that you do not specify the parameter --with-virtualhost. EPrints doesn't need it, and so you won't have to take care of certain additional configuration files. The parameter --with-apache=1 is employed here because our Apache releases are 1.x.
+
You have to use your own values for the fileds replaced by ****** and for archiveID, server.name, eprints.database, mysql.server.name.
  
*Run install.pl:
+
* Configuration files modifications
-->''% ./install.pl''
 
!!EPrints configuration
 
*Creating the archive
 
->From EPrints directory (/opt/eprints2 by default) run ''bin/configure_archive''. The answers to the questions asked by this script are:
 
  
-->[-Archive ID? archiveID-]
+
We have to change certain EPrints configuration files so all the software processes to be run in the future correctly implement the base URL we want to deploy (http://server.name/eprints). The changes required are commenting code lines and including new ones, as you can see below:
-->[-Hostname? 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] ? yes-]
 
-->[-[=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, server.name, eprints.database, mysql.server.name.
+
/opt/eprints2/archives/archiveID/cfg/ArchiveConfig.pm, section "Server of static HTML + images, including port"
  
*Configuration files modifications
+
# Server of static HTML + images, including port
->We have to change certain EPrints configuration files so all the software processes to be run in the future correctly implement the base URL we want to deploy ([=http://server.name/eprints=]). The changes required are commenting code lines and including new ones, as you can see below:
+
# $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://server.name/eprints";
  
->''/opt/eprints2/archives/archiveID/cfg/[=ArchiveConfig.pm=]'', section "Server of static HTML + images, including port"
+
/opt/eprints2/perl_lib/EPrints/Session.pm, subroutine get_uri
  
-->[-# Server of static HTML + images, including port-]
+
# sub get_uri
-->[-# $c->{base_url} = "[=http://=]$c->{host}";-]
+
# {
-->[-# if( $c->{port} != 80 )-]
+
#     my( $self ) = @_;
-->[-# {-]
+
#     return( $self->{"request"}->uri );
-->[-# &nbsp;&nbsp;&nbsp;&nbsp;# Not SSL port 443 friendly-]
+
# }
-->[-# &nbsp;&nbsp;&nbsp;&nbsp;$c->{base_url}.= ":".$c->{port};-]
+
sub get_uri
-->[-# }-]
+
    my( $self ) = @_;
-->[-# $c->{base_url} .= $c->{urlpath};-]
+
    my $uri= $self->{"request"}->uri;
-->[-$c->{base_url} = "[=http://server.name/eprints=]";-]
+
    if( $uri =~ m+^/+? && $uri !~ m+/eprints+i ){
 +
        $uri = "/eprints" . $uri;
 +
    }
 +
    return $uri;
 +
}
  
->''/opt/eprints2/perl_lib/EPrints/Session.pm'', subroutine get_uri
+
/opt/eprints2/cgi/users/home, section "Render page"
  
-->[-# sub get_uri-]
+
# my $changeuserpath = "/change_user/".($user->get_value( "username" ));
-->[-# {-]
+
my $changeuserpath = "/eprints/change_user/".($user->get_value( "username" ));
-->[-# &nbsp;&nbsp;&nbsp;&nbsp;my( $self ) = @_;-]
 
-->[-# &nbsp;&nbsp;&nbsp;&nbsp;return( $self->{"request"}->uri );-]
 
-->[-# }-]
 
-->[-sub get_uri-]
 
-->[-{-]
 
-->[-&nbsp;&nbsp;&nbsp;&nbsp;my( $self ) = @_;-]
 
-->[-&nbsp;&nbsp;&nbsp;&nbsp;my $uri= $self->{"request"}->uri;-]
 
-->[-&nbsp;&nbsp;&nbsp;&nbsp;if( $uri =~ m+^/+? && $uri !~ m+/eprints+i ){-]
 
-->[-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$uri = "/eprints" . $uri;-]
 
-->[-&nbsp;&nbsp;&nbsp;&nbsp;}-]
 
-->[-&nbsp;&nbsp;&nbsp;&nbsp;return $uri;-]
 
-->[-}-]
 
  
->''/opt/eprints2/cgi/users/home'', section "Render page"
+
''IMPORTANT NOTE'': Though EPrints will be used under http://server.name/eprints instead of [=http://server.name=], there is no need for modifying urlpath parameter inside ''/opt/eprints2/archives/archiveID.xml'' file (the corresponding line must remain as [-<urlpath></urlpath>-]).
  
-->[-# my $changeuserpath = "/change_user/".($user->get_value( "username" ));-]
+
* The remaining steps are those we all now, without changes from official EPrints documentation. From EPrints directory (/opt/eprints2 by default), run:
-->[-my $changeuserpath = "/eprints/change_user/".($user->get_value( "username" ));-]
 
  
->''IMPORTANT NOTE'': Though EPrints will be used under [=http://server.name/eprints=] instead of [=http://server.name=], there is no need for modifying urlpath parameter inside ''/opt/eprints2/archives/archiveID.xml'' file (the corresponding line must remain as [-<urlpath></urlpath>-]).
+
% bin/create_tables archiveID
 +
% bin/import_subjects archiveID
 +
% bin/generate_static archiveID
 +
% bin/create_user archiveID USERID EMAIL admin PASSWORD
 +
% bin/generate_views archiveID
 +
% bin/generate_apacheconf
  
*The remaining steps are those we all now, without changes from official EPrints documentation. From EPrints directory (/opt/eprints2 by default), run:
+
And do not forget to add the usual periodical tasks to the crontab of the user under which EPrints runs (nobody in our example): ''generate_views'', ''generate_abstracts'', ''send_subscriptions'' (daily, weekly and monthly), ''indexer''.
  
-->''% bin/create_tables archiveID''
+
==Web server restart==
-->''% bin/import_subjects archiveID''
 
-->''% bin/generate_static archiveID''
 
-->''% bin/create_user archiveID USERID EMAIL admin PASSWORD''
 
-->''% bin/generate_views archiveID''
 
-->''% bin/generate_apacheconf''
 
  
->And do not forget to add the usual periodical tasks to the crontab of the user under which EPrints runs (nobody in our example): ''generate_views'', ''generate_abstracts'', ''send_subscriptions'' (daily, weekly and monthly), ''indexer''.
 
!!Web server restart
 
 
Of course, once all changes are done, you have to restart the affected Apache servers (main Apache and secondary Apache), stopping and starting their daemons (do not use the ''apachectl'' restart command).
 
Of course, once all changes are done, you have to restart the affected Apache servers (main Apache and secondary Apache), stopping and starting their daemons (do not use the ''apachectl'' restart command).

Revision as of 12:37, 24 May 2006

EPrints setup under virtual directories other than / (or how to share EPrints with other web applications on the same server)

Perhaps you have ever wondered if it's possible to use the same web server for EPrints and other web applications, and you've faced with the fact that EPrints software requires, as for Apache configuration respects, that two important virtual directories (/ and /perl) are redirected to EPrints proprietary physical directories (/opt/eprints2/archives/archiveID/html/ and /opt/eprints2/cgi respectively, as stated in /opt/eprints2/archives/archiveID/cfg/auto-apache.conf). This condition makes impossible, in a first approach, to share EPrints web server with other applications than EPrints itself.

However, this small document explains in detail how to overcome this limitation. It closely mimics the situation at Complutense University, Madrid, Spain.

Starting environment

We have at our disposal one corporative web server ([=http://server.name/=]) with the following setup, imposed by our computing services:

  • The main Apache listens to requests on HTTP port #80 and has not built-in mod_perl support.
  • The main campus web site is located under [=http://server.name/=].
  • The secondary Apache listens to requests on HTTP port #8000 and has built-in mod_perl support. This is the one to be used for EPrints. We'll use port #8084.
  • Both Apaches run under user nobody.

In order for our customers to be able to acces EPrints service from the main campus web site, we'll configure Apache and EPrints so the software be accessible through http://server.name/eprints/.

EPrints version used for this tests is 2.3.11.

Web server configuration steps

To be performed in the following order.

  • Main Apache configuration (campus web site)

As for EPrints concerns, this Apache has to redirect all requests for [=http://server.name/eprints=] to the 8084 port of the secondary Apache with mod_perl. So its file httpd.conf needs to be modified like this:

ProxyPass /eprints http://server.name:8084
ProxyPassReverse /eprints http://server.name:8084

These lines have to be included at the end of the file, outside the virtual hosts sections (if any). Of course, replace server.name with your server name, as fixed in your DNS, and /eprints with the name of the virtual directory you'd like to be used.

  • Secondary Apache configuration (EPrints one)

It has to manage HTTP requests redirected from the main Apache to its 8084 port, so you have to define a virtual host for HTTP port #8084, as well as a default virtual host (required if you want to use virtual hosts; see Apache documentation). The httpd.conf file must be like this:

### Section 1: Global Environment
...
Listen 8000
Listen 8084
...
### Section 2: 'Main' server configuration
...
Port 8000
Port 8084
...
### Section 3: Virtual Hosts
NameVirtualHost *:8000
<VirtualHost _default_:8000>
   ServerName server.name:8000
   DirectoryIndex index.php index.html index.htm
</VirtualHost>
<VirtualHost *:8084>
   ServerName server.name:8084
   DirectoryIndex index.html
</VirtualHost>
Include /opt/eprints2/cfg/apache.conf

Please be aware that this configuration example is very simplistic. Virtual hosts sections can have lot of directives. We've only reflected here the minimum required. Once again, you'll have to customize server.name.

EPrints installation

The most time consuming task is to find the appropriate parameters to be used during EPrints installation and initial archive creation. After several tests, this are the keys for success, following the steps from official EPrints documentation (http://software.eprints.org/docs/php/installation.php), and modified when needed. The whole process is run under user nobody (the owner of Apache).

  • Unpack the eprints tar.gz file:
% gunzip eprints-2.something.tar.gz
% tar xf eprints-2.something.tar
  • Run the "configure" script:
% cd eprints-2.something
% ./configure --with-user=nobody --with-group=nobody --with-apache=1

It is very important that you do not specify the parameter --with-virtualhost. EPrints doesn't need it, and so you won't have to take care of certain additional configuration files. The parameter --with-apache=1 is employed here because our Apache releases are 1.x.

  • Run install.pl:
% ./install.pl

EPrints configuration

  • Creating the archive

From EPrints directory (/opt/eprints2 by default) run bin/configure_archive. The answers to the questions asked by this script are:

Archive ID? archiveID
Hostname? 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] ? yes
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, server.name, eprints.database, mysql.server.name.

  • Configuration files modifications

We have to change certain EPrints configuration files so all the software processes to be run in the future correctly implement the base URL we want to deploy (http://server.name/eprints). The changes required are commenting code lines and including new ones, as you can see below:

/opt/eprints2/archives/archiveID/cfg/ArchiveConfig.pm, 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://server.name/eprints";

/opt/eprints2/perl_lib/EPrints/Session.pm, subroutine get_uri

# sub get_uri
# {
#     my( $self ) = @_;
#     return( $self->{"request"}->uri );
# }
sub get_uri
   my( $self ) = @_;
   my $uri= $self->{"request"}->uri;
   if( $uri =~ m+^/+? && $uri !~ m+/eprints+i ){
       $uri = "/eprints" . $uri;
   }
   return $uri;
}

/opt/eprints2/cgi/users/home, section "Render page"

# my $changeuserpath = "/change_user/".($user->get_value( "username" ));
my $changeuserpath = "/eprints/change_user/".($user->get_value( "username" ));

IMPORTANT NOTE: Though EPrints will be used under http://server.name/eprints instead of [=http://server.name=], there is no need for modifying urlpath parameter inside /opt/eprints2/archives/archiveID.xml file (the corresponding line must remain as [-<urlpath></urlpath>-]).

  • The remaining steps are those we all now, without changes from official EPrints documentation. From EPrints directory (/opt/eprints2 by default), run:
% bin/create_tables archiveID
% bin/import_subjects archiveID
% bin/generate_static archiveID
% bin/create_user archiveID USERID EMAIL admin PASSWORD
% bin/generate_views archiveID
% bin/generate_apacheconf

And do not forget to add the usual periodical tasks to the crontab of the user under which EPrints runs (nobody in our example): generate_views, generate_abstracts, send_subscriptions (daily, weekly and monthly), indexer.

Web server restart

Of course, once all changes are done, you have to restart the affected Apache servers (main Apache and secondary Apache), stopping and starting their daemons (do not use the apachectl restart command).