Installation
============

Install mysql [not necessary if connecting to a remote MySQL server].

	% fink install mysql
	% sudo daemonic enable mysql


Install Apache [with SSL if required]. OR: just use the built-in Apache
(1.3.3), as it seems to just work out of the box with this (with
mod_perl 1.x).

	% fink install apache2[-ssl]
	% sudo daemonic enable apache2


Perl 5.8.1 (10.3) or 5.8.6 (10.4) should already be there.


Install the latest version of the Perl CGI package (need at least 3.08
for mod_perl 2).


Install mod_perl 2 [note mod_perl 1 is already included with the
built-in Apache 1.3]. No Fink package), so must install manually. This
includes the Apache and Apache2 Perl modules required by ePrints.
Presumably it will build to whatever the current system version of Perl
is.

	% perl Makefile.PL MP_APXS=/sw/sbin/apxs
	% make
	% make test
	% sudo make install


Install required Perl modules.

	% fink install data-showtable-pm		[Data::ShowTable]
	% fink install dbi-pm58x				[DBI]
	% fink install dbd-mysql-pm58x			[DBD::MySQL]
	% fink install mime-base64-pm58x		[MIME:Base64]
	% fink install unicode-string-pm58x		[Unicode::String]
	% fink install xml-parser-pm58x			[XML::Parser]

	Msql-Mysql Module: It appears that this is actually the DBD::MySQL
	module. Apparently this requires access to .h and library files from
	MySQL.
	
	Maybe (but probably not) CGI, Carp, Cwd, Data::Dumper, Digest::MD5,
	File::Basename, File::Copy, File::Find, File::Path, Getopt::Long,
	Pod::Usage, Sys::Hostname
	
	Probably worth installing the most recent version of the CGI module,
	as it fixes a known forms problem with Apache 2 [not necessary for
	Apache 1 unless you have a really old version]. Can't install with
	Fink as it only lists it as a virtual package. Install manually with
	cpan instead.

	Install XML::GDOME if required. Leave this for now as it's easier to
	set up without it. It needs XML-LibXML-Common, XML-NamespaceSupport,
	XML-GDOME. Download from http://gdome2.cs.unibo.it/#downloads.


Install miscellaneous utilities (if necessary) [note these are only
needed for compressed file uploads and snarfing documents from URLs ---
I think both features can be turned off].

	% fink install wget
	
	Tar, gunzip and unzip are all base Fink packages and thus available
	by default.


Install tools for full-text indexing (if necessary).

	% fink install xpdf [for pdftotext]
	% fink install lynx
	% fink install wv2 [= wvware]


Install LaTeX support tools (if necessary).

	% fink install tetex [for latex, dvips]
	% fink install imagemagick [for convert]


Install ePrints.

	% sudo mkdir /Library/Perl/5.8.x/darwin-thread-multi-2level
	[if it doesn't already exist]
	
	% cd /usr/include
	% sudo /usr/bin/h2ph * */* [to set up free space checking]
	[this will probably eventually become (??)
	/usr/bin/h2ph -d /sw/lib/perl5/5.8.1/darwin * */*]
	
	% pushd bin; sed -i -e "s/deny, allow/deny,allow/g" generate_apacheconf; chmod 755 generate_apacheconf; popd
	[Apache treats "deny, allow" as two separate arguments and complains]

	EPrints needs to be installed as the same user as the apache
	webserver runs as. We suggest you install it as user "eprints" and
	group "eprints". Apache will need to be reconfigured to run as this
	user if so. I won't bother for the quick and dirty test --- I'll
	just run ePrints as "www/www".
	
	% ./configure --prefix=/usr/local/eprints --with-user=www --with-group=www --with-apache=2 --with-smtp-server=whatever
	% sudo ./install.pl


Setup
=====

Start and configure MySQL.

	% sudo /Library/StartupItems/daemonic-mysql/daemonic-mysql start
	% mysql -u root
	
	Set root passwords. It appears that you need to use the old password
	model for compatibility with the current version of DBI::MySQL.
	Without old password format, you can't connect to the database
	("Client does not support authentication protocol").

	mysql> SET PASSWORD FOR 'root'@'localhost' = OLD_PASSWORD('bl@rgh');
	mysql> SET PASSWORD FOR 'root'@'ou075110.otago.ac.nz' = OLD_PASSWORD('bl@rgh');
	
	Remove anonymous accounts.
	
	mysql> DELETE FROM mysql.user WHERE User = '';
	mysql> FLUSH PRIVILEGES;


Configure ePrints.

	% sudo -s -u www
	% cd /usr/local/eprints
	% ./bin/configure_archive

	Doesn't seem to like unusual characters in the database password.
	(barnacle)

	% ./bin/generate_apacheconf
	% ./bin/create_tables archive_test_1
	
	% ./bin/import_subjects archive_test_1
	- If you do not specify the subjects file name then the system will
	use "subjects" from the given archive's cfg directory.
	- Must answer "yes" in full to continuation prompt.
	
	% ./bin/generate_static archive_test_1
	% ./bin/create_user archive_test_1 admin nstanger@infoscience.otago.ac.nz admin blobby
	% ./bin/generate_views archive_test_1
	% ./bin/generate_abstracts archive_test_1
	
	% ./bin/indexer start
	[starts up the indexer daemon, otherwise no indexes are built!]
	

Configure and (re)start Apache.

	Add to httpd.conf:
		User www [should be this already]
		Group www [should be this already]
		LoadModule perl_module /sw/lib/apache2/modules/mod_perl.so
		PerlHeaderParserHandler "sub { tie *STDOUT, 'Apache' unless tied *STDOUT; }"
		Include /usr/local/eprints/cfg/apache.conf
		[For Apache 1.3:
		LoadModule perl_module        libexec/httpd/libperl.so
		AddModule mod_perl.c
		]
	
	% sudo apachectl stop [/usr/sbin/apachectl for Apache 1.3]
	% sudo apachectl start [note: restart doesn't reload the configs!]


Maintaining the system
======================

- bin/indexer must be running in the background for searching to work.
- must run bin/generate_views periodically to rebuild the browse view pages.


Advanced configuration
======================

	You can configure the archive to run on a different domain on the
	same machine, while leaving the "primary" domain intact.
	
	In httpd.conf:
	
		- uncomment "NameVirtualHost *:80"
		- add:
			<VirtualHost *:80>
				ServerName primary1.domain.name
				ServerName primary2.domain.name
				ServerAdmin admin@primary.domain.name
			</VirtualHost>

	In archive config XML file:
	
		<host>archive.domain.name</host>
		<adminemail>archive-admin@archive.domain.name</adminemail>
	
	Then ./bin/generate_apacheconf and restart Apache.
	
	You can also run on a different port to make things easier.
	(Remember to enable the Port and Listen directives in httpd.conf
	appropriately, and to let the ports through the firewall if
	necessary.)
	
	Much better, here are actual instructions!
	<http://wiki.eprints.org/w/EPrints2/EPrintsSetupUnderVirtualDirectoriesOtherThanRoot>


Appearance
==========

Note for dynamically generated pages: they don't seem to handle XHTML
comments properly, adding an extra unnecessary layer of <!-- --> around
them, which makes the pages display weirdly. Better not to have any
comments :)

If you change any of the templates (especially the top-level site template),
you will need to generate_static, generate_abstracts, generate_views and
possibly force_config_reload (or better, restart Apache).

	ARCHIVE/cfg/template-en.xml		global page template (customise header & footer)
	ARCHIVE/cfg/static/en/*			individual static page templates (e.g., info page)
	ARCHIVE/cfg/general/*			CSS templates and standard images

If you want to get a list of the latest items added on the front page,
turn on SSI in httpd.conf then turn on Includes and XBitHack in
ARCHIVE/cfg/apache.conf.

	httpd.conf:
		uncomment "AddType text/html .shtml" and "AddHandler server-parsed .shtml"
		ensure that mod_include is enabled
	
	ARCHIVE/cfg/apache.conf: add
		<Directory "/usr/local/eprints/archives/ARCHIVEID/html">
		  Options +Includes
		  XBitHack on
		</Directory>
	
	Finally (fortunately permissions seem to be preserved when the HTML
	verison is generated):
		% chmod +x ARCHIVE/cfg/static/en/index.xpage


Security
========

The most obvious way to set up a repository where only certain people can
see the contents is to create a separate private repository on a different port,
with no public registration.

Creating new user types appears to involve adding stuff to
metadata-types.xml, phrases-en.xml and ArchiveConfig.pm.