Difference between revisions of "Getting Started with EPrints 3"

From EPrints Documentation
Jump to: navigation, search
m (Typo correction in "Running epadmin...Create an initial user...Enter a username" section as follows: The username you will be used -> The username you will use)
(Two pages about basically the same thing is confusing. The "Getting Started" page should be fine as no-one uses anything but EPrints 3.x)
(Tag: New redirect)
 
Line 1: Line 1:
[[Category:Manual]]
+
#REDIRECT [[Getting Started]]
[[Category:Management]]
 
[[Category:Installation]]
 
==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.
 
 
 
Alternatively you can use different ports to distinguish your different repositories hosted by the same server.
 
 
 
===Running epadmin===
 
Make sure MySQL is actually running.
 
 
 
Change to your eprints user (probably ''eprints'').
 
 
 
Change directory to the eprints directory (<tt>/opt/eprints3</tt> by default for a source install and <tt>/usr/share/eprints</tt> for packaged installs) and run
 
 
 
bin/epadmin create
 
 
 
If you are running EPrints 3.4 or later you will need a further parameter to define which flavour of repository you want.  The common two choices are either '''pub''' or '''zero''':
 
 
 
bin/epadmin create pub
 
 
 
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.
 
* 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 <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.
 
** 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 <tt>epadmin config_core ''archive_id''</tt>).
 
* 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, <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, 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, <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 - 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.
 
* 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'.
 
** 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 by this process!
 
* 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>.
 
* 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 ...
 
** Enter a username - The username you will use 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 <tt>generate_static ''archive_id''</tt>).
 
* 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 import it using [http://wiki.eprints.org/w/API:bin/import_subjects <tt>import_subjects</tt>].
 
* 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====
 
 
 
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.
 
 
 
<pre>
 
-bash-4.1$ ./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? testrepo 
 
We need to create /usr/share/eprints/archives/testrepo, doing it now…
 
 
 
Creating initial files:
 
Installing: /usr/share/eprints/archives/testrepo/cfg
 
Installing: /usr/share/eprints/archives/testrepo/cfg/lang
 
[...]
 
Installing: /usr/share/eprints/archives/testrepo/cfg/workflows/eprint
 
 
 
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 then 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] ?
 
Core configuration for testrepo
 
 
 
 
 
Please enter the fully qualified hostname of the repository.
 
 
 
For a production system we recommend against using the real hostname of the
 
machine.
 
 
 
Example: testrepo.footle.ac.uk
 
 
 
Hostname? testprint
 
 
 
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] ?
 
 
 
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:
 
centos610.local
 
centos610
 
centos610
 
 
 
Enter a single hash (#) when you're done.
 
 
 
Alias (enter # when done) [#] ? testprint.local
 
Redirect testprint.local to testprint [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.
 
 
 
HTTPS Hostname [] ?
 
 
 
 
 
Administrator Email? someone@example.com
 
 
 
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] ?
 
 
 
Write these core settings? [yes] ?
 
Wrote /usr/share/eprints/archives/testrepo/cfg/cfg.d/adminemail.pl
 
Wrote /usr/share/eprints/archives/testrepo/cfg/cfg.d/10_core.pl
 
Wrote /usr/share/eprints/archives/testrepo/cfg/lang/en/phrases/archive_name.xml
 
 
 
Configure database? [yes] ?
 
 
 
Configuring Database for: testrepo
 
Database Name [testrepo] ?
 
MySQL Host [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 [testrepo] ?
 
Database Password [nxxxxuAw] ?
 
Database Engine [MyISAM] ?
 
 
 
Write these database settings? [yes] ? 
 
Wrote /usr/share/eprints/archives/testrepo/cfg/cfg.d/database.pl
 
 
 
EPrints can create the database, and grant the correct permissions.
 
 
 
Create database "testrepo" [yes] ?
 
Database Superuser Username [root] ?
 
Database Superuser Password?
 
Create database tables? [yes] ?
 
Creating database tables...
 
Set DB compatibility flag to '3.3.4'.
 
Done creating database tables.
 
 
 
 
 
Create an initial user? [yes] ?
 
Creating a new user in testrepo
 
 
 
Enter a username [admin] ?
 
Select a user type (user|editor|admin) [admin] ?   
 
Enter Password?
 
Email? first.last@example.org
 
 
 
 
 
Successfully created new user:
 
      ID: 1
 
Do you want to build the static web pages? [yes] ?
 
 
 
Starting EPrints Repository.
 
Connecting to DB ... done.
 
mkdir /usr/share/eprints/archives/testrepo/html/en/codemirror/mode/velocity
 
/usr/share/eprints/lib/static/codemirror/mode/velocity/velocity.js -> /usr/share/eprints/archives/testrepo/html/en/codemirror/mode/velocity/velocity.js
 
mkdir /usr/share/eprints/archives/testrepo/html/en/style/images
 
/usr/share/eprints/lib/static/style/images/action_edit.png -> /usr/share/eprints/archives/testrepo/html/en/style/images/action_edit.png
 
[...]
 
/usr/share/eprints/lib/static/style/images/action_unpack.png -> /usr/share/eprints/archives/testrepo/html/en/style/images/action_unpack.png
 
/usr/share/eprints/lib/static/codemirror/lib/util/loadmode.js -> /usr/share/eprints/archives/testrepo/html/en/codemirror/lib/util/loadmode.js
 
Ending EPrints Repository.
 
 
 
Do you want to import the LOC subjects? [yes] ?
 
 
 
Starting EPrints Repository.
 
Connecting to DB ... done.
 
Importing from /usr/share/eprints/archives/testrepo/cfg/subjects...
 
Done importing 280 subjects from /usr/share/eprints/archives/testrepo/cfg/subjects
 
Reindexing subject dataset to set ancestor data
 
Reindexing item: subject/A
 
Reindexing item: subject/AC
 
Reindexing item: subject/AI
 
Reindexing item: subject/AM
 
[...]
 
Reindexing item: subject/sch_soc
 
Reindexing item: subject/subjects
 
Done reindexing
 
Ending EPrints Repository.
 
 
 
Exiting normally.
 
Do you want to update the apache config files? (you still need to add the
 
'Include' line) [yes] ?
 
Wrote /usr/share/eprints/cfg/apache/testrepo.conf
 
 
 
You must restart apache for any changes to take effect!
 
 
 
--------------------------------------------------------------------------
 
That seemed to more or less work...
 
--------------------------------------------------------------------------
 
 
 
Now make any required changes to the cfg files.
 
 
 
Note that changing the metadata configuration may require the database
 
tables to be regenerated. epadmin erase_data will regenerate the
 
eprints and documents tables only. erase_data will regenerate everything.
 
(nb. these also do erase the contents of the tables, and any uploaded
 
files).
 
 
 
Make sure that your main apache config file contains the line:
 
 
 
Include /usr/share/eprints/cfg/apache.conf
 
 
 
Then stop and start your webserver:
 
Often:
 
/etc/rc.d/init.d/httpd stop
 
/etc/rc.d/init.d/httpd start
 
(or maybe /usr/local/apache/bin/apachectl stop & start)
 
 
 
And then try connecting to your repository.
 
--------------------------------------------------------------------------
 
 
 
Don't forget to register your repository at http://roar.eprints.org/
 
 
 
-bash-4.1$
 
 
 
</pre>
 
 
 
Finish apache's configuration before its final restart to be ready for opening a browser and watch the homepage of your new archive, ready to be [[Branding with confidence|branded]].
 
 
 
If you want to add some more users, use the command <tt>epadmin create_user <repository id></tt> or the admin's web dialog.
 
 
 
==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!
 

Latest revision as of 11:36, 4 October 2023

Redirect to: