2005-02-14
| Revision History | ||
|---|---|---|
| Revision 1.1 | 2005-03-22 | mb |
| Added Apache2 info | ||
| Revision 1.0 | 2004-09-10 | mb |
| revised for hyperjournal 0.4 stable | ||
| Revision 0.2 | 2004-03-31 | mb |
| second draft | ||
| Revision 0.1 | 2004-02-14 | mb |
| first draft | ||
Abstract
The HyperJournal installation manual is targeted to sysadmins, developers and hackers. Please note that installing HyperJournal requires at least basic knowledge of UNIX administration.
Table of Contents
This document, HyperJournal Installation Manual, is copyrighted (c) 2005 by Michele Barbera. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/copyleft/fdl.html.
No liability for the contents of this document can be accepted. Use the concepts, examples and information at your own risk. There may be errors and inaccuracies, that could be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility.
All copyrights are held by their by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements.
Many thanks to (in alphabetical order):
Francesca Di Donato <france (at) hjournal.org>
Riccardo Giomi <giomi (at) netseven.it>
Feedback on this document is welcome. Send your additions, comments and criticisms to the following email address : <barbera (at) netseven.it>.
HyperJournal requires a number of additional Open Source software and libraries. Prerequisites are different depending on if you want to use an external or an internal contextualization repository. We suggest, whenever possible, to use an internal one: it's much more efficient on terms of computational speed and bandwidth usage. Here is a list of common prerequisites:
PHP >= 5.0.1
The following PEAR packages:(refer to the PEAR web site and the section called “Step 1: Check Requirements” for additional information)
DB >= 1.7.0
File
HTTP
HTTP_Header
HTTP_Session
HTTP_Request
Net_Socket
Net_URL
HTML_TreeMenu
You will also need the following PHP Extensions
Mysql
GD2
lib JPEG
Make sure to adjust the following values in your php.ini:
magic_quotes_gpc must be OFF
safe_mode must be OFF
upload_max_filesize must be a suitable size
max_execution_time must be a suitable time (5 mins would be ok)
include_path must include the directory where the pear package are
If you want to install a local contextualization repository (strongly recommended!) you will also need:
Java >= 1.4.1
A servlet container (tested on Tomcat)
Sesame RDF Database version 1.2.x which can be found at www.openrdf.org
HyperJournal requires Sesame 1.2.x, pay attention not to install the latest 2.0 version, this is NOT supported by HyperJournal
This section provides a step-by-step guide to the installation process. Here we will assume that all the prerequisites are met (although the installation script will perform tests on most of the required libraries).
Download hyperJournalxxx.tar.gz from www.hjournal.org/downloads/ and untar it somewhere on your disk running the command tar -zxvf hyperjournalxxx.tar.gz then go to the new directory with cd hyperjournalxxx/
Before installing HyperJournal, you'll have to answer some questions about the configuration of your system.
Run ./configure.sh. The script will ask you some questions and propose a default answer for each question, based on its knowledge of your system settings.
The information you need include:
This is the full path of your web-server's configuration file. Some possibilities are: /etc/httpd.conf, /etc/httpd/httpd.conf, /etc/httpd/conf/httpd.conf, or /etc/apache/httpd.conf. The script automatically suggests you with one of these or searches in the /etc tree for a suitable file.
This is your web-server user name[1]
The directory where the www public part of HyperJournal will reside. This directory needs to be inside the webserver's document root.
The directory where the main part (APIs, libraries, data and other stuff) of HyperJournal will reside. Normally the default location (/opt) is ok and this value can be left unchanged.
Then become root and run make.
Check the paths are correct then run make install.
You can now delete the directory your are in. Just keep the file Makefile if you want to be able to automatically uninstall HyperJournal.
HyperJournal requires to access to a Sesame 1.2.x repository via HTTP. Sesame™ is an RDF Database available at www.openrdf.org
Install Sesame into a servlet container. (This means that you have to install Sesame as a server, and not as a library.) Please refer to its documentation for instructions on how to install Sesame™. After installing Sesame you must create a repository for HyperJournal. The easiest way to do so is to edit the WEB-INF/system.conf file of Sesame™. If this has not been done yet, you will have first to copy or rename the system.conf.example file in system.conf.
When all is done, you must restart tomcat for it to apply the changes.
The Hyperjournal GUI installer will then handle the modification of such configuration file to create a new repository. For this reason the user apache is running as (usually nobody or www or www-data) will need read andwrite access to this file
For more informations, you can refer to the Sesame™ manual
The last part of the installation process is managed by a GUI installer. If you know very well what you are doing, you can also skip this phase and directly set values in INSTALL_DIR/configuration.xml. The constant names are pretty self-explanatory (and we also suppose you know what are you doing if you choose editing this file directly :-) )
To run the GUI installer point your browser to the location where you installed HyperJournal (from now on HJOURNAL_WWW_ROOT) to the file setup.php (HJOURNAL_WWW_ROOT/setup.php) and follow the on-screen instructions.
This step checks the php version meets the requirments and searches your php environment for the required extensions and PEAR Packages.
If you see one or more red 'x', it means that a package is not found. If a PEAR package is missing first of all check that your php include path directive (in php.ini) includes the directory where PEAR packages are placed. To install a specific PEAR package you can use the PEAR cli installer (refer to the PEAR web site for additional information).
Some packages may be in its beta stage thus they cannot be installed via the PEAR cli install command. You need to manually download the beta packages and then issue a pear install /path/to/pear/packagename.tar.gz command.
Here you can set HyperJournal paths and URLs.
The full path to the directory where the the HyperJournal application is installed. With trailing slash.
The directory where the www public part of HyperJournal is installed. This directory needs to be inside the webserver's document root. With trailing slash.
The domain (better not to use an IP address) that points to your HyperJournal server. No trailing slash.
This will be concatenated to the HyperJournal Absolute URL to obtain the full URL of your HyperJournal instance. No traling slash.
Full path to the Sesame configuration file (including /system.conf). Please note that apache needs write access to this file
Select Yes if you have already created an empty mysql database for HyperJournal. Select No otherwise.
Here You can set-up a mysql database from scratch.
Mysql host name (default is localhost)
Insert a mysql user who has enough permissions to create databases and grant permissions to other users (default is root)
Password of the root (power) user.
Name of the mysql db that is going to be created for HyperJournal.
Name of the mysql user that is going to be created for HyperJournal.
Password of the mysql user that is going to be created for HyperJournal.
Here You can set-up an already existing mysql database.
Mysql host name (default is localhost)
Name of the mysql db to use for HyperJournal.
Name of a mysql user who has all permissions on the above database.
Password of the mysql user.
Here you must choose between using a local or a remote Sesame repository
As contextualization, which is the feature Sesame is mainly used for is EXPERIMENTAL as of HyperJournal 0.4, using a local repository is reccomended. However, if you want to fully exploit the power of contextualization you must share the sesame repository with other HyperJournals and, by doing so, enter a federation of HyperJournals. If you choose this option, contact the sesame repository administrator to obtain write access to that repository. In future versions will be no longer necessary to share the same repository to be part of a federation.
Here you must enter the connection parameters to connect to aremote Sesame repository. Ask its administrator if you are unsure.
Sesame host name
The port to be used to connect to host
The name of the repository to connect to
Username with write permissions
The user password
Here You can set-up an already existing mysql database.
Sesame host name
The port to be used to connect to host
Username with write permissions (It will be created automatically)
password (It will be created automatically)
The name of the mysql db used internally by Sesame (It will be created automatically)
The user of the mysql db used internally by Sesame (It will be created automatically)
The password of the mysql db used internally by Sesame (It will be created automatically)
Here you can create an administrator account.
The administrator password
The administrator email
This is a Persistant URL, see www.purl.org for additional information. Using a PURL is not mandatory but we storngly encourage you to register and use use a PURL, it's free. Using a PURL will save you A LOT of problems if in the future you want to move your HJ to another domain or if the dynamic contextualization system specifications, which are still Experimental, will change
Please choose a password carefully as in HyperJournal 0.4 there is no check of the password robustness
Please check the email adress twice as no test mails are sent to this address and its correctness IS NOT checked.
Here you can check if your php sendamil settings are correct. Yust insert an email address and see if you receive the test email. Sorry, this is the best we can do, we cannot configure a mail server for you (it's too annoying :-) )!
An external (non local) sendmail can be used instead of a local one. Please refer to the PHP manual for additional information on how to set up the sendmail configuration directive.
Here you can send us an automatically generated email to alert us of your hyperjournal's installation. The email we will recive contains only the name of your journal, it's URL and the software version. We will use the collected data only to warn you if critical bugs are discovered and to alert you of new releases of hyperjournal. Moreover it makes us happy to know that someone is using HyperJournal (in fact this is the second best thing after donations :-) ). Please consider registering (even if you're just trying and not using it for a in-production journal), we spend a lot of time in programming HyperJournal and it's free !!! Thank you very much!
It seems that your mail server isn't correclty configured. Be aware that without a running mailserver your journal users will not be alble to register, hence your journal will practically be unusable. If you know what you are doing and still want to proceed you can still register your hyperjournal installation to be alerted by us if critical bugs are discovered or if new releases are made available. You can register by manually sending us an email at info@hjournal.org with subject: "hjregistration" and the xml which is accessible from the GUI installer (right-clik, save-as) in the body (no attachments please!!!). Thank you very much!
The configuration of your hyper journal has been saved, now, if you are using a local Sesame repository, you must restart Tomcat and click next to upload the RDF ontology and to finish the hyper journal installation. Additionally you must put the hj-inference.xml file in the same directory of the sesame's system.conf configuration file before to click next. You can find the hj-inference.xml file in classes/rdf/hj-inference in the extracted hj package.
Failing to put the (apache readable) hj-inference.xml in the correct location will cause major malfunctioning of HyperJournal
You MUST now remove the setup.php script (found in HJOURNAL_WWW_ROOT/install.php). Log in with your administrator account and proceed to the control panel.
The installation process IS NOT finished yet. Check carefully all the directives in the Administrator control Panel. Especially under the journal panel, where it is important to configure the journal name and locations panel (do not change anything here except the True Type font paths).
It is is a test intallation you may also want to give all permissions to the Administrator, otherwise you will not be able to perform editing and publish articles. Refer to the user manual for more details.
Do not forget to configure the Earliest timestamp in Control Panel->OAI panel if you wish your journal to be OAI compliant
In order to be able to run the installer under Apache2 you must do the following:
Create a symlink from apachectl to apache2ctl
After running make install remove the lines containing rewrite rules from /etc/apache2/apache2.conf and move them to the suitable .conf file (usually somwhere under /etc/apache2/sites-enabled) depending on your system configuration. Restart apache.
[1] If you dont know your web-server's user name you can find it in the configuration file. (Search the file for a line beginning with User .) Alternatively you can search your etc/passwd for one of the most common names such as www, www-data, apache, nobody.