Getting Started with ECrystals

From eCrystals Federation Project

Revision as of 16:06, 9 December 2008 by Mark (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search



This tutorial was compiled using a Debian-based distribution of the Linux operating system (Ubuntu, "Hardy Heron").

Please ensure that you installed EPrints and eCrystals before continuing with the rest of this tutorial.

Creating an Archive

eCrystals is able to serve multiple archives under the same EPrints installation. EPrints creates all Apache configuration files that are needed to run each eCrystals archive.

Running epadmin

Change to the EPrints user:

 root@ubuntu$  sudo su eprints

Navigate to the EPrints directory (/opt/eprints3 by default):

 eprints@ubuntu$  cd /opt/eprints3

Run the epadmin command:

 eprints@ubuntu$  bin/epadmin create

Configuring epadmin

The configuration script for EPrints (and eCrystals) uses a command-line interface that is similar to CPAN. The default (or recommended) option is displayed in square brackets. To select the default option, press the Enter key.

  • Archive ID - each EPrints archive must be given a unique, system-wide identifier. It is recommended that this identifier is short and memorable. Once entered, an archive/<archive_id> directory will be created automatically.

Once the archive directory and default files have been created, we can configure the EPrints repository:

  • Configure vital settings
    • Hostname - The hostname that must be typed into a Web browser in order to view this archive (please update your DNS settings accordingly)
    • Webserver Port - The default is 80
    • Alias - Please enter any DNS aliases that can be used to view this archive (please update your DNS settings accordingly)
    • Administrator Email - The email address for the EPrints repository administrator
    • Archive Name - The full name of this archive, to be displayed on nearly all Web pages (and in the title bar of the Web browser)
  • Write these core settings - Please accept the default option ("yes"). If you don't, configuration files will not be updated and you will need to re-run the configuration script.

EPrints and ECrystals make extensive use of a MySQL database, which is configured as follows:

  • Configure database
    • Database Name - The internal name of the database. As best practice, it is recommended that you use the <archive_id>.
    • MySQL Host - The address of the server that the database is running on. If the database is running on the same machine it is recommended that you use, "" or "localhost".
    • MySQL Port - The port of the server that the database is running on. The default port for MySQL is 8889. Please consult your systems team for more information about your local infrastructure.
    • MySQL Socket - The socket file of the server that the database is running on. It is unlikely that you will have to enter a value. Please consult your systems team for more information.
    • Database User - The username for the database. As best practice, it is recommended that you use the <archive_id>.
    • Database Password - The password for the database user.
  • Write these database settings - Please accept the default option ("yes").
  • Create database <db_name> - Please accept the default option ("yes"). EPrints will automatically create any missing databases, tables and accounts. If you have already configured your database, type "no".
    • MySQL Root Password - You will be prompted for the MySQL root password (configured when MySQL was installed).
  • Create database tables - Please accept the default option ("yes")

Now it is time to create the administrator account for the new archive:

  • Create an initial user
    • Enter a username - Enter "admin"
    • Select a user type - Enter "admin"
    • Enter Password - Please enter a password for the new administrator account. As best practice, DO NOT use the word "admin"!
    • Email - Please enter an email address for the new administrator account.
  • Do you want to build static Web pages - Please accept the default option ("yes")
  • Do you want to import the LOC subjects - Please enter "no". eCrystals uses its own subject hierarchy.

Finally, the configuration script will update Apache configuration files:

  • Do you want to update the apache config files? - Please accept the default option ("yes")

Before exiting, the configuration script will display information about the newly configured Web server.

An example configuration

 root@ubuntu$  sudo su eprints
 eprints@ubuntu$  cd /opt/eprints3
 eprints@ubuntu$  bin/epadmin create
 Create an EPrint Repository
 Please select an ID for the repository, which will be used to create a directory
 and identify the repository. Lower case letters and numbers, may not start with
 a number. examples: "lemurprints" or "test3"
 Archive ID? example
 We need to create /opt/eprints3/archives/example, doing it now...
 Getting uid and gid information from eprints
 UID: 113
 PID: 125
 Creating initial files:
 Installing: /opt/eprints/archives/example/cfg
 OK. I've created the initial config files and directory structure.
 I've also created a "disk0" directory under documents/ if you want
 your full texts to be stored on a different partition them remove
 the disk0, and create a symbolic link to the directory you wish to 
 store the full texts in. Additional links may be placed here to be 
 used when the first is full.
 Configure vital settings? [yes] ? yes
 Core configuration for example
 Please enter the fully qualified hostname of the repository.
 For a production system we recommend against using the real hostname of the 
 Please enter the port of the webserver. This is probably 80, but you may wish
 to run apache on a different port if you are experimenting.
 Webserver Port [80] ? 80
 Please enter all the aliases which could reach the repository, and indicate if
 you would like EPrints to write a Redirect Rule to redirect requests to this
 alias to the correct URL.
 Some suggestions:
 Enter a single hash (#) when you're done.
 Alias (enter # when done) [#] ? #
 Administrator Email? ******
 Enter the name of the repository in the default language. If you wish to enter
 other titles for other languages or enter non ascii characters then you may 
 enter something as a placeholder and edit the XML config file which this 
 script generates.
 Archive Name [Test Repository] ? Example ECrystals Repository
 Write these core settings? [yes] ? yes
 Configure database? [yes] ? yes
 Configuring Database for: example
 Database Name [example] ? example
 MySQL Host [localhost] ? localhost
 You probably don't need to set socket and port (unless you do!?).
 MySQL Port (# for no setting) [#] ? #
 MySQL Socket (# for no setting) [#] ? #
 Database User [example] ? example
 Database Password? ******
 Write these database settings? [yes] ? yes
 Create database "example"? [yes] ? yes
 MySQL Root Password? ******
 Create database tables? [yes] ? yes
 Create an initial user? [yes] ? yes
 Enter a username [admin] ? admin
 Select a user type (user|editor|admin) [admin] ? admin
 Enter Password? ******
 Email? ******
 Do you want to build the static web pages? [yes] ? yes
 Do you want to import the LOC subjects? [yes] ? no
 Do you want to update the apache config files? (you still need to add the 'Include' line) [yes] ? yes

Testing the New Archive

Restart Apache using the following command:

 root@ubuntu$  /etc/init.d/apache2 restart

Open a browser and enter the hostname into the address bar. You should see the new archive, ready to be populated with data!

Personal tools