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 HotSpot(tm) 64-Bit Server VM in reply to java -version)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.
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:
| Key | Supported versions | Description |
| :——– | :———————– | :—————- |
files.repository.name | 2.0 and later | Root directory name where files will be stored (ie: repository.name=C:\\Sigmah-files) |
archives.repository.name | 2.0 and later | Root directory name where backup archives are stored. (ie: repository.name=C:\\Sigmah-files\\archives) |
files.upload.maxSize | 2.0 and later | Maximumum size of the uploaded files in bytes (default: 20971520 (20MB) ) |
mail.hostname | 1.0 and later | SMTP hostname used to send emails by the application. (ie: mail.hostname=smtp.myngo.org) |
mail.port | 1.1 and later | SMTP port used to send emails by the application. (ie: mail.port=25) |
mail.from.address | 1.0 and later | SMTP sender email address used to send emails by the application. (ie: mail.from.address=sigmah@myngo.org) |
mail.from.name | 1.0 and later | SMTP sender name as shown to recipient used to send emails by the application (ie:mail.from.name=Sigmah) |
mail.auth.username | 1.1 and later | Username in case of a required authentication when using the given SMTP server (ie:mail.auth.username=sigmah) |
mail.auth.password | 1.1 and later | Password in case of a required authentication when using the given SMTP server (ie:mail.auth.password=sig42mah) |
mail.encoding | 2.0 and later | Character encoding used in the emails generated by Sigmah (ie:mail.encoding=UTF-8) |
mail.contentType | 2.0 and later | Content type used in the emails generated by Sigmah (ie:mail.contentType=text/html) |
mail.support.to | 2.0 and later | E-mail address to which the Report a bug hyperlinks redirects to. (default:mail.support.to=support@sigmah.org) |
mail.optimisation.to.address | 2.2 and later | E-mail address to which the Software performance reports are sent to. (default:mail.optimisation.to.address=support@sigmah.org) |
mail.optimisation.copy.address | 2.2 and later | E-mail address to which the Software performance reports are sent to in CC. (default:mail.optimisation.copy.address=) |
mail.optimisation.markdownfile.name | 2.2 and later | Filename for the Markdown Software performance report file. (default:mail.optimisation.markdownfile.name=sigmah_performance_report.md) |
mail.optimisation.jsonfile.name | 2.2 and later | Filename for the JSON Software performance report file. (default:mail.optimisation.jsonfile.name=sigmah_performance_brut_report.json) |
maps.key | 2.0 and later | Google Maps key |
repository.images | 1.0 - 1.2 | (deprecated: removed since 2.0) |
upload.maxSize | 1.2 | Maximumum size of the uploaded files in bytes (deprecated: replaced by files.upload.maxSize since 2.0) |
host.url | 1.1 - 1.2 | URL on which the Sigmah instance is running.This URL will be used widely on Sigmah. For example, we use the URL: [host.url]/NewUserConfirm?userid1234/ to do the confirmation of new created user .Notice: Do not add any sign at the end. It should be like 'http://www.sigmah.org',not 'http://www.sigmah.org/'. (deprecated: removed since 2.0) |
default.interface | 1.1 - 1.2 | Interface switch between Sigmah & ActivityInfo. This parameter MUST remain with value default.interface=Sigmah. (deprecated: removed since 2.0) |
repository.file_storage_provider_class | 1.1 - 1.2 | Use repository.file_storage_provider_class=org.sigmah.server.endpoint.file.LocalStorageProvider, except if you install Sigmah on the Amazon platform. (deprecated: removed since 2.0) |
repository.name | 1.1 - 1.2 | Root directory name where files will be stored (ie: repository.name=C:\\Sigmah\\Files) (deprecated: replaced by files.repository.name since 2.0) |
repository.files | 1.0 | Folder where the files uploaded by users will be stored. (ie: repository.files=C:\\Sigmah\\Files) (deprecated: replaced by repository.name since 1.1) |
newUserConfirm.host.url | 1.0 | URL used in the confirmation email sent to new users, to confirm their registration. (ie: newUserConfirm.host.url=http://www.myngo.org:8080/sigmah/NewUserConfirm?) (deprecated: replaced by host.url since 1.1) |
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).
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)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
| Parameter | Description |
|---|---|
| p_organization_name | The name of your organization |
| p_organization_logo_filename | The filename of the logo (i.e. logo.png) |
| p_headquarters_country_code | Use an ISO 2-letters code like “AF” from Officially assigned code elements |
| p_user_email | Your mail address |
| p_user_name | Your name |
| p_user_first_name | Your first name |
| p_user_locale | Must be “fr” or “en” or “es” don't include quotes (“) |
Follow this procedure:
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)
You're ready to use it.
To start to use your Sigmah installation:
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 .
webapps folderYour 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