Difference between revisions of "Getting Started with EPrints 3"

From EPrints Documentation
Jump to: navigation, search
(updated to 3.2.4)
Line 4: Line 4:
 
==Creating an Archive==
 
==Creating an Archive==
  
EPrints 3 can run run multiple archives under one install. Multiple archives will require giving additional DNS aliases to the machine running EPrints, EPrints can then create all the parts of the apache configuration file needed to run the virtual hosts.
+
EPrints 3 can run multiple archives under one install. Multiple archives will require giving additional DNS aliases to the machine running EPrints, EPrints can then create all the parts of the apache configuration file needed to run the virtual hosts.
  
 
===Running epadmin===
 
===Running epadmin===
 
Make sure MySQL is actually running.
 
Make sure MySQL is actually running.
  
Change to your eprints user (probably "eprints").
+
Change to your eprints user (probably ''eprints'').
  
 
Change directory to the eprints directory (<tt>/opt/eprints3</tt> by default) and run
 
Change directory to the eprints directory (<tt>/opt/eprints3</tt> by default) and run
  
<code>
+
bin/epadmin create
bin/epadmin create
+
</code>
+
  
You will get the following prompts (note that when you see something in [square brackets], it's the default value and can be selected by simply hitting enter)
+
You will get the following prompts (note that when you see something in [square brackets], it's the default value and can be selected by simply hitting <enter>):
  
* Archive ID - the system name for your archive.  It's probably a good idea to think of something short and memorable. Once entered, an <tt>archive/<archive_id></tt> directory will be created, and the standard configuration files will be copied in.
+
* Archive ID - the system name for your archive.  It's probably a good idea to think of something short and memorable. Once entered, an <tt>archive/<archive_id></tt> directory will be created, and the standard configuration files will be copied in.
 
* Configure vital settings - Hit enter to say 'yes'. This will lead to more prompting about core settings:
 
* Configure vital settings - Hit enter to say 'yes'. This will lead to more prompting about core settings:
 
** Hostname - What someone will type into a web browser to get to your archive.  Make sure that your systems team have a DNS alias pointing to your server for this.
 
** Hostname - What someone will type into a web browser to get to your archive.  Make sure that your systems team have a DNS alias pointing to your server for this.
** Webserver Port - Which port to you want to serve the archive on?  The default is 80, so unless you can think of a good reason not to, just hit enter to accept the default.
+
** Webserver Port - Which port do you want to serve the archive on?  The default is 80, so unless you can think of a good reason not to, just hit enter to accept the default.
 
** Alias - You can enter any number of aliases that will take users to this archive.  Enter a '#' when you don't want to enter any more.  You could have your archive served on <tt>eprints.myorganisation.org</tt> and <tt>eprints.myorg.org</tt>.  As with the Hostname, your systems team need to be informed about these aliases too.
 
** Alias - You can enter any number of aliases that will take users to this archive.  Enter a '#' when you don't want to enter any more.  You could have your archive served on <tt>eprints.myorganisation.org</tt> and <tt>eprints.myorg.org</tt>.  As with the Hostname, your systems team need to be informed about these aliases too.
 +
*** Redirect ''your chosen alias'' to ''Hostname'' - Yes, usually that is your intention.
 +
** Please enter the path part of the repository's base URL - Make it simple for you and your visitors ... and confirm the suggestion; multiple archives could be managed by different domains or ports!
 +
** If you will use https for your user pages (including login) enter the https hostname - No doubt, for secure usage you need another name.
 
** Administrator Email - Enter the email address of the repository administrator.  This will allow your repository users to send email to the right person.
 
** Administrator Email - Enter the email address of the repository administrator.  This will allow your repository users to send email to the right person.
 
** Archive Name - The full name of your archive.  By default, this will be used on many of the pages, and in the title bar of the browser.
 
** Archive Name - The full name of your archive.  By default, this will be used on many of the pages, and in the title bar of the browser.
** Write these core settings - If you don't say 'yes', then you entered all that data for nothing.
+
** Write these core settings - If you don't say 'yes', then you entered all that data for nothing (relaunch the process by <tt>epadmin config_core ''archive_id''</tt>).
* Configure database - EPrints makes extensive use of a MySQL database.  Enter 'yes' to configure this.
+
* Configure database - EPrints makes extensive use of a MySQL database.  Enter 'yes' to launch <tt>epadmin config_db ''archive_id''</tt>.
** Database Name - The internal name of your database.  It makes sense to use the Archive ID for this, but you don't have to.  You don't need to create this database, epadmin will do it for you.
+
** Database Name - The internal name of your database.  It makes sense to use the Archive ID for this, but you don't have to.  You don't need to create this database, <tt>epadmin</tt> will do it for you.
** MySQL Host - The address of the server that the database is running on.  If the database is on the same machine as the EPrints installation, enter 'localhost'.
+
** MySQL Host - The address of the server that the database is running on.  If the database is on the same machine as the EPrints installation, confirm 'localhost'.
 
** MySQL Port - You probably don't need to enter a value.  If you have problems connecting to the database, talk to your systems team.
 
** MySQL Port - You probably don't need to enter a value.  If you have problems connecting to the database, talk to your systems team.
 
** MySQL Socket - As with MySQL Port, it's unlikely that you need to enter anything.
 
** MySQL Socket - As with MySQL Port, it's unlikely that you need to enter anything.
** Database User - The username with which to log into the MySQL Database.  You don't need to create this user, epadmin will do it for you.  If you enter a MySQL username that already exists, it will be overwritten by epstats.
+
** Database User - The username with which to log into the MySQL Database.  You don't need to create this user, <tt>epadmin</tt> will do it for you.  If you enter a MySQL username that already exists, it will be overwritten by epstats!
** Database Password - The password for the Database User.
+
** Database Password - Just confirm the suggested password for the Database User, <tt>eprints</tt> will keep track of it!
 
** Write these database settings - You should write them, or you'll lose them.
 
** Write these database settings - You should write them, or you'll lose them.
** Create database <Database Name> - Say yes, and epadmin can create the database and populate it with all the right tables.  If you've already created a database and a user for this archive, say no.
+
* Create database <Database Name> - Say ''yes'' to launch <tt>epadmin create_db ''archive_id''</tt>, and <tt>epadmin</tt> can create the database and populate it with all the right tables.  If you've already created a database and a user for this archive, say 'no'.
** MySQL Root Password - To create the database and the user, epadmin needs the MySQL Root Password. This is not saved anywhere.  It is used to log into mysql, create the database and create the user with the right access rights. The password is then forgotten.
+
** Database Superuser Username - 'root' isn't a bad suggestion, but should match your specifications during the MySQL installation.
** Create database tables - say yes to have epadmin create all the database tables.
+
** Database Superuser Password - To create the database and the user, epadmin needs the MySQL Root Password (specified during MySQL installation). This is not saved anywhere.  It is only used to log into MySQL, create the database and create the user with useful access rights. The password is forgotten afterwards, because it's not needed anymore!
* Create an initial user - It's a good idea to create a user account for yourself at this point.
+
* Create database tables - say 'yes' to have epadmin create all the database tables, i.e. initiate the same as with <tt>epadmin create_tables ''archive_id''</tt>.
** Enter a username - The username you will use to log into EPrints in your browser.
+
* Create an initial user - It's a good idea to create a user account for yourself at this point, but you can start the same process by <tt>epadmin create_user ''archive_id''</tt> anytime ...
** Select a user type (user|editor|admin) - There are three levels of user in EPrints.  You probably want to be an administrator, so enter 'admin'.
+
** Enter a username - The username you will be used to log into EPrints on the home page of the new archive.
** Enter Password - A password for this user.  Remember to choose a password that will be hard for someone else to guess.
+
** Select a user type (user|editor|admin) - There are three user roles in EPrints.  You probably want to be an administrator, so enter 'admin'.
** Email - Enter your email address so that administrators can get in contact with you.
+
** Enter Password - A password for this user.  Remember to choose a password that will be hard for someone else to guess!
** Do you want to build the static web pages - There are a number of pages in EPrints which change very rarely.  These are the static pages.  The Home page and the About page are examples of static pages.  Stylesheets are also static.  These pages need to be built, so say 'yes'.
+
** Email - Enter your email address so that users can get in contact with you.
** Do you want to import the LOC subjects - If you will be using the Library Of Congress subject hierarchy, say 'yes'.  Otherwise you will need to create your own subject hierarchy.
+
* Do you want to build the static web pages - There are a number of pages in EPrints which change very rarely.  These are the static pages.  The Home page and the About page are examples of static pages.  Stylesheets are also static.  These pages need to be built, so say 'yes' (otherwise you have to start that process manually later by <tt>generate_static ''archive_id''</tt>).
* Do you want to update the apache config files? (you still need to add the 'Include' line) - Your archive has a number of files which it uses to configure the web server.  These should be updated, so say 'yes'.
+
* Do you want to import the LOC subjects - If you will be using the Library Of Congress subject hierarchy, say 'yes'.  Otherwise you will need to create your own subject hierarchy and to import them using [http://wiki.eprints.org/w/API:bin/import_subjects import_subjects].
* Before exiting, epadmin will display information about configuring the webserver.
+
* Do you want to update the apache config files? (you still need to add the 'Include' line in the very central http.conf, e.g.) - Your archive has a number of files which it uses to configure the web server.  These should be updated, so say ''yes'' or start <tt>generate_apacheconf ''archive_id''</tt> later.
 +
* Before exiting, <tt>epadmin</tt> will display information about configuring the webserver.
  
 
====example configuration====
 
====example configuration====
Line 64: Line 66:
 
  Hostname? eprints.adastral.ucl.ac.uk
 
  Hostname? eprints.adastral.ucl.ac.uk
 
  Webserver Port [80] ? 80
 
  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:
 +
eprints.adastral
 +
eprints
 +
Enter a single hash (#) when you're done.
 +
Alias (enter # when done) [#] ? eprints.adastral
 +
Redirect entw-server to entw-server.grs.de [yes] ?
 
  Alias (enter # when done) [#] ? #
 
  Alias (enter # when done) [#] ? #
 +
Please enter the path part of the repository's base URL. This should probably be '/'.
 +
Path [/] ?
 +
If you will use https for your user pages (including login) enter the https hostname
 +
here, or leave blank when using http only.
 +
Hostname?
 
  Administrator Email? *******@adastral.ucl.ac.uk
 
  Administrator Email? *******@adastral.ucl.ac.uk
 
  Archive Name [Test Repository] ? UCL Adastral Park Repository
 
  Archive Name [Test Repository] ? UCL Adastral Park Repository
Line 76: Line 91:
 
  Database Password?  
 
  Database Password?  
 
  Write these database settings? [yes] ? yes
 
  Write these database settings? [yes] ? yes
  Create database "uclapr" [yes] ? yes
+
  Create database "uclapr" [yes] ?  
  MySQL Root Password?  
+
  Database Superuser Username [root] ?
  Create database tables? [yes] ? yes
+
Database Superuser Password?  
  Create an initial user? [yes] ? yes
+
  Create database tables? [yes] ?
  Enter a username [admin] ? admin
+
  Create an initial user? [yes] ?
  Select a user type (user|editor|admin) [admin] ? admin
+
  Enter a username [admin] ?
 +
  Select a user type (user|editor|admin) [admin] ?
 
  Enter Password? *****************
 
  Enter Password? *****************
 
  Email? *******@adastral.ucl.ac.uk
 
  Email? *******@adastral.ucl.ac.uk
  Do you want to build the static web pages? [yes] ? yes
+
  Do you want to build the static web pages? [yes] ?
 
  Do you want to import the LOC subjects? [yes] ? no (I have a custom subject file)
 
  Do you want to import the LOC subjects? [yes] ? no (I have a custom subject file)
 
  Do you want to update the apache config files? (you still need to add the 'Include' line) [yes] ? yes  
 
  Do you want to update the apache config files? (you still need to add the 'Include' line) [yes] ? yes  
 
  
 
Open a browser, and enter the hostname in the address bar.  You should see your new archive, ready to be [[Branding with confidence|branded]].
 
Open a browser, and enter the hostname in the address bar.  You should see your new archive, ready to be [[Branding with confidence|branded]].
  
If you want to add some more users, use the command <tt>epadmin add_user <repository id></tt>
+
If you want to add some more users, use the command <tt>epadmin create_user <repository id></tt>.
  
==Maintenance (required)==
+
==Regular Maintenance==
  
 
EPrints front end web pages and abstracts *are not* automatically updated when you make changes to the repository.
 
EPrints front end web pages and abstracts *are not* automatically updated when you make changes to the repository.
Line 99: Line 114:
  
 
===Generate Views===
 
===Generate Views===
   eprints@host$ bin/generate_views yourarchivename
+
   eprints@host$ bin/generate_views ''yourarchivename''
  
 
===Generate Statics===
 
===Generate Statics===
   eprints@host$ bin/generate_static yourarchivename
+
   eprints@host$ bin/generate_static ''yourarchivename''
  
 
===Generate Abstracts===
 
===Generate Abstracts===
 
   eprints@host$ bin/generate_abstracts yourarchivename
 
   eprints@host$ bin/generate_abstracts yourarchivename
 +
 +
Finally a restart of your apache server is recommended, because a lot of settings will only be read initially!

Revision as of 10:05, 18 November 2010

Creating an Archive

EPrints 3 can run multiple archives under one install. Multiple archives will require giving additional DNS aliases to the machine running EPrints, EPrints can then create all the parts of the apache configuration file needed to run the virtual hosts.

Running epadmin

Make sure MySQL is actually running.

Change to your eprints user (probably eprints).

Change directory to the eprints directory (/opt/eprints3 by default) and run

bin/epadmin create

You will get the following prompts (note that when you see something in [square brackets], it's the default value and can be selected by simply hitting <enter>):

  • Archive ID - the system name for your archive. It's probably a good idea to think of something short and memorable. Once entered, an archive/<archive_id> directory will be created, and the standard configuration files will be copied in.
  • Configure vital settings - Hit enter to say 'yes'. This will lead to more prompting about core settings:
    • Hostname - What someone will type into a web browser to get to your archive. Make sure that your systems team have a DNS alias pointing to your server for this.
    • Webserver Port - Which port do you want to serve the archive on? The default is 80, so unless you can think of a good reason not to, just hit enter to accept the default.
    • Alias - You can enter any number of aliases that will take users to this archive. Enter a '#' when you don't want to enter any more. You could have your archive served on eprints.myorganisation.org and eprints.myorg.org. As with the Hostname, your systems team need to be informed about these aliases too.
      • Redirect your chosen alias to Hostname - Yes, usually that is your intention.
    • Please enter the path part of the repository's base URL - Make it simple for you and your visitors ... and confirm the suggestion; multiple archives could be managed by different domains or ports!
    • If you will use https for your user pages (including login) enter the https hostname - No doubt, for secure usage you need another name.
    • Administrator Email - Enter the email address of the repository administrator. This will allow your repository users to send email to the right person.
    • Archive Name - The full name of your archive. By default, this will be used on many of the pages, and in the title bar of the browser.
    • Write these core settings - If you don't say 'yes', then you entered all that data for nothing (relaunch the process by epadmin config_core archive_id).
  • Configure database - EPrints makes extensive use of a MySQL database. Enter 'yes' to launch epadmin config_db archive_id.
    • Database Name - The internal name of your database. It makes sense to use the Archive ID for this, but you don't have to. You don't need to create this database, epadmin will do it for you.
    • MySQL Host - The address of the server that the database is running on. If the database is on the same machine as the EPrints installation, confirm 'localhost'.
    • MySQL Port - You probably don't need to enter a value. If you have problems connecting to the database, talk to your systems team.
    • MySQL Socket - As with MySQL Port, it's unlikely that you need to enter anything.
    • Database User - The username with which to log into the MySQL Database. You don't need to create this user, epadmin will do it for you. If you enter a MySQL username that already exists, it will be overwritten by epstats!
    • Database Password - Just confirm the suggested password for the Database User, eprints will keep track of it!
    • Write these database settings - You should write them, or you'll lose them.
  • Create database <Database Name> - Say yes to launch epadmin create_db archive_id, and epadmin can create the database and populate it with all the right tables. If you've already created a database and a user for this archive, say 'no'.
    • Database Superuser Username - 'root' isn't a bad suggestion, but should match your specifications during the MySQL installation.
    • Database Superuser Password - To create the database and the user, epadmin needs the MySQL Root Password (specified during MySQL installation). This is not saved anywhere. It is only used to log into MySQL, create the database and create the user with useful access rights. The password is forgotten afterwards, because it's not needed anymore!
  • Create database tables - say 'yes' to have epadmin create all the database tables, i.e. initiate the same as with epadmin create_tables archive_id.
  • Create an initial user - It's a good idea to create a user account for yourself at this point, but you can start the same process by epadmin create_user archive_id anytime ...
    • Enter a username - The username you will be used to log into EPrints on the home page of the new archive.
    • Select a user type (user|editor|admin) - There are three user roles in EPrints. You probably want to be an administrator, so enter 'admin'.
    • Enter Password - A password for this user. Remember to choose a password that will be hard for someone else to guess!
    • Email - Enter your email address so that users can get in contact with you.
  • Do you want to build the static web pages - There are a number of pages in EPrints which change very rarely. These are the static pages. The Home page and the About page are examples of static pages. Stylesheets are also static. These pages need to be built, so say 'yes' (otherwise you have to start that process manually later by generate_static archive_id).
  • Do you want to import the LOC subjects - If you will be using the Library Of Congress subject hierarchy, say 'yes'. Otherwise you will need to create your own subject hierarchy and to import them using import_subjects.
  • Do you want to update the apache config files? (you still need to add the 'Include' line in the very central http.conf, e.g.) - Your archive has a number of files which it uses to configure the web server. These should be updated, so say yes or start generate_apacheconf archive_id later.
  • Before exiting, epadmin will display information about configuring the webserver.

example configuration

The script will run through a number of configuration options, an example of which is listed below. Please change the settings to suit your site configuration.

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? uclapr
We need to create /var/lib/eprints3/archives/uclapr, doing it now...
Getting uid and gid information for apache
UID: 48
GID: 48
Configure vital settings? [yes] ? yes
Hostname? eprints.adastral.ucl.ac.uk
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:
eprints.adastral
eprints
Enter a single hash (#) when you're done.
Alias (enter # when done) [#] ? eprints.adastral
Redirect entw-server to entw-server.grs.de [yes] ?
Alias (enter # when done) [#] ? #
Please enter the path part of the repository's base URL. This should probably be '/'.
Path [/] ? 
If you will use https for your user pages (including login) enter the https hostname
here, or leave blank when using http only.
Hostname?
Administrator Email? *******@adastral.ucl.ac.uk
Archive Name [Test Repository] ? UCL Adastral Park Repository
Write these core settings? [yes] ? yes
Configuring Database for: uclapr
Database Name [uclapr] ? *********
MySQL Host [localhost] ? localhost
MySQL Port (# for no setting) [#] ? 
MySQL Socket (# for no setting) [#] ? 
Database User [******] ? 
Database Password? 
Write these database settings? [yes] ? yes
Create database "uclapr" [yes] ? 
Database Superuser Username [root] ?
Database Superuser Password? 
Create database tables? [yes] ?
Create an initial user? [yes] ?
Enter a username [admin] ?
Select a user type (user|editor|admin) [admin] ?
Enter Password? *****************
Email? *******@adastral.ucl.ac.uk
Do you want to build the static web pages? [yes] ?
Do you want to import the LOC subjects? [yes] ? no (I have a custom subject file)
Do you want to update the apache config files? (you still need to add the 'Include' line) [yes] ? yes 

Open a browser, and enter the hostname in the address bar. You should see your new archive, ready to be branded.

If you want to add some more users, use the command epadmin create_user <repository id>.

Regular Maintenance

EPrints front end web pages and abstracts *are not* automatically updated when you make changes to the repository. To apply your changes and update the web pages:

Generate Views

 eprints@host$ bin/generate_views yourarchivename

Generate Statics

 eprints@host$ bin/generate_static yourarchivename

Generate Abstracts

 eprints@host$ bin/generate_abstracts yourarchivename

Finally a restart of your apache server is recommended, because a lot of settings will only be read initially!