GeoLog Installation manual v1.0 - FER-a

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

28 Νοε 2012 (πριν από 4 χρόνια και 10 μήνες)

229 εμφανίσεις





















GeoLog

Installation Manual


Version

1.0


GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
3



Revision History


Date

Version

Description

Author

200
8
-
01
-
23

0.1

Initial Draft

Juraj Misur

2008
-
01
-
25

1.0

Final version

Juraj Misur










Doc. No.:





GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
4



Table of C
ontents

1.

Introduction

5

1.1

Purpose of this document

5

1.2

Document organization

5

1.3

Intended Audience

5

1.4

Scope

5

1.5

Definitions and acronyms

6

1.5.1

Definitions

6

1.5.2

Acronyms and abbreviations

6

1.6

Re
ferences

6

2.

General requirements

7

2.1

Operating system

7

2.2

External programs

7

2.3

Web browsers

7

3.

Installation procedure

7

3.1

Google Maps API key

7

3.2

Setting up database

8

3.2.1

HSQLDB

8

3.2.2

PostgreSQL

8

3.3

Deploying GeoLog

8

3.3.1

Tomcat manager

8

3.3.2

Manually

8

3.4

GeoLog setup process

8

4.

Configuration files

12

5.

Troubleshooting

Error! Bookmark not defined.

6.

GeoLog Live

13


GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
5



1.

Introduction


1.1

Purpose of this document


This document gives detailed information on how to deploy and run

GeoLog, describes initial setup
process and how to later configure GeoLog system properties.


1.2

Document organization


The document is organized
to following sections
:



Section 1,
Introduction,

contains general description of this document



Section 2,
Genera
l Requirements
,
contains description about technologies which are needed in order to
run GeoLog



Section 3,
Installation Procedure
, contains description of how to configure external programs such as
database before deploying GeoLog and also GeoLog setup pro
cess itself.



Section 4
,
Configuration files
, contains description of important configuration files if GeoLog needs to
be further customized or modified some settings after setup process.



Section 5,
Troubleshooting
, contains answers to most common problems.



Section 6,
GeoLog Live
, contains
URL

of GeoLog testing server.


1.3

Intended Audience


The intended audience is:



customers, who
will
use
GeoLog

on their own system



developers, who
are responsible for deployment or will continue to maintain GeoLog project



supe
rvisor
s
, who
may want to test

GeoLog


1.4

Scope


Scope of this document is to provide necessary information
for user
to be able to successfully run
GeoLog on intended system. It will discuss how to deploy and start the application, how to go through
initial se
tup process
,

which is needed for GeoLog to connect to database and setup other vital system
properties. It also gives information
on
how to modify configuration files so the application will be able
to adapt to changed environment.

This document does not g
ive information related to external technologies like Java application server,
database server or Java installation. Firstly, these technologies can vary from system to system and
secondly user who will deploy this application should be familiar with them.


GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
6



1.5

Definitions and acronyms


1.5.1

Definitions


Keyword

Definitions

Java Application

Server

Web server for Java web applications








1.5.2

Acronyms and abbreviations


Acronym or

abbreviation

Definitions

URL

Uniform Resource Locator
, here simply web address st
arting on http://...








1.6

References


Other GeoLog related document
s

can be found on GeoLog project site on FER
, or GeoLog SVN:



GeoLog Requirements Definition



GeoLog Design Description



GeoLog

Technical Documentation



GeoLog Developers Manual



GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
7



2.

Genera
l requirements


GeoLog was developed in Java programming language as web application using

database, therefore it’s
important

to setup these technologies and programs before trying to run GeoLog.


2.1

Operating system


GeoLog can be run on any operating system

for which there is Java 5 compatible runtime. This
includes mainstream systems such as Windows, Linux and MacOS.


2.2

External programs


The following
programs
are required by G
eoLog



Java 5 or higher

o

Java 5
,

6 or higher

(
Java 5 compatible
)

must be installed o
n system in order to run some other
programs. GeoLog was made compliant with Java 5.

o

Downloadable at
http://www.java.com/en/download/index.jsp



Java Application Server


o

GeoLog has been tested on Ap
ache Tomcat version 5.5 and 6.0. For more information please
see http://tomcat.apache.org/. Also any other Java application servers which support Java
Servlet 2.4 specification should be able to run GeoLog successfully.



Database

o

GeoLog has been tested with

HSQLDB (
http://hsqldb.org
) and PostgreSQL
(
http://www.postgresql.org
)

databases and provides direct support for these databases. Since it
uses Hibernate as database access frame
work, it supports any other well known database, but
for that it needs to be modified as described in
S
ection
4

Configur
ation files
.


2.3

Web browsers


GeoLog was tested and is
fully functional in the
se

br
owsers:



Mozilla Firefox 1.5 or higher



Internet Explorer 6 or higher



Opera 8
.5

or higher

JavaScript must be turned

on

for GeoLog to be fully functional (a
s it uses Google Maps API
).

3.

Installation procedure


In order to install GeoLog, Java Application Server

and HSQLDB or PostgreSQL database must be
running. User installing must also have write access to web applications directory on Application
server an
d know access
settings
for database.

3.1

Google Maps API key


For Google Maps to work correctly, you need Goog
le Maps API key. This can be obtained on
http://code.google.com/apis/maps/signup.html

after agreeing to the Terms of Use and filling in web site
URL
. This
URL

must be publicly available and the
key will work only for exact
URL

address you put
in. For GeoLog, you have to put whole path to
GeoLog

root directory,
e.g.

http://mydomain.org/geolog
.


GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
8



3.2

Se
tting up database

3.2.1

HSQLDB


Hsqldb is lightweight java datab
ase made for quick and easy development. Nothing have to be
installed, it’s run just like any other java application from jar file. When it starts

(by default on
localhost)
, only one database will be made and anybody will be able to connect to it (
therefor
e it’s

not
recommended for
public use).


Database will be started simply by entering this command to command line/shell:

java
-
classpath <path to hsqldb.jar> org.hsqldb.Server
-
database geolog


hsqldb
-
1.8.0.7.jar is included in GeoLog distribution and is i
n application’s WEB
-
INF/lib directory.


This will create database server listening on localhost:9001. Username is
sa

and password is not set.

Databa
se is only one and has no name (geolog is just temporary file
name
for hsqldb)
.


3.2.2

PostgreSQL


Installing and
setting up PostgreSQL is out of scope of this document. Only thing required for GeoLog
to run is fresh database and some user access to it (any db name, user name or password).


3.3

Deploying GeoLog


Since GeoLog is being distributed in form of a war file, the
re are many ways to deploy it to application
server. If using Apache Tomcat with Tomcat Web Application Manager installed, choose Tomcat
manager installation. Otherwise you will to deploy GeoLog manually.



3.3.1

Tomcat manager


Application server must be starte
d. Go to Tomcat Web Application Manager (expecting that you have
proper access to it) and to section Deploy
-
> WAR file to deploy. Click browse button, find GeoLog
war file and submit the form. GeoLog will be automatically uploaded to server, extracted and

started.
Manager will be refreshed and GeoLog will be listed as running application on /geolog context path.


3.3.2

Manually


Deployment can vary among application servers. If using Tomcat, just copy GeoLog war file to
Tomcat
webapp
s

directory. Tomcat should no
tice that

and start GeoLog automatically (
either
if it’s
running or started later).

Either way you should be familiar with configuring the application server.


3.4

GeoLog setup process


After starting GeoLog, setup pages will be first to see.
Setup process con
sists of 4 setup pages. Here is
step
-
by
-
step visual guide:

1.

1
st

Setup Page
:

a.

Public
URL

-

URL

of web server together with GeoLog context path, can be domain
name, IP address, or localhost based.

b.

Google API key


put here your key

c.

Database type


choose HSQLD
B or PostgreSQL

d.

URL

-


your database
URL

with port

e.

Database


database name

GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
9



f.

User name


database user name

g.

Password


database user password



Figure
1
:

Page 1


HSQLDB



Figure
2
:

Page 1


PostgreSQL

GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
10





2.

2
nd

Setup Page

a.

Me
ssage that connection to database was successful.


Figure
3
: Page 2


Database connection successful


b.

Some error occurred.

Please check settings again.


Figure
4
: Page 2



Database connect
ion unsuccessful


3.

3
rd

Setup Page

a.

Database will be filled with initial data. Now you have to provide some additional
settings.

i.

Login name


system administrator’s login name

(read
-
only)

ii.

Email address


system administrator’s email address

iii.

Password


system
administrator’s password

b.

SMTP settings (are not obligatory and can be changed later)

i.

SMTP server


URL

of

SMTP

server

ii.

Port


SMTP
server’s port for incoming messages

iii.

Authentication


check
ed

if server requires authentication

iv.

Sender address


from what emai
l address will GeoLog mails come

v.

User name


SMTP authentication user name

vi.

Password


SMTP authentication password

GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
11




Figure
5
: Page 3


System and SMTP settings


4.

4
th

Setup Page

GeoLog will confirm successful setup.
After that the s
etup pages will be deleted. If you didn’t
provide SMTP settings, you can do it later in system administration panel. Click finish and
you will be redirected to
fully functional
GeoLog
.


Figure
6
: Page 4


Setup Finished

3.5

After the
setup

There are some steps which are needed to do after the setup is complete:



If you didn’t provide valid SMTP settings during the setup process, don’t forget to login as
System administrator and go to System administration panel and configure SMTP settin
gs,
otherwise users wouldn’t be able to register (confirmation email won’t be sent). If you submit
correct SMTP settings, testing email will be sent.

NOTE: In the time of development, the
easiest

way to set up SMTP was to set SMTP server to

gmail
-
smtp
-
in
.l.google.com
’, it requires
no authentication, but it also doesn’t work
everywhere (only from trusted domains or so).

GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
12





Every article from deleted user is automatically reassigned to Guest. Its login is ‘guest’, so
anybody can try to login as Guest after the

installation. There are two options how to disable
this:

1.

Login as Guest and change the password
, or

2.

Ban Guest. You won’t be able to login as Guest (in reality there is no need for that)

and
this is much safer.



No Content administrator
will be present afte
r installation

therefore new registered users
won’t be able to submit new locations, because nobody will be assigned to any of predefined
categories. So it’s recommended to manually register new user, promote to Content
administrator and assign some catego
ries.


4.

Configur
ation files


GeoLog can be later configured via system administrator interfac
e, but some system information
(database settings,
G
oogle
API

key etc) can be only configured via certain configuration files. All files
reside in WEB
-
INF/classes d
irectory.

After editing
c
onfiguration file
s
, you should restart GeoLog for changes to make effect.


System.properties


Following properties are editable:



root.link


URL

to the root directory of GeoLog on web server
.

o

NOTE:
It’s
very
important that this
pr
operty
ends with slash ‘/’
, otherwise it might
break
URL
s inside GeoLog
i
n runtime



google.api.key


obtained Google Maps API key


Database.properties


This configuration file is entirely dedicated to database connection settings.

Ant related properties:



d
b.driver.dir


relative path to database driver (usually ‘../lib’)



db.driver.jar


jar file with database driver


Shared properties:



db.type


type
of database (unimportant)



db.driver.name


java driver class



db.
url



jdbc database
URL



db.dbname


databas
e name



db.user


user



db.pass


password



db.params


optional parameters


db.url, db.dbname, db.user and db.pass are the most important properties user should focus for
connecting to database (if some error occurs or if changing database settings).


Applic
ation properties:



db.dialect


Hibernate dialect




These define names of files which are used to initially create database:



db.sql.create


create tables script



db.sql.drop


drop tables script



db.sql.populate


populate tables script



db.sql.countries


i
nsert all countries


GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
13



By modifying these variables, you can easily connect GeoLog to any type of d
atabase supported by
Hibernate (see http://www.hibernate.org/80.html). You need to provide your own jar file (put it in
WEB
-
INF/lib directory an
d change approp
riate properties, then reload GeoLog.


Log4j.properties


You might want to modify logging properties of GeoLog. This configuration file is for internal logging
system, it’s in log4j logging format.


Other properties


These files contain strings which can b
e modified in order to more tweak GeoLog error/email
messages:



errors.properties



mails.properties


For additional explanation please see
doc/API/
API_FAQ.doc

in GeoLog SVN
.


Schedule.properties


Properties in this file:



schedule.delete.unconfirmed.users


n
umber of days after which unconfirmed user will be
deleted from system


Upload.properties


Properties in this file:



upload.dir


relative path to upload directory (used for images)



file.types


what images are allowed to upload
to
upload.dir



max.file.size


maximum file size


5.

GeoLog Live


Since GeoLog was partially developed and presented on a virtual machine, there is already running,
publicly available version of GeoLog on following internet address:

http:/
/161.53.67.139:8080/geolog

Note that the server is for development purposes and might be already shut down after the end of the
course.

The following table contains usernames and passwords for some types (roles) of testing users.


Login

Password

Role

Sys
tem administrator

system

System administrator

FirstCA

firstca

Content administrator

MarioPrivileged

marioprivileged

Privileged user


6.

References


Here are some links which can help with required applications:



Java

o

Sun Java
-

http://java.sun.com/



Java application server


here are free ones:

o

Apache Tomcat
-

http://tomcat.apache.org/

GeoLog


Version: 1.0


Installation Manual


Date: 2008
-
01
-
25





Page
14



o

Jetty
-

http://tomcat.apache.org/



Database:

o

HSQLDB
-

http://hsqldb.org/

o

PostgreSQL
-

http://www.postgresql.org/

o

MySQL
-

http://www.mysql.com/