Installing EPrints on Windows
June 11, 2010 45 Comments
EPrints provide a Windows installer for their product. However, because it is a Perl based web application it cannot be installed by running this installer file alone. There is a set of required software that is somewhat outside what might be considered the ‘normal’ range for Windows. Part of this includes running the Apache web server. If the machine on which you are intending to run EPrints has other applications that depend on the IIS web server then we would recommend choosing a different server for EPrints and, preferably, a Linux platform. If Linux is not an option and the server you are using does not run IIS (or you are comfortable with running Apache alongside IIS on different ports) then this article, in conjunction with the official EPrints documentation may prove useful.
The following is the list of required software for EPrints on Windows:
- ActiveState Perl
- Selected Perl Modules
One approach to installing this might be to download a WAMP installation such as WAMP Server. However, there are a couple of drawbacks for this. The first is that EPrints requires a specific installation directory for Apache. This may also be a consideration if you are installing EPrints on a machine that already has Apache installed. The second is that WAMP installs PHP, which you may not require. This isn’t a major problem in that it won’t interfere with EPrints but is a consideration in that extra software will be installed that will, to some extent, be using resources (for example, Apache will load various PHP modules).
To install EPrints it will be preferable (though not strictly necessary) to have Administrator privileges on the computer that will be running the software. It is necessary to have write permission to the root of the C drive.
Before installing EPrints you should also ensure that you have a hostname set up for the repository. This is the web address that will be entered in a browser (e.g. myrepro.myuni.ac.uk). The EPrints documentation says (correctly) that you should ensure that your systems team sets up a DNS entry for the domain that you want to use. If you are setting up a test repository that will not be accessed by other users it is possible to bypass this process by adding an entry for a ‘fake’ domain in your Windows hosts file. A tutorial on the hosts file can be found at bleepingcomputer.com.
Apache 2.2 can be downloaded from the Apache web site. If you are not going to be running IIS on the same computer and are happy to have Apache running on port 80 (the standard setting for web connections) then you can accept all the defaults except that you will need to change the installation folder to
C:\Apache in the Destination Folder dialog.
Once the installation has finished it is necessary to add the Apache binaries folder to the standard windows path. To do this right click on My Computer and select Properties. In the Advanced tab click the Environment Variables button. In the System variables section scroll down and select the variable name Path. Click edit and add the following to the end of the Variable value text:
Note the semi-colon. Entries in the Windows path variables are separated by semi-colons so this needs to be added to separate the new entry from the existing elements in the path. Click OK three times to save the changes.
You can test your installation by entering http://localhost/ in a browser. If you have used a different port in order to run alongside IIS enter this too, e.g. http://localhost:8080/. You should see a simple web page saying “It works!”
MySQL can be downloaded from the MySQL web site. The standard installation can be followed except for where the default character set is concerned. The MySQL Server Instance Configuration Wizard should start during the installation process. If it doesn’t you can run it after installation from the Windows Start Menu folder for MySQL.
When you reach the Default Character Set dialog select Best Support for Multilingualism.
This will set the default character set to UTF8. If you have an existing MySQL installation then the default character set can be changed through the MySQL Administrator or by re-running the MySQL Server Instance Configuration Wizard.
When installing MySQL the installer will ask for a password for the root user. Be sure to remember this.
Active State Perl (ActivePerl) community edition can be downloaded from the ActiveState web site. You can run through this installation accepting the defaults.
Installing Perl Modules
Perl modules are extensions to the basic Perl library. EPrints requires three additional Perl modules: mod_perl, DBD::mysql and XML::LibXML. Perl modules are available from various internet archives and ActivePerl includes a tool for managing the installed modules. From the Windows Start Menu folder for Active Perl select Perl Package Manager. Note, EPrints recommend using the module archive provided by the University of Winnipeg. To use this archive select Edit -> Preferences. Select the Repositories tab. From the Suggested drop-down list at the bottom of the dialog select the University of Winnipeg and click Add.
Module packages can be most easily installed from a command prompt. Start a command prompt (from Start Menu -> All Programs -> Accessories or by selecting Start Menu -> Run… and typing
cmd) and enter the following commands:
ppm install mod_perl ppm install DBD-mysql ppm install XML-LibXML
mod_perl installation script will ask for the location of the Apache modules directory. Enter
C:\Apache\modules. It will also be necessary to edit the Apache configuration files to enable mod_perl. This file is
C:\Apache\conf\httpd.conf. Add the following lines just after the section that contains a number of lines beginning with
# Perl LoadFile C:/Perl/bin/perl510.dll LoadModule perl_module modules/mod_perl.so
In the line that starts
LoadFile put the path to the file
perl510.dll. The value above should be correct for default installations of ActivePerl. Note the unix style forward slashes (/) in the path rather than the Windows style back slashes (\).
It is necessary to restart Apache to pick up these changes. This can be done by clicking on the Apache icon in the Windows System Tray.
Using PPM through a HTTP Proxy
Many HEIs route all web traffic through a HTTP proxy. This can prevent the Perl Package Manager being able to access the module archives. To overcome this it is necessary to set an environment variable so that the package manager is aware of the address of the proxy.
To set an environment variable right click on My Computer and select Properties. In the Advanced tab click the Environment Variables button. In the System variables section click New. Enter the Variable name HTTP_proxy and in Variable value the address of your institution’s HTTP proxy, including the port if required, e.g. http://myproxy.university.ac.uk:8080. If your proxy requires authentication then you will have to create two other environment variables called HTTP_proxy_user and HTTP_proxy_pass. Click OK three times to save the changes.
Install optional software
GhostScript and ImageMagick are optional pieces of software that add functionality to EPrints for creating preview images.
GhostScript can be downloaded from the GhostScript SourceForge project. Run the installer and accept the default options.
ImageMagick can be downloaded from the ImageMagick web site. Run the installer accepting the defaults except on the Select Additional Tasks dialogue. Here check the option to Install PerlMagick for ActiveState Perl.
The EPrints installer can be downloaded using the link to the .msi file from the EPrints software home page. It is better to use the link from the home page rather than the link from the Windows installation documentation because the home page link may point to a more recent stable version.
The EPrints installer does not allow any options to be configured. EPrints will be installed to the folder
Once the installation is complete edit the Apache configuration file (
C:\Apache\conf\httpd.conf) again. Add the following lines to the end of the file:
# EPrints Include C:/eprints/cfg/apache.conf
Set Windows paths
The EPrints configuration files contain certain paths which are, by default, set a Unix-style paths. In order for Preview images to be created (e.g. thumbnails of the first page of PDFs) the path to the ImageMagick ‘convert’ executableneeds to be changed to the Windows path.
To change this it is first necessary to copy the system configuration into an installation-specific configuration folder. This will prevent the changes getting overwritten if EPrints is upgraded.
Copy the file
C:\eprints\cfg\cfg.d\executables.pl and change the line:
'convert' => '/usr/bin/convert',
To reflect the location of the file convert.exe in your ImageMagick installation, for example:
'convert' => 'C:/Program Files/ImageMagick-6.6.2-Q16/convert.exe',
This path will depend on the version of ImageMagick that you installed.
Note that the creation of preview thumbnails for PDFs is not instant. If you view the abstract page of a newly deposited PDF and no preview is available try again after a few minutes.
Creating a repository
You can now create a repository. The process is similar to that described in the EPrints Getting Started guide but needs to be customised slightly for a Windows environment.
The configuration process is done through the command line so it is necessary to open a command prompt. First change to the EPrints binary directory:
epadmin command to create a repository:
perl epadmin create
You can now follow the on-screen instructions as indicated in the Getting Started Guide. Be careful especially to make a note of the Archive ID that you set for the repository.
When asked for a hostname enter the value that was set up by your systems team.
You will also be asked for the MySQL root user password that you entered during the MySQL installation.
Update: note that the
epadmin create command will ask for two host names, the standard host name and, later in the setup process, a secure host name. If set, the secure host name will be used for the Login and Create Account screens. This can cause problems if the server is not set up to use SSL (see comments) so be sure to only set this host name if you are sure that the server can handle connections using HTTPS.
Static files and LOC subject import
The creation of static files and importing of LOC subjects does not work when attempted as part of the repository creation process using
epadmin create. This is because Windows will not run Perl scripts unless explicitly told to user Perl (e.g.
perl epadmin create) or unless the script file has an extension that identifies it as requiring perl (e.g.
epadmin.pl create). Neither of these is an option for static file creation or import of LOC subjects by
epadmin without actually editing the
epadmin script file itself, which isn’t recommended.
However, both operations can be carried out after the repository has been created. You will need to know the ID of the archive that you have just created. Still in the
eprints\bin folder run the following commands, substituting the Archive ID of your repository where we have written
perl generate_static testwin perl import_subjects testwin perl generate_apacheconf
Restart Apache in order to pick up the configuration changes. It may also be useful to restart the EPrints Indexer service. This can be done from Control Panel -> Administrative Tools -> Services.
Once the web server has restarted it should be possible to access your repository using the hostname that was set up by your systems team.
Thanks go to archivalsoup for their blog article that informed these instructions. The main functional difference is that this article reflects some of the specific paths required by the latest EPrints installer.