INSTALLATION GUIDE

boreddizzyΔιαχείριση Δεδομένων

16 Δεκ 2012 (πριν από 5 χρόνια και 21 μέρες)

213 εμφανίσεις

JERRYMOUSE
(C2i Registration System)
INSTALLATION GUIDE
Nicolas Dorotte
2
Contents
1 System requirements 3
1.1 Operating System..............................3
1.2 Database...................................3
1.3 Java.....................................3
1.4 Web Server.................................3
1.5 Apache Ant.................................4
1.6 Final note..................................4
2 Installation instructions 5
2.1 Get the sources...............................5
2.2 Execute the ant script...........................5
2.3 Set up the database.............................5
2.4 Deploy the web application.........................6
2.5 End of installation.............................7
3 Developpement 8
4 Troubleshooting 9
System requirements 3
1 Systemrequirements
1.1 Operating System
All the application has been extensively tested on Gentoo Linux (2.6.14),and partly
on Microsoft Windows XP SP2.However it was meant to be as platform-independent
as possible so you can easily port it to other OSes.
Nevertheless,this guide has been written for a Unix-like installation,therefore we leave
it to the reader to adapt the commands to his own platform.
Note:You might want to ensure that your system date and time are correct because
the application performs some date and time checking.
1.2 Database
This is the most dependant part of our application but as it was developed using
Java/JDBC technology and SQL standards you can port it to nearly all databases
with minimum effort,providing that you have JDBC drivers for your SQL-compliant
database.
However,we want to draw your attention to the fact that MySQL does not fully cover
all SQL functionalities,so we had to turn to PostgreSQL,freely available on many
platforms.
1.3 Java
Our application uses some of Java 5 new features (e.g.generics),so it is necessary that
the JVM on the server is up-to-date,otherwise the system will not compile.
Plus,a web application needs J2EE libraries.Hence you must install it.
Attention:activation.jar,mail.jar and j2ee.jar must be in your CLASSPATH (you
can find them in the lib directory of your J2EE installation).
1.4 Web Server
We developed and tested thoroughly our system using a Tomcat server.But we have
also tested its deployment under Sun AppServer and JBoss.
Other ones have yet to be tested,but hopefully the structure of a WAR file makes it
server independent,and other servers might be used.
Attention:JerryMouse uses JVM system properties to store important configura-
tion values.For security reasons,most server does not allow applications to do so,
therefore,if your server is concerned by this remark,it is necessary that you edit the
server.policy configuration file.
System requirements 4
Just replace the following line:
permission java.util.PropertyPermission"
*
","read";
by this one:
permission java.util.PropertyPermission"
*
","read,write";
1.5 Apache Ant
To ease the installation process we provide an Apache Ant build script.You might
want to install it in order to perform a quick installation.
1.6 Final note
All of the listed programs here (or equivalents) have to be correctly installed in order
for the systemto work.You might want to ensure that all of themare working properly,
and that correct pathes are set.
Installation instructions 5
2 Installation instructions
2.1 Get the sources
First of all,if you don’t have them yet,you have to download the archive containing
the latest sources.You can get them at the following address:
http://jerry-mouse.dyndns.org/files/jerrymouse.tar.gz
Download this archive to your machine,and extract it,issuing the following command
in a shell (of course we suppose you are in the directory where you downloaded the
file):
$ tar xvzf jerrymouse.tar.gz
If your system fulfils the system requirements,you can proceed with the installation.
2.2 Execute the ant script
Now you need to compile the application,set up the database and deploy it in the
servlet container.Hopefully,an ant script is there to do all of this for you (well,almost),
providing the good informations.
Just go to the directory you have just extracted and type:
$ cd jerrymouse
$ ant
During the build process,you will be prompted some questions.We shall explain each
one of them in details in the following.
2.3 Set up the database
config:
[echo] --------- Database informations ---------
[input] Enter the url of your postgresql server [localhost]:
Here you have to enter the hostname of the machine running your PostgreSQL server.
If it is running on your machine,just type enter and the script will use localhost by
default.Otherwise,you must enter the exact address or the installation process will
fail.
[input] Enter the name of your database [c2i]:
Installation instructions 6
You must choose a database name,enter whatever fits your needs (if nothing is typed,
c2i will be used).
Attention:You must ensure that a database with this name is not already defined
or build will fail.
[input] Enter user name for connecting to the database [postgres]:
[input] Enter password:
You must have permission to create databases on the server with valid user name and
password.postgres is the default user.
[input] Enter default domain name for students addresses [u-cergy.fr]:
Students who haven’t created their account yet can be notified by mail,asking them
to register to the system.In order to send them a mail we have to know a valid email
address.The default one will be:firstname.lastname@u −cergy.fr.This is where
you can change the default domain name.
[echo] --------- Informations for ’admin’ account ---------
[input] Enter your first name [none]:
[input] Enter your last name [none]:
[input] Enter password:
We have to create at least one administrator account so that you can use the system.
This is where you provide information about it.The login for this account is admin
and the password is the one you just entered.
2.4 Deploy the web application
You now need to specify the name and destination path of your webapp:
config:
[echo] --------- Web Application Informations ---------
[input] Enter a context name for the application [C2i]?
[input] Where will it be deployed?[/opt/tomcat5/webapps]
Default is/opt/tomcat5/webapps,but on your machine it might be the value of
$CATALINA
HOME if your using Tomcat.For other servers please refer to your server
manual.
[input] Enter a SMTP server for sending mails [smtp.easyconnect.fr]
[input] Enter an email address which will be used to send
notifications to users?[jerry-mouse@easyconnect.fr]
Installation instructions 7
Finally,provide valid SMTP server address and email.It will be used to send notifica-
tions and other informations related to the system to the users.
Note:The email address you will give here will be used for the admin account of the
system.
2.5 End of installation
If you made it through each and every step successfully,and providing that your Web
Server is started,the JerryMouse system might be up and running.Just type the
address of your context in a browser,and enjoy!
For troubleshooting see Section 4.
Developpement 8
3 Developpement
If you are a developer,you might want to use the following targets (or define new ones).
To get a list of the availables ones,just type:
$ ant -projecthelp
archive
Generate a tar named jerrymouse.tar.gz containing all sources (what you have down-
loaded for installation)
clean
Delete repertories build and dist
cvs
Providing the good cvsroot parameters,it downloads the latest sources from CVS (de-
fault CVSROOT is/var/lib/cvsd/root)
doc
Generates javadoc in a repertory called doc.
db-drop
Use it to uninstall a previous database.
install
See section 2
mrproper
Call clean target and delete doc
src-*
See src/build.xml
uninstall
Ask for information,then delete the webapp in question
webapp
Generate a WAR file from sources
Developpement 9
4 Troubleshooting
Problem:When I try to identify on the web site I get the following exception:
org.postgresql.util.PSQLException:L’indice de la colonne est hors
limite:3,nombre de colonnes:2.
Solution:They are some compatibility issues with the lasted JDBC driver provided
with our application and previous versions of PostgreSQL,unfortunately some features
weren’t implanted in previous drivers so we must use the present one.
Anyway,to fix the problem you can edit the config.properties in WEB-INF/conf/
and replace the following line:
jerrymouse.driverFirstIndex=1
by this one:
jerrymouse.driverFirstIndex=2
Problem:When I try to access the web site,I get redirected to HTTPS and connec-
tion fails.
Solution:Your web server might not be configured to deal with HTTPS connections.
Either configure it using your web server documentation,or if you don’t care about
security (which is really not the best solution because every data passing between the
server and the client could be intercepted by a third person,especially passwords!!),
you could just disable HTTPS doing the following:
Edit the file named index.jsp in the base directory of the context.
And comment out the following lines:
if (request.getScheme().equalsIgnoreCase("http")) {
String URL = request.getRequestURL().toString();
response.sendRedirect("https"+ URL.substring(4));
}
which gives:
/
*
if (request.getScheme().equalsIgnoreCase("http")) {
String URL = request.getRequestURL().toString();
response.sendRedirect("https"+ URL.substring(4));
}
*
/
But you should really consider setting up HTTPS on your server.