GeoLog

Installation Manual
Version 1.0

GeoLog
Installation Manual

Version:
1.0
Date: 2008-01-25

Revision History
Date
2008-01-23
2008-01-25

Version
0.1
1.0

Description
Initial Draft
Final version

Author
Juraj Misur
Juraj Misur

Doc. No.:

Page 2

GeoLog
Installation Manual

Version:
1.0
Date: 2008-01-25

Table of Contents
1. Introduction............................................................................................................................................4
1.1 Purpose of this document...........................................................................................................4
1.2 Document organization..............................................................................................................4
1.3 Intended Audience......................................................................................................................4
1.4 Scope..........................................................................................................................................4
1.5 Definitions and acronyms...........................................................................................................5
1.5.1 Definitions......................................................................................................................................5
1.5.2 Acronyms and abbreviations..........................................................................................................5
1.6 References..................................................................................................................................5
2. General requirements.............................................................................................................................6
2.1 Operating system........................................................................................................................6
2.2 External programs......................................................................................................................6
2.3 Web browsers.............................................................................................................................6
3. Installation procedure.............................................................................................................................6
3.1 Google Maps API key................................................................................................................6
3.2 Setting up database.....................................................................................................................7
3.2.1 HSQLDB........................................................................................................................................7
3.2.2 PostgreSQL....................................................................................................................................7
3.3 Deploying GeoLog.....................................................................................................................7
3.3.1 Tomcat manager.............................................................................................................................7
3.3.2 Manually........................................................................................................................................7
3.4 GeoLog setup process................................................................................................................7
3.5 After the setup..........................................................................................................................10
4. Configuration files...............................................................................................................................11
5. GeoLog Live........................................................................................................................................12
6. References............................................................................................................................................12

Page 3

GeoLog
Installation Manual

1.

Introduction

1.1

Purpose of this document

Version:
1.0
Date: 2008-01-25

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:

1.3

Section 1, Introduction, contains general description of this document

Section 2, General 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 process 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.
Intended Audience
The intended audience is:

1.4

customers, who will use GeoLog on their own system

developers, who are responsible for deployment or will continue to maintain GeoLog project
supervisors, who may want to test GeoLog
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 setup 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 give 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.

Page 4

GeoLog
Installation Manual

Version:
1.0
Date: 2008-01-25

1.5

Definitions and acronyms

1.5.1

Definitions

Keyword
Java Application Server

1.5.2

Web server for Java web applications

Acronyms and abbreviations

Acronym or
abbreviation
URL

1.6

Definitions

Definitions
Uniform Resource Locator, here simply web address starting on http://...

References
Other GeoLog related documents can be found on GeoLog project site on FER, or GeoLog SVN:

GeoLog Requirements Definition

GeoLog Design Description

GeoLog Technical Documentation

GeoLog Developers Manual

Page 5

GeoLog
Installation Manual

2.

Version:
1.0
Date: 2008-01-25

General requirements
GeoLog was developed in Java programming language as web application using database, therefore its
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 GeoLog

2.3

Java 5 or higher
o Java 5, 6 or higher (Java 5 compatible) must be installed on 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 Apache 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 framework, it supports any other well known database, but
for that it needs to be modified as described in Section 4 Configuration files.
Web browsers
GeoLog was tested and is fully functional in these browsers:

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 (as 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 and know access settings for database.

3.1

Google Maps API key

For Google Maps to work correctly, you need Google 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.
Page 6

GeoLog
Installation Manual

3.2

Setting up database

3.2.1

HSQLDB

Version:
1.0
Date: 2008-01-25

Hsqldb is lightweight java database made for quick and easy development. Nothing have to be
installed, its 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 (therefore its 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 in applications WEB-INF/lib directory.
This will create database server listening on localhost:9001. Username is sa and password is not set.
Database 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, there 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 started. 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 webapps directory. Tomcat should notice that and start GeoLog automatically (either if its
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 consists of 4 setup pages. Here is
step-by-step visual guide:
1. 1st 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 HSQLDB or PostgreSQL
d. URL - your database URL with port
e. Database database name
Page 7

GeoLog
Installation Manual

Version:
1.0
Date: 2008-01-25

f.
g.

User name database user name

Password database user password

Figure 1: Page 1 HSQLDB

Figure 2: Page 1 PostgreSQL

Page 8

GeoLog
Installation Manual

2.

Version:
1.0
Date: 2008-01-25

2nd Setup Page

a. Message 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 connection unsuccessful

3.

3rd Setup Page

a. Database will be filled with initial data. Now you have to provide some additional
settings.
i. Login name system administrators login name (read-only)
ii. Email address system administrators email address
iii. Password system administrators password
b. SMTP settings (are not obligatory and can be changed later)
i. SMTP server URL of SMTP server
ii. Port SMTP servers port for incoming messages
iii. Authentication checked if server requires authentication
iv. Sender address from what email address will GeoLog mails come
v. User name SMTP authentication user name
vi. Password SMTP authentication password

Page 9

GeoLog
Installation Manual

Version:
1.0
Date: 2008-01-25

Figure 5: Page 3 System and SMTP settings

4.

4th Setup Page

GeoLog will confirm successful setup. After that the setup pages will be deleted. If you didnt
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 didnt provide valid SMTP settings during the setup process, dont forget to login as
System administrator and go to System administration panel and configure SMTP settings,
otherwise users wouldnt be able to register (confirmation email wont 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 doesnt work
everywhere (only from trusted domains or so).
Page 10

GeoLog
Installation Manual

4.

Version:
1.0
Date: 2008-01-25

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 wont 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 after installation therefore new registered users
wont be able to submit new locations, because nobody will be assigned to any of predefined
categories. So its recommended to manually register new user, promote to Content
administrator and assign some categories.

Configuration files
GeoLog can be later configured via system administrator interface, but some system information
(database settings, Google API key etc) can be only configured via certain configuration files. All files
reside in WEB-INF/classes directory.
After editing configuration files, 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: Its very important that this property ends with slash /, otherwise it might
break URLs inside GeoLog in runtime
google.api.key obtained Google Maps API key
Database.properties
This configuration file is entirely dedicated to database connection settings.
Ant related properties:
db.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 database 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).
Application 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 insert all countries
Page 11

GeoLog
Installation Manual

Version:
1.0
Date: 2008-01-25

By modifying these variables, you can easily connect GeoLog to any type of database 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 and change appropriate properties, then reload GeoLog.
Log4j.properties
You might want to modify logging properties of GeoLog. This configuration file is for internal logging
system, its in log4j logging format.
Other properties
These files contain strings which can be 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 number 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
System administrator
FirstCA
MarioPrivileged

6.

Password
system
firstca
marioprivileged

Role
System administrator
Content administrator
Privileged user

References
Here are some links which can help with required applications:
Java
o Sun Java - http://java.sun.com/
Page 12

GeoLog
Installation Manual

Version:
1.0
Date: 2008-01-25

Java application server here are free ones:

o Apache Tomcat - http://tomcat.apache.org/
o Jetty - http://tomcat.apache.org/
Database:
o HSQLDB - http://hsqldb.org/
o PostgreSQL - http://www.postgresql.org/
o MySQL - http://www.mysql.com/

Page 13