This installation guide describes the technical procedure to follow to install Sigmah.

If you want to install Sigmah just for a trial purpose, you might be interested to know that Sigmah has a live demo available at: http://demo.sigmah.org . You might also be interested to read about the the Sigmah Central service if you want to use Sigmah but are in doubt whether you have the human or financial capacities to maintain such a system.

This installation guide only covers installation of Sigmah both on a Windows and on a Linux (ubuntu) platforms.

For better performance and security, it is recommended to maintain an installation environment for Sigmah with latest versions of the 3 key components it requires. Those components and the known minimum required version are:

• Java 1.8 and above: visit http://www.java.com to download and get installation procedures for the Java runtime environment (if you have a 64bit environment, be sure to download a x64 version which will produce Java HotSpot(tm) 64-Bit Server VM in reply to java -version)
• PostgreSQL 9 and above: download and run the One-click-installer available at http://www.postgresql.org/download/windows to get your copy of the PostgreSQL relational database management system (tip: when installing the database, give all the rights to your database user). For the rest of this procedure, we'll assume that the PostgreSQL database will be installed on same server as application server (database server name will be localhost), and that to connect to the database man should use the default port number 5432. NB : it seems that Postgres doesn't worked properlly when installed on C:/Program Files (it seems better to install it at directly at the root C:/, especially on windows 7)
• Tomcat 7 and above: download and get installation procedures of the Tomcat Java application server at http://tomcat.apache.org/index.html . NB : Sigmah does work also properly with Jetty application server

1. Download the MinimumDataKit SQL file of the latest version of Sigmah at https://github.com/sigmah-dev/sigmah/releases/latest .
2. Create a new database on your PostgreSQL server (watch this video to learn how to ). For the rest of this procedure, we'll assume your database is called sigmah_db. We'll also assume that to access this new database your database username is >db_username, and your database password is db_password.
3. Run the MinimumDataKit SQL file in this new sigmah_db database, in the order given by their filename.

1. Download the webapp archive (*.war) of the latest version of Sigmah at https://github.com/sigmah-dev/sigmah/releases/latest .

2. Create a folder in the webapps directory of your Tomcat installation. This folder will be used as context name for your Sigmah webapp. For the rest of this procedure, we'll assume that you've created a webapp folder named sigmah. All paths, if the contrary is not explicitly specified, will be considered starting from the root of this sigmah folder.

3. Decompress the .war file into your just created sigmah folder.

4. Edit the file WEB-INF/classes/META-INF/persistence.xml and set the database parameters as the following for an installation using PostgreSQL as recommended: (Notice: in v1.2 and earlier versions, the file to edit for database connection parameters was WEB-INF/classes/sigmah.properties)

hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
hibernate.connection.driver_class=org.postgresql.Driver
hibernate.connection.username=db_username
hibernate.connection.password=db_password
hibernate.connection.url=jdbc:postgresql://localhost:5432/sigmah_db
hibernate.hbm2ddl.auto=update
hibernate.show_sql=false
hibernate.format_sql=false

5. Edit the file WEB-INF/classes/sigmah.properties, set the files management and mail parameters. Each folder set must of course exist before running Sigmah. Edit each key of the file as following:

6. (deprecated: step removed since v2.0) Edit the file WEB-INF/classes/sigmah.client.js and replace the GoogleMapsAPI key by a one you've generated with your Google account at https://developers.google.com/maps/documentation/javascript/v2/introduction#Obtaining_Key

7. (deprecated: step removed since v2.0) Optionally, edit the file WEB-INF/classes/log4j.properties to specify your own path for the log file. If you want to do so, replace the value activityinfo.log of the key log4j.appender.file.File by the value you wish.

8. Start or reboot your Tomcat application server to make it deploy your new Sigmah webapp. To start the Tomcat application server, type the following command in the root folder of your Tomcat instance: java -jar start.jar (more information on web application deployment at http://wiki.eclipse.org/Tomcat/Howto/Deploy_Web_Applications)

9. Open your web-browser on the /healthcheck URI to check the health of your new Sigmah server: if your server is running on localhost on port 8080, and if your webapp name is sigmah, then the full URL to test will be http://localhost:8080/sigmah/healthcheck . If healthcheck returns a blank page with only an “OK” message, your server is up and running properly!

Sigmah should be now technically installed on your server, congratulations! The procedure is almost finished: next step will be to create an organization and a first user (see below).

• Edit the logo of your organization to produce a PNG file of 126×56 pixels, and save this file in the files folder of your Sigmah installation (ie: C:\Sigmah\Files). (Notice: in v1.2 and earlier versions, there was a specific images folder to store logo on the filesystem, but since v2.0 all files including organisations' logos are stored in a single folder)
• Run the following SQL command by replacing all parameters with the right value through a call to psql command-line tool

Call of psql command-line tool (called to be made from MS-DOS command line interface opened in the Postgres installation bin folder where the psql.exe executable is located)

psql -U db_username -d sigmah_db -c “select create_new_organization('p_organization_name',
 'p_organization_logo_filename', 'p_headquarters_country_code', 'p_user_email', 
'p_user_name', 'p_user_first_name', 'p_user_locale');”

SQL command description of the parameters

Follow this procedure:

1. Download the sigmah-newOrganizationLaunchScript.postgresql.sql script from https://​github.com/​sigmah-dev/​sigmah/​releases/​latest .
2. Edit the logo of your organization to produce a PNG file of 126×56 pixels, and save this file in the files folder of your Sigmah installation (ie: C:​\Sigmah\Files). (Notice:​ in v1.2 and earlier versions, there was a specific images folder to store logo on the filesystem, but since v2.0 all files including organisations'​ logos are stored in a single folder)
3. Edit the script, and use the search&​replace tool of your text editor to replace ​all the parameters (strings which starts and ends by a '​§'​) by the values you want to give to them.
4. Run the following SQL command by replacing ​all parameters with the right value through ​a call to psql command-line tool.

You're ready to use it.

To start to use your Sigmah installation:

1. Open your browser at http://localhost:8080/sigmah/ (or another URL if you have not used all the default parameters suggested in this procedure)
2. Enter the email used as parameter in the newOrganizationLaunchScript.postgresql.sql script, and “sigmah” as password.
3. You're in!

sudo apt-get install default-jre

Currently, only Tomcat7 is provided through apt-get. But a more recent version does also work.

sudo apt-get install tomcat7

user@hostname:~$ sudo apt-get install postgresql
user@hostname:~$ sudo -i -u postgres
postgres@hostname:~$ psql
postgres=# CREATE USER sigmah;
# CREATE ROLE
postgres=# ALTER ROLE sigmah WITH CREATEDB;
# ALTER ROLE
postgres=# CREATE DATABASE sigmah_db OWNER sigmah;
# CREATE DATABASE
postgres=# ALTER USER sigmah WITH ENCRYPTED PASSWORD 'sigmah';
# ALTER ROLE
postgres=# \q
postgres@hostname:~$ [ctrl+d] to logout
user@hostname:~$

In order to have v2.2 working, you also need to install the pg_trgm extension, and make the sigmah user able to create extension from it in its database (only solution for this: making it “superuser”).

Here is how to:

user@hostname:~$ sudo -i -u postgres
postgres@hostname:~$ psql
postgres=# ALTER ROLE sigmah SUPERUSER;
# ALTER ROLE
postgres=# \q
postgres@hostname:~$ [ctrl+d] to logout
user@hostname:~$ sudo apt-get install postgresql-contrib
user@hostname:~$ sudo /etc/init.d/postgresql restart

You can follow the “Preparing the Sigmah database” part to download the MinimumDataKit SQL file. Open a terminal and run the script.

Note: I got errors due to the escape caracter “\'” not escaped… (i.e. “People\'s”). I edited the file and removed them: “people\'s” → “peoples”.

user@hostname:~$ psql -U sigmah -d sigmah_db -h localhost -f ./sigmah-MinimumDataKit-2.0.postgresql.sql
Password for user sigmah: 

You can follow the “Installing Sigmah” part of the process with following changes:

Steps 2. & 3.: The Tomcat webapps folder is /var/lib/tomcat7/webapps/ on Ubuntu .

1. Copy the .war file into this webapps folder
2. Restart Tomcat (see below for howto) to be sure the war file will be autodeployed

Your webapp is now deployed, and you are ready to proceed with following steps where you should edit the configuration files.

Step 8.: To start or restart Tomcat:

sudo /etc/init.d/tomcat7 restart

PostgreSQL: when restarting PostgreSQL, I had an issue with the log file (missing the folder /var/log/postgresql):

user@hostname:/var/log$ sudo /etc/init.d/postgresql restart
* Restarting PostgreSQL 9.1 database server
* Error: Could not create log file /var/log/postgresql/postgresql-9.1-main.log

user@hostname:/var/log$ sudo mkdir postgresql
user@hostname:/var/log$ sudo chmod 777 postgresql/
user@hostname:/var/log$ sudo /etc/init.d/postgresql restart

See also: http://bugs.launchpad.net/ubuntu/+source/postgresql-common/+bug/1048664