Server setup

Server setup This section describes how to set up a server instance of DHIS 2 on Ubuntu 12.04 64 bit - with PostgreSQL as database system and Tomcat as Servlet container. The term invoke refers to executing a given command in a terminal. + with PostgreSQL as database system and Tomcat as Servlet container. This guide is not meant to be a step-by-step guide per se, but rather to serve as a reference to how DHIS2 can be deployed on a server. There are many possible deployment strategies, which will differ depending on the operating system and database you are using, and other factors. The term invoke refers to executing a given command in a terminal. For a national server the recommended configuration is a quad-core 2 Ghz processor or higher and 12 Gb RAM or higher. Note that a 64 bit operating system is required for utilizing more than 4 Gb of RAM, the Ubuntu 12.04 64 bit edition is thus recommended. For this guide we assume that 8 Gb RAM is allocated for PostgreSQL and 8 GB RAM is - allocated for Tomcat/JVM, and that a 64-bit operating system is used. If you are running a different configuration please adjust the suggested values - accordingly! We recommend that the available memory is split roughly equally + allocated for Tomcat/JVM, and that a 64-bit operating system is used. If you are running a different configuration please adjust the suggested values accordingly! We recommend that the available memory is split roughly equally between the database and the JVM. Remember to leave some of the physical memory to the operating system for it to perform its tasks, for instance around 2 GB. The steps marked as optional, like the step for performance tuning, can be done at a later stage. - Create new user (optional) - You might want to create a dedicated user for running DHIS - it is not recommended to run - as the root user. Create a new user called dhis by invoking

useradd -d /home/dhis -m
-        dhis -s /bin/bash

Then make the user able to perform operations temporarily as root +

+ Creating a user to run DHIS2 + You should create a dedicated user for running DHIS - it is not recommended to run + as the root user. Create a new user called dhis by invoking useradd -d /home/dhis -m dhis -s /bin/bash Then make the user able to perform operations temporarily as root user by invoking usermod -G sudo dhis. Then invoke passwd dhis to set the password for your account. Make sure you set a strong password with at least 15 random characters. You might want to disable remote login for the root account for improved security by invoking sudo passwd -l root - Operating system kernel tuning - These settings are optional except for the shared memory setting which is required for PostgreSQL memory allocation. Open the kernel configuration file by invoking sudo nano /etc/sysctl.conf At the end of the file add the following lines and save. - kernel.shmmax = 4294967296 +

+ Operating system kernel tuning + These settings are optional except for the shared memory setting which is required for PostgreSQL memory allocation. Open the kernel configuration file by invoking sudo nano /etc/sysctl.conf At the end of the file add the following lines and save. + kernel.shmmax = 4294967296 net.core.rmem_max = 8388608 net.core.wmem_max = 8388608 - Make the changes take effect by invoking sudo sysctl -p - Install Java - Install Java by invoking the following: - sudo apt-get install openjdk-7-jdk - Check that your installation is okay by invoking java -version - Install PostgreSQL - To install PostgreSQL version 9.2 we first need to add a Ubuntu package repository to our system. - sudo apt-get install python-software-properties +

+ Setting the server time + Remember to set the server date correctly according to the time zone of which the main part of the users of the system are located. This will affect e.g. when scheduled tasks are executed. For instance, to the set time to 22:45, October 17, 2012, invoke sudo date 101722452012. + It may be necessary to reconfigure the time zone of the server to match the time zone of the location which the DHIS2 server will be covering. If you are using a virtual private server, the default time zone may not correspond to the time zone of your DHIS2 location. You can easily reconfigure the time zone by invoking sudo dpkg-reconfigure tzdata and following the instructions. + It is easy to keep your server very accurate by using the NTP package. You can install it by simply invoking sudo apt-get install ntp. NTP will automatically syncronize your server time on a regular basis. +

+ Postgresql installation and tuning + To install PostgreSQL version 9.2 we first need to add a Ubuntu package repository to our system. + sudo apt-get install python-software-properties sudo add-apt-repository ppa:pitti/postgresql -sudo apt-get update - Now install PostgreSQL by invoking sudo apt-get install postgresql-9.2 - Switch to the postgres user by invoking sudo su postgres - Create a non-privileged user called dhis by invoking +sudo apt-get update + Now install PostgreSQL by invoking sudo apt-get install postgresql-9.2 + Switch to the postgres user by invoking sudo su postgres + Create a non-privileged user called dhis by invoking createuser -SDRP dhis. Enter a secure password at the prompt. Create a database by invoking createdb -O dhis dhis2. Return to your session by invoking exit You now have a PostgreSQL user called dhis and a database called dhis2. - Do performance tuning by opening the following file by invoking - sudo nano /etc/postgresql/9.2/main/postgresql.conf - and set the following properties: - shared_buffers = 3200MB - Determines how much memory should be allocated exclusively for PostgreSQL caching. This + Do performance tuning by opening the following file by invoking + sudo nano /etc/postgresql/9.2/main/postgresql.conf + and set the following properties: + shared_buffers = 3200MB + Determines how much memory should be allocated exclusively for PostgreSQL caching. This setting controls the size of the kernel shared memory which should be reserved for PostgreSQL. Should be set to around 40% of total memory dedicated for PostgreSQL. - work_mem = 20MB - Determines the amount of memory used for internal sort and hash operations. This setting + work_mem = 20MB + Determines the amount of memory used for internal sort and hash operations. This setting is per connection, per query so a lot of memory may be consumed if raising this too high. Setting this value correctly is essential for DHIS 2 aggregation performance. - maintenance_work_mem = 256MB - Determines the amount of memory PostgreSQL can use for maintenance operations such as + maintenance_work_mem = 256MB + Determines the amount of memory PostgreSQL can use for maintenance operations such as creating indexes, running vacuum, adding foreign keys. Incresing this value might improve performance of index creation during the analytics and data mart generation processes. - effective_cache_size = 8000MB - An estimate of how much memory is available for disk caching by the operating system (not + effective_cache_size = 8000MB + An estimate of how much memory is available for disk caching by the operating system (not an allocation) and is used by PostgreSQL to determine whether a query plan will fit into memory or not. Setting it to a higher value than what is really available will result in poor performance. This value should be inclusive of the shared_buffers setting. PostgreSQL has two @@ -105,58 +108,62 @@ shared_buffers setting. PostgreSQL delegates the second layer to the operating system disk cache and the size of available memory can be given with the effective_cache_size setting. - checkpoint_segments = 32 - PostgreSQL writes new transactions to a log file called WAL segments which are 16MB in size. When a number of segments have been written a checkpoint occurs. Setting this number to a larger value will thus improve performance for write-heavy systems such as DHIS 2. - checkpoint_completion_target = 0.8 - Determines the percentage of segment completion before a checkpoint occurs. Setting this to a high value will thus spread the writes out and lower the average write overhead. - wal_buffers = 16MB - Sets the memory used for buffering during the WAL write process. Increasing this value might improve throughput in write-heavy systems. - synchronous_commit = off - Specifies whether transaction commits will wait for WAL records to be written to the disk before returning to the client or not. Setting this to off will improve performance considerably. It also implies that there is a slight delay between the transaction is reported successful to the client and it actually being safe, but the database state cannot be corrupted and this is a good alternative for performance-intensive and write-heavy systems like DHIS 2. - wal_writer_delay = 10000ms - Specifies the delay between WAL write operations. Setting this to a high value will improve performance on write-heavy systems since potentially many write operations can be executed within a single flush to disk. - Restart PostgreSQL by invoking sudo /etc/init.d/postgresql restart - Set the database configuration - The database connection information is provided to DHIS 2 through a configuration file called hibernate.properties. Create this file and save it in a convenient location. A file corresponding to the above setup has these properties: - hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect + checkpoint_segments = 32 + PostgreSQL writes new transactions to a log file called WAL segments which are 16MB in size. When a number of segments have been written a checkpoint occurs. Setting this number to a larger value will thus improve performance for write-heavy systems such as DHIS 2. + checkpoint_completion_target = 0.8 + Determines the percentage of segment completion before a checkpoint occurs. Setting this to a high value will thus spread the writes out and lower the average write overhead. + wal_buffers = 16MB + Sets the memory used for buffering during the WAL write process. Increasing this value might improve throughput in write-heavy systems. + synchronous_commit = off + Specifies whether transaction commits will wait for WAL records to be written to the disk before returning to the client or not. Setting this to off will improve performance considerably. It also implies that there is a slight delay between the transaction is reported successful to the client and it actually being safe, but the database state cannot be corrupted and this is a good alternative for performance-intensive and write-heavy systems like DHIS 2. + wal_writer_delay = 10000ms + Specifies the delay between WAL write operations. Setting this to a high value will improve performance on write-heavy systems since potentially many write operations can be executed within a single flush to disk. + Restart PostgreSQL by invoking sudo /etc/init.d/postgresql restart + Set the database configuration + The database connection information is provided to DHIS 2 through a configuration file called hibernate.properties. Create this file and save it in a convenient location. A file corresponding to the above setup has these properties: + hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect hibernate.connection.driver_class = org.postgresql.Driver hibernate.connection.url = jdbc:postgresql:dhis2 hibernate.connection.username = dhis hibernate.connection.password = xxxx hibernate.hbm2ddl.auto = update - A common mistake is to have a white-space after the last property value - make sure there + A common mistake is to have a white-space after the last property value - make sure there is no white-space at the end of any line. Also remember that this file contains the clear text password for your dhis2 database so needs to be protected from unauthorized access. To do this invoke chmod 0600 hibernate.properties which ensures that only the dhis user which owns the file is allowed to read or write to it. - Install Tomcat - Download the Tomcat binary distribution from http://tomcat.apache.org/download-70.cgi A useful tool for downloading files +

+ Install Java + Install Java by invoking the following command: sudo apt-get install openjdk-7-jdk + Check that your installation is okay by invoking java -version. +

+ Install Tomcat and DHIS2 + Download the Tomcat binary distribution from http://tomcat.apache.org/download-70.cgi A useful tool for downloading files from the web is wget. Extract to a convenient location. This guide assumes that you have navigated to the root directory of the extracted archive. - Download the latest stable DHIS WAR file by invoking: - - wget stable.dhis2.org - - Clear the pre-installed web applications by invoking rm -rf webapps/* Move + Download the latest stable DHIS WAR file by invoking: wget stable.dhis2.org + Clear the pre-installed web applications by invoking rm -rf webapps/* Move the DHIS WAR file to the webapps directory and rename it to ROOT.war. - Create a file bin/setenv.sh and add the lines below. - The first will set the location of your Java Runtime Environment, the second will dedicate + Create a file bin/setenv.sh and add the lines below. + The first line will set the location of your Java Runtime Environment, the second will dedicate memory to Tomcat and the third will set the location for where DHIS 2 will search for the hibernate.properties configuration file. Please check that the path the Java binaries are correct as they might vary from system to system, e.g. on AMD systems you might see /java-7-openjdk-amd64 Note that you should adjust this to your environment: - export JAVA_HOME='/usr/lib/jvm/java-7-openjdk' + export JAVA_HOME='/usr/lib/jvm/java-7-openjdk' export JAVA_OPTS='-Xmx7500m -Xms4000m -XX:MaxPermSize=500m -XX:PermSize=300m' export DHIS2_HOME='/home/dhis/config' - If you need to change the port of which Tomcat listens for requests you can open the Tomcat configuration file /conf/server.xml, locate the <Connector> element which is not commented out and change the port attribute value to the desired port number. - To monitor the behavior of Tomcat the log is the primary source of information. The log can be easily viewed with the command tail -f logs/catalina.out - Set server time - Remember to set the server date correctly according to the time zone of which the main part of the users of the system are located. This will affect e.g. when scheduled tasks are executed. For instance, to the set time to 22:45, October 17, 2012, invoke sudo date 101722452012 - Run DHIS 2 - Make the startup script executable by invoking chmod 755 bin/* DHIS 2 can now be started by invoking bin/startup.sh The log can be monitored by invoking tail -f logs/catalina.out DHIS 2 can be stopped by invoking bin/shutdown.sh Assuming that the WAR file is called ROOT.war, you can now access your DHIS instance at http://localhost:8080 + If you need to change the port of which Tomcat listens for requests you can open the Tomcat configuration file /conf/server.xml, locate the <Connector> element which is not commented out and change the port attribute value to the desired port number. + To monitor the behavior of Tomcat the log is the primary source of information. The log can be easily viewed with the command tail -f logs/catalina.out +

+ Running DHIS2 + Make the startup script executable by invoking chmod 755 bin/* DHIS 2 can now be started by invoking bin/startup.sh The log can be monitored by invoking tail -f logs/catalina.out DHIS 2 can be stopped by invoking bin/shutdown.sh Assuming that the WAR file is called ROOT.war, you can now access your DHIS instance at http://localhost:8080 +

Reverse proxy configuration @@ -174,7 +181,7 @@

Basic setup for nginx - We recommend using nginx (http://wiki.nginx.org) as reverse proxy due to its low memory + We recommend using nginx as reverse proxy due to its low memory footprint and ease of use. To install invoke the following: sudo apt-get install nginx nginx can now be started, reloaded and stopped with the following commands: @@ -183,7 +190,7 @@ sudo /etc/init.d/nginx stop Now that we have installed nginx we will now continue to configure regular proxying of requests to our Tomcat instance, which we assume runs at http://localhost:8080. To configure nginx you can open the configuration file by invoking sudo nano /etc/nginx/nginx.conf - nginx configuration is built around a hierarchy of blocks representing http, server and location, where each block inherit settings from parent blocks. The following snippet will configure nginx to proxy pass (redirect) requests from port 80 (which is the port nginx will listen on by default) to our Tomcat instance. It will also make nginx serve requests for static content such as javascript, stylesheets and images and instruct clients to cache it for 4 days which will reduce the load on Tomcat and improve overall performance. Include the following configuration in nginx.conf: + nginx configuration is built around a hierarchy of blocks representing http, server and location, where each block inherit settings from parent blocks. The following snippet will configure nginx to proxy pass (redirect) requests from port 80 (which is the port nginx will listen on by default) to our Tomcat instance. It will also make nginx serve requests for static content such as Javascript, stylesheets and images and instruct clients to cache it for 4 days which will reduce the load on Tomcat and improve overall performance. Include the following configuration in nginx.conf: - You can now access your DHIS instance at http://localhost. Since the reverse proxy has been set up we can improve - security by making Tomcat only listen for local connections. In /conf/server.xml you can add an address + You can now access your DHIS instance at http://localhost. Since the reverse proxy has been set up we can improve + security by making Tomcat only listen for local connections. In /conf/server.xml you can add an address attribute with the value localhost to the Connector element for HTTP 1.1 like this: <Connector address="localhost" protocol="HTTP/1.1" ... > @@ -223,8 +228,7 @@ In order to improve security it is recommended to configure the server running DHIS to communicate with clients over an encrypted connection and to identify itself to clients using a trusted certificate. This can be achieved through SSL which is an cryptographic - communication protocol running on top of TCP/IP. First, install the required openssl library: + communication protocol running on top of TCP/IP. First, install the required openssl library: sudo apt-get install openssl To configure nginx to use SSL you will need a proper SSL certificate from an SSL provider. The cost of a certificate varies a lot depending on encryption strength. An affordable certificate from Rapid SSL Online should serve most purposes. To generate the CSR (certificate signing request) you can invoke the command below. When you are prompted for the Common Name, enter the fully qualified domain name for the site you are securing. openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr @@ -275,7 +279,7 @@ proxy_set_header X-Forwarded-Proto https; } }]]> - In order for tomcat to properly produce Location uris using https you also need to add two other parameters to the Connector in tomcat's server.xml file: + In order for tomcat to properly produce Location uris using https you also need to add two other parameters to the Connector in tomcat's server.xml file: <Connector scheme="https" proxyPort="443" ... >

@@ -374,11 +378,11 @@

Making resources available with nginx In some scenarios it is desirable to make certain resources publicly available on the Web without requiring authentication. One example is when you want to make data analysis related resources in the Web API available in a Web portal. The following example will allow access to charts, maps, reports, report table and document resources through basic authentication by injecting an Authorization HTTP header into the request. It will remove the Cookie header from the request and the Set-Cookie header from the response in order to avoid changing the currently logged in user. It is recommended to create a user for this purpose given only the minimum authorities required. The Authorization value can be constructed by Base64-encoding the username appended with a colon and the password and prefix it "Basic ", more precisely "Basic base64_encode(username:password)". It will check the HTTP method used for requests and return 405 Method Not Allowed if anything but GET is detected. - It can be favorable to set up a separate domain for such public users when using this approach. This is because we don't want to change the credentials for already logged in users when they access the public resources. For instance, when your server is deployed at somedomain.com, you can set a dedicated subdomain at api.somedomain.com, and point URLs from your portal to this subdomain. + It can be favorable to set up a separate domain for such public users when using this approach. This is because we don't want to change the credentials for already logged in users when they access the public resources. For instance, when your server is deployed at somedomain.com, you can set a dedicated subdomain at api.somedomain.com, and point URLs from your portal to this subdomain. server { listen 80; server_name api.somedomain.com; - + location ~ ^/(api/(charts|chartValues|reports|reportTables|documents|maps|organisationUnits)|dhis-web-commons/javascripts|images|dhis-web-commons-ajax-json|dhis-web-mapping|dhis-web-visualizer) { if ($request_method != GET) { return 405; @@ -502,7 +506,7 @@ The cron job is set up with two files. The first is a script which performs the actual task of backup up the database. It uses a PostgreSQL program called pg_dump for creating the database copy. The second is a crontab file which runs the backup script every day at 23:00. Note that this script backs up the database file to the local disk. It is strongly recommended to store a copy of the backup at a location outside the server where the application is hosted. This can be achieved with the scp tool. Make sure that you have set the system date correctly on your server.

- Working with the PostgreSQL database + Working with the PostgreSQL database Common operations when managing a DHIS instance are dumping and restoring databases. To make a dump (copy) of your database, assuming the setup from the installation section, you can invoke the following: @@ -510,7 +514,7 @@ The first argument (dhis2) refers to the name of the database. The second argument (dhis) refers to the database user. The last argument (dhis2.sql) is the file name of the copy. If you want to compress the file copy immediately you can do: - pg_dump dhis2 -U dhis | gzip > dhis2.sql.gz + pg_dump dhis2 -U dhis | gzip > dhis2.sql.gz To restore this copy on another system, you first need to create an empty database as described in the installation section. You also need to gunzip the copy if you created a compressed version. You can the invoke: