Getting Started with ECrystals

Prerequisites
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/ 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 .
 * 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, "0.0.0.0" 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 .
 * Database Password - The password for the database user.
 * Write these database settings - Please accept the default option ("yes").
 * Create database  - 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 machine.

Example: example.footle.ac.uk

Hostname? example.chem.soton.ac.uk

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? ******@chem.soton.ac.uk

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? ******@chem.soton.ac.uk

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!