# Gisgraphy installation guide

Before you install and launch Gisgraphy, you must set up Java (you need a version of the JVM >= 1.5), PostgreS, and PostGIS. It is not, properly speaking, part of the installation of Gisgraphy, and if you don't already have PostgreS, PostGIS and Java installed, you must install them first. A tutorial is provided here for Linux and here for Windows.

## Download a Gisgraphy distribution

- First you have to download a distribution here. Download a tar.gz file if you are on Linux or download a zip file if you are on Windows.
- Then extract it : tar xvf YOURFILE if you're on Linux or double click on the file if you are running Windows.

## Initialize the database

Here are the commands to run to and initialize the Gisgraphy tables:

    #create tables;
    psql -UYOURUSER -d gisgraphy -h YOURIP -f /path/to/file/create_tables.sql

Where YOURUSER is a postgresql user with admin rights, YOURIP is the IP address of your server (127.0.0.1 in most case)
Then insert users (...for the admin interface,... you don't have to log to use Gisgraphy webservices) in the database. A script called insert-users.sql is provided with two default users: one with admin rights and one with simple rights.
psql -UYOURPOSTGRESQLUSER -d gisgraphy -h YOURIP -f /path/to/file/insert_users.sql
It is HIGHLY recommended that you modify them for security once Gisgraphy is installed.

- Log in as 'admin' with password 'admin'
- Go to the http://localhost:8080/admin/users.html page
- Change the admin and user password
- Change the password of user 'user'

## Edit the database and Gisgraphy settings

Go into the directory where you've extracted the Gisgraphy distribution, then edit the database settings in the jdbc.properties file in the directory 'webapps/ROOT/WEB-INF/classes' of the Gisgraphy distribution to set the PostgreS password you've defined in the 'Environment setup' step.
You can edit the configuration information (import, and so on) in the env.properties file in directory 'webapps/ROOT/WEB-INF/classes' of the Gisgraphy distribution (for more information see the options documentation).
Good to know - if you want to use Google Maps features (see street, etc), you must set the googleMapAPIKey in the env.properties
That's all - you can now start Gisgraphy

## Start Gisgraphy

- Open a command line (Start/run and type 'cmd')
- Change the current directory to the folder where you've unzipped the files
- Change the rights of the launch.sh script if you are on Linux : chmod +x launch.sh
- Launch the launch script (.sh on Linux, .command on mac and .bat on windows "

Some useful scripts are provided, most of them are for Unix / Linux :

- launch : run gisgraphy and output logs to the console.
- start : starts Gisgraphy.
- stop : Shutdown gisgraphy (clean way).
- force-stop : kill gisgraphy (doesn't check the status).
- status : tell whether gisgraphy is started or not.
- logs : output logs file to the console.
- respawn : check gisgraphy status and re-launch it if it has gone.
- watch : run the respawner.
- unwatch : stop the respawner.
- startupscript : script to run gisgraphy as a daemon.
- setGisgrapgyAsService : intall the startup script (unix only).

Important : You must type the command line in the directory where you've extract the Gisgraphy files.
The directory where you type the command to start your servlet container (e.g : `java -jar start.jar` for Jetty or `startup.sh/startup.bat` for Tomcat) determines the directory where the full text data will be stored. The data will be stored in the `$Current_Working_directory/solr` directory. In other words :

- If you are in directory 'foo' and you type : "`java -jar ./directory/where/Gisgraphy/is/Extracted/start.jar`", the data will be stored in `foo/solr`, because you are in the 'foo' directory
- If you are in directory 'foo' and you type : "`cd directory/where/gisgraphy/is/extracted/start.jar`" and then "`java -jar start.jar`", the Data will be stored in the 'extracted' directory, because you are in the 'extracted' directory.

This is the same thing for Tomcat or any servlet Container (Resin, ...) due to SolR. More...
To avoid OutOfMemoryError : If you launch Gisgraphy in Tomcat, you must launch it with a minimum memory of 512M. To do this, set your CATALINA_OPTS to `-Xms512M -Xmx512M` (e.g : add this CATALINA_OPTS=-Xms512M -Xmx512M to the .bashrc file in your home directory).

## See if it works

Open a browser and go to http://localhost:8080/mainMenu.html. You should see the admin page; then go to http://localhost:8080/ you should see a Gisgraphy page!

## And now...

You can :

- Import data
- Improve security
- Improve performance
- See the FAQ
- Use the forum