Getting started with DHIS 2

- Getting started with DHIS2 - After reading this chapter you will be able to understand: - - - Start DHIS 2 from the desktop - - - How to log-in from the desktop - - - Create new users and user roles - - -

- Prerequisites - You must be sure that you have a current version of the Java Runtime installed on your machine. Depending on your operating system, there are different ways of installing Java. The reader is referred to this website for detailed information on getting java installed. - -

- Starting the DHIS2 Live package - The DHIS2 Live package is the easiest way to get started with DHIS2. DHIS2 Live is appropriate for a stand-alone type of installation. Simply download the application from here. - Once the file is downloaded, you can simply double-click the downloaded file, and get started using DHIS2. -

Working directly with the H2 database - - DHIS2 Live uses an embedded H2 database. This has several advantages - there is no need - to install a separate database engine such as PostgresSql or MySql, and backup can be made by just copying the file. The whole db - exists in memory, which means high performance. The disadvantage is need for RAM. It is also not suitable for mulitiuser server - installations. - - - In general, it is recommended to work with the database through the DHIS2 user interface, but in some situations one may need to - manipulate the data directly. If one downloads H2 separately, it comes with a web interface. It can also be manipulated using - OpenOffice.org, using the following procedure. This assumes that dhis2-live is located in - the user's Linux home directory (represented by ~). Substitute the absolute path to your dhis2-live installation. - - - Start OpenOffice Word Processor and select Tools - Options, then Java - Class Path ... and click on Add Archive... - - - Select the following file (version may differ): ~/dhis2-live/webapps/dhis/WEB-INF/lib/h2-1.1.119.jar - - - Close OpenOffice completely and then open OpenOffice.org Database. Select connect to an existing database - JDBC - - - Datasource URL is h2:~/dhis2-live/database/dhis2;AUTO_SERVER=TRUE, and JDBC driver class is org.h2.Driver - - - User name is sa, password not needed. Finally, select a name and folder for the .odb file. - - - More tips - - -

- Downloading and installing the server version - DHIS2 functions both as a - desktop application, as well as a web-enabled client-server application. - For larger, production installations with many users and large volumes - of data (for instance as a national level server) it is recommended to - install the server version. The latest version of the infrastructure can be - found here. - - There are many permutations of getting a server installation up and running, and will depend very much on the nature of the installation. A typical installation for a single machine, running Ubuntu Linux will be described in the discussion that follows. This type of single-installation would be appropriate for a small work-group. There are so many different ways to get the application running, and this will depend to a large extent on the number of users you will be catering to, the type of hardware you have available, and the nature of the implementation of the application (e.g one central server as opposed to multiple subnational installations). The example provided here is meant to be a rough guide for those that are setting up a DHIS2 server instance from scratch, however, you should consider all security requirements of your implementation before blindly following this example. - You will need to decide which back-end database system you will use. DHIS2 is a database agnostic application in principle, and should run on any system with a compatible JDBC driver. However, it is recommended either to use Postgresql or MySQL, as these systems are widely used by other members of the DHIS2 community. In addition to a back-end database system, you will need a compatible servlet container. Apache Tomcat 6 is recommended by the developers, however in principle, the application should run in any container that conforms to the Servlet 2.5 specification. - It is certainly possible to install all packages from source code, but it is suggested that you install most of the basic packages through your systems package manager. Depending on which version of Linux that you may be using, you may need to install a newer version of both the back-end database system (such as Postgresql and MySQL) and Servlet container. It is recommended to use at least Postgresl version 8.3 or MySQL 5.0. - To get started downloading the necessary packages, execute the following commands. Note that you may need to add the sudo command before these commands, if you are not running as root. - apt-get install nano wget nano /etc/apt/sources.list - Uncomment and add “multiverse” after “universe” in each line of this file. - After editing the sources.list execute these commands. - apt-get update -apt-get install sun-java6-jdk postgresql postgresql-client -postgresql-contrib postgresql-8.3-postgis - This will install a number of packages on your system, including Java and the Postgresql database system. In principle, DHIS2 will run under any servlet container, but it is recommended to use Apache Tomcat. Check with the DHIS2 developers if you have questions about using other servlet containers. To get Tomcat, execute the following commands - wget http://apache.mirror.testserver.li/tomcat/tomcat-6/v6.0.20/bin/apache-tomcat-6.0.20.tar.gz tar xvzf apache-tomcat-6.0.20.tar.gz mv apache-tomcat-6.0.20 /usr/local/tomcat - If you need plan on installing Geoserver as part of your DHIS2 installation, go ahead and download and install it. You should check on the Geoserver web page for the latest version. - - -wget http://downloads.sourceforge.net/geoserver/geoserver-2.0.0a-war.zip - unzip geoserver-2.0.0a-war.zip - -unzip geoserver.war -d /usr/local/tomcat/webapps - -mv /usr/local/tomcat/webapps/geoserver/data /usr/local/geodata - You should now change the default Geoserver password to something more secure. Execute nano /usr/local/geodata/security/users.properties and change the password and then save all changes. - Edit one of your persistent environment variables (see this page for details). Add the following lines to the chosen file. - export JAVA_HOME=/usr/lib/jvm/java-6-sun - export JDK_HOME= /usr/lib/jvm/java-6-sun - - export JAVA_OPTS=-XX:PermSize=256m -XX:MaxPermSize=1536 -Xms512m -Xmx1024m -server - - export GEOSERVER_DATA_DIR=/usr/local/geodata - - export DHIS2_HOME=/root/dhis/dhis2 - - Note that you may need to alter the file paths to point to the actual directories on your system. - Assuming that you have installed the postgresql database system, you can create a new database with the following commands. - sudo su - postgres - createdb createdb -E utf-8 dhis - Note that you can change the name of the database to anything that suits your environment. - To tell the DHIS2 application where to find its database you need a hibernate.properties file in DHIS2_HOME . For a postgres database connection to a database called 'dhis', with user name and password 'dhis', you need to put the following inside your file /root/dhis/dhis2/hibernate.properties: - hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect - hibernate.connection.driver_class = org.postgresql.Driver - - hibernate.connection.url = jdbc:postgresql:dhis - hibernate.connection.username = dhis - hibernate.connection.password = dhis - - hibernate.hbm2ddl.auto = update - Save this file in the DHIS2_HOME directory. Exit the current shell in order to reload the environment variables and open a new shell. You will need to start both postgresql as well as the tomcat server. If you installed postgresql with the apt-get command, you can start this from the /etc/init.d/ directory with the commands. - sudo su - - cd /etc/init.d/ - ./S18postgresql start - Note that you may need to alter this command to your particular system. - It is good security practise to run the tomcat application as a separate user. If you do not already have a separate user account, you can create one with the following commands. - sudo useradd -d /home/tomcat6 -m tomcat6 - sudo passwd tomcat6 - You should not change the file permissions for the entire directory that you installed Tomcat to, with the following command. - sudo chown -R tomcat6:tomcat6 /usr/local/tomcat - To start the application, login as the user, navigate to the /usr/local/tomcat/bin/ directory, and execute the start.sh script. - sudo su - tomcat6 - cd /usr/local/tomcat/bin - ./startup.sh -

- Installing DHIS2 with the Debian install package - If you are using Ubuntu or Debian, a separate Debian installation package has been created to simplify the installation process. You can simply download this file and then install DHIS2 from the command line with the following command. - sudo dpkg -i dhis2-2.0.3.deb - You can also install this Debian package from your systems package manager. -

+ Getting started with DHIS2 + After reading this chapter you will be able to understand: + + + Start DHIS 2 from the desktop + + + How to log-in from the desktop + + + Create new users and user roles + + +

+ Prerequisites + You must be sure that you have a current version of the Java Runtime installed on your machine. Depending on your operating system, there are different ways of installing Java. The reader is referred to this website for detailed information on getting java installed. + +

+ Starting the DHIS2 Live package + The DHIS2 Live package is the easiest way to get started with DHIS2. DHIS2 Live is appropriate for a stand-alone type of installation. Simply download the application from here. + Once the file is downloaded, you can simply double-click the downloaded file, and get started using DHIS2. +

+ Starting up with a blank database + The live package comes with a demo database just like what you see on the online demo (which is based on the national Sierra Leone HMIS), and if you want to start with a blank system/database and build up your own system then you need to do the following: + + + 1) Stop the DHIS2 live if it is already running. Right click on the tray icon and select Exit. +The tray icon is the green symbol on the bottom right of your screen (on Windows) which should say' DHIS2 Server running' if you hold your mouse pointer over it. + 2) Open the folder where the DHIS2 live package is installed and locate the folder called "conf". + + 3) In conf/ open the file called 'hibernate.properties' in a text editor (notepad or similar) and do the following modification: +locate the string 'jdbc:h2:./database/dhis2' and replace the 'dhis2' part with any name that you want to give to your database (e.g. dhis2_test). + 4) Save and close the hibernate.properties file. + + 5) Start DHIS2 live by double-clicking on the file dhis2-live.exe in the DHIS2 live installation folder or by using a desktop shortcut or menu link that you might have set up. + + 6) Wait for the browser window to open and the login screen to show, and then log in with username: admin and password: district + + 7) Now you will see a completely empty DHIS2 system and you should start by adding your users, organisational hierarchy, data elements, and datasets etc. Please refer to the other sections of the user manual for instructions on how to do this. + +

+ Working directly with the H2 database + + DHIS2 Live uses an embedded H2 database. This has several advantages - there is no need + to install a separate database engine such as PostgresSql or MySql, and backup can be made by just copying the file. The whole db + exists in memory, which means high performance. The disadvantage is need for RAM. It is also not suitable for mulitiuser server + installations. + + + In general, it is recommended to work with the database through the DHIS2 user interface, but in some situations one may need to + manipulate the data directly. If one downloads H2 separately, it comes with a web interface. It can also be manipulated using + OpenOffice.org, using the following procedure. This assumes that dhis2-live is located in + the user's Linux home directory (represented by ~). Substitute the absolute path to your dhis2-live installation. + + + Start OpenOffice Word Processor and select Tools - Options, then Java - Class Path ... and click on Add Archive... + + + Select the following file (version may differ): ~/dhis2-live/webapps/dhis/WEB-INF/lib/h2-1.1.119.jar + + + Close OpenOffice completely and then open OpenOffice.org Database. Select connect to an existing database - JDBC + + + Datasource URL is h2:~/dhis2-live/database/dhis2;AUTO_SERVER=TRUE, and JDBC driver class is org.h2.Driver + + + User name is sa, password not needed. Finally, select a name and folder for the .odb file. + + + More tips + + +

+ Downloading and installing the server version + DHIS2 functions both as a + desktop application, as well as a web-enabled client-server application. + For larger, production installations with many users and large volumes + of data (for instance as a national level server) it is recommended to + install the server version. The latest version of the infrastructure can be + found here. + + There are many permutations of getting a server installation up and running, and will depend very much on the nature of the installation. A typical installation for a single machine, running Ubuntu Linux will be described in the discussion that follows. This type of single-installation would be appropriate for a small work-group. There are so many different ways to get the application running, and this will depend to a large extent on the number of users you will be catering to, the type of hardware you have available, and the nature of the implementation of the application (e.g one central server as opposed to multiple subnational installations). The example provided here is meant to be a rough guide for those that are setting up a DHIS2 server instance from scratch, however, you should consider all security requirements of your implementation before blindly following this example. + You will need to decide which back-end database system you will use. DHIS2 is a database agnostic application in principle, and should run on any system with a compatible JDBC driver. However, it is recommended either to use Postgresql or MySQL, as these systems are widely used by other members of the DHIS2 community. In addition to a back-end database system, you will need a compatible servlet container. Apache Tomcat 6 is recommended by the developers, however in principle, the application should run in any container that conforms to the Servlet 2.5 specification. + It is certainly possible to install all packages from source code, but it is suggested that you install most of the basic packages through your systems package manager. Depending on which version of Linux that you may be using, you may need to install a newer version of both the back-end database system (such as Postgresql and MySQL) and Servlet container. It is recommended to use at least Postgresl version 8.3 or MySQL 5.0. + To get started downloading the necessary packages, execute the following commands. Note that you may need to add the sudo command before these commands, if you are not running as root. + apt-get install nano wget nano /etc/apt/sources.list + Uncomment and add “multiverse” after “universe” in each line of this file. + After editing the sources.list execute these commands. + apt-get update +apt-get install sun-java6-jdk postgresql postgresql-client +postgresql-contrib postgresql-8.3-postgis + This will install a number of packages on your system, including Java and the Postgresql database system. In principle, DHIS2 will run under any servlet container, but it is recommended to use Apache Tomcat. Check with the DHIS2 developers if you have questions about using other servlet containers. To get Tomcat, execute the following commands + wget http://apache.mirror.testserver.li/tomcat/tomcat-6/v6.0.20/bin/apache-tomcat-6.0.20.tar.gz tar xvzf apache-tomcat-6.0.20.tar.gz mv apache-tomcat-6.0.20 /usr/local/tomcat + If you need plan on installing Geoserver as part of your DHIS2 installation, go ahead and download and install it. You should check on the Geoserver web page for the latest version. + + +wget http://downloads.sourceforge.net/geoserver/geoserver-2.0.0a-war.zip + unzip geoserver-2.0.0a-war.zip + +unzip geoserver.war -d /usr/local/tomcat/webapps + +mv /usr/local/tomcat/webapps/geoserver/data /usr/local/geodata + You should now change the default Geoserver password to something more secure. Execute nano /usr/local/geodata/security/users.properties and change the password and then save all changes. + Edit one of your persistent environment variables (see this page for details). Add the following lines to the chosen file. + export JAVA_HOME=/usr/lib/jvm/java-6-sun + export JDK_HOME= /usr/lib/jvm/java-6-sun + + export JAVA_OPTS=-XX:PermSize=256m -XX:MaxPermSize=1536 -Xms512m -Xmx1024m -server + + export GEOSERVER_DATA_DIR=/usr/local/geodata + + export DHIS2_HOME=/root/dhis/dhis2 + + Note that you may need to alter the file paths to point to the actual directories on your system. + Assuming that you have installed the postgresql database system, you can create a new database with the following commands. + sudo su - postgres + createdb createdb -E utf-8 dhis + Note that you can change the name of the database to anything that suits your environment. + To tell the DHIS2 application where to find its database you need a hibernate.properties file in DHIS2_HOME . For a postgres database connection to a database called 'dhis', with user name and password 'dhis', you need to put the following inside your file /root/dhis/dhis2/hibernate.properties: + hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect + hibernate.connection.driver_class = org.postgresql.Driver + + hibernate.connection.url = jdbc:postgresql:dhis + hibernate.connection.username = dhis + hibernate.connection.password = dhis + + hibernate.hbm2ddl.auto = update + Save this file in the DHIS2_HOME directory. Exit the current shell in order to reload the environment variables and open a new shell. You will need to start both postgresql as well as the tomcat server. If you installed postgresql with the apt-get command, you can start this from the /etc/init.d/ directory with the commands. + sudo su - + cd /etc/init.d/ + ./S18postgresql start + Note that you may need to alter this command to your particular system. + It is good security practise to run the tomcat application as a separate user. If you do not already have a separate user account, you can create one with the following commands. + sudo useradd -d /home/tomcat6 -m tomcat6 + sudo passwd tomcat6 + You should not change the file permissions for the entire directory that you installed Tomcat to, with the following command. + sudo chown -R tomcat6:tomcat6 /usr/local/tomcat + To start the application, login as the user, navigate to the /usr/local/tomcat/bin/ directory, and execute the start.sh script. + sudo su - tomcat6 + cd /usr/local/tomcat/bin + ./startup.sh +

+ Installing DHIS2 with the Debian install package + If you are using Ubuntu or Debian, a separate Debian installation package has been created to simplify the installation process. You can simply download this file and then install DHIS2 from the command line with the following command. + sudo dpkg -i dhis2-2.0.3.deb + You can also install this Debian package from your systems package manager. +

+ Creating new users and roles + This section will describe how to add new users to the DHIS 2 + application. +

+ Open User Menu + To create or find a user begin with clicking on the ‘user’ module + displayed in the drop down menu of the Maintenance module located on the + main tool bar on the top part of the displayed screen. User names + already registered will appear as a list as seen in the screen shot + below. + + Select Users menu item + + + + + + + + Search by user name + + + + + + + You can search for specific user names in the user list by + entering the name in the ‘filter by user name’ field as shown + above. +

+ Define a new role + As part of creating a user name you are required to define the user + role. Do so by clicking on the ‘user role’ appearing on the left side of + the displayed screen. + + Create new user role + + + + + + + This will lead you to the Role Management page where you will have + to click on Add new to create a new role. + + Add new user role + + + + + + + The following screen will open and here in the first text box you + need to give Name of the Role such as Super User, Admin User, etc. The + second text box called ‘Description’ gives more information about the + type of User Role that is being created for e.g. State Admin User, + District Data Entry. + + Role maintenance page + + + + + + + Next you will specify the particular data set(s) that are to be + made available to the particular role. You will also need to specify the + type of ‘authority’ to be given to the particular user. For each of the + three options namely Datasets, Reports and Authorities user can select + multiple options from the scroll down menu provided against each field. + A user can choose multiple options either by moving them + one-by-one. + + Adding a dataset to a user role + + + + + + + In order for particular users to be able to enter data, you must + add them to both a dataset as well as an organisational unit level. You + can also select multiple datasets individually by pressing the Ctrl key + on the keyboard and clicking on individual datasets. + + Adding multiple datasets to user roles + + + + + + + Finally when you have entered the required fields click on + Save which is located on the lower part of the + displayed screen. The desired user role and related authorisation will + be saved to the database, and can then be assigned to a particular + user. +

+ Add New User + Under particular user role there can be more than one user. To add + new users go to the User options under the Maintenance module. + + Add new user + + + + + + + To add a new user, just follow these steps: + + + Click on the Add New button. + + + Enter New User details like User name, + Password, Confirm password, Surname, First name and Email in new user’s option + tabs. + + + Click on Add button for confirmation of + new user details and follow the user error while creation of new + user. + + + The recently created new user can be seen in main’ User + management Screen + + + You can edit (like password, surname….etc) and delete the + details of new/old users by selecting corresponding User’s + Edit and Delete + Buttons. + + + Click on Save tab after editing all + details of a particular selected user. + + Add or edit users + + + + + + + + User management screen + + + + + + + + +