dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 263
committer: Lars Helge Overland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Fri 2011-02-11 18:23:44 +0100
message:
  Added section on installing dhis2 on server
modified:
  src/docbkx/en/dhis2_implementation_guide_installation.xml


--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs

Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription

=== modified file 'src/docbkx/en/dhis2_implementation_guide_installation.xml'
--- src/docbkx/en/dhis2_implementation_guide_installation.xml	2011-02-11 15:11:12 +0000
+++ src/docbkx/en/dhis2_implementation_guide_installation.xml	2011-02-11 17:23:44 +0000
@@ -1,11 +1,33 @@
 <?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. -->
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
+<!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
 <chapter>
   <title>Installation</title>
   <para>The installation chapter provides information on how to install DHIS 2 in various contexts, including online central server, offline local network, standalone application and self-contained package called DHIS 2 Live.</para>
   <para>DHIS 2 runs on all platforms for which there exists a Java Runtime Environment version 6 or higher, which includes most popular operating systems such as Windows, Linux and Mac. DHIS 2 also runs on many relational database systems such as PostgreSQL, MySQL, H2 and Derby. DHIS 2 is packaged as a standard Java Web Archive (WAR-file) and thus runs on any Servlet containers such as Tomcat and Jetty.</para>
   <para>The DHIS 2 team recommends Ubuntu 10.1.0 operating system, PostgreSQL database system and Tomcat Servlet container as the preferred environment for server installations. The mentioned frameworks can be regarded as market leaders within their domain and is heavily field tested over many years.</para>
   <para>This chapter provides a guide for setting up the above technology stack. It should however be read as a guide for getting up and running and not as an exhaustive documentation for the mentioned environment. We refer to the offical Ubuntu, PostgreSQL and Tomcat documentation for in-depth reading.</para>
-  <para/>
+  <section>
+    <title>Server setup</title>
+    <para>This section describes how to set up a server instance of  DHIS 2 on Ubuntu 10.10 64 bit with PostgreSQL as database system and Tomcat as Servlet container. The term <emphasis role="italic">invoke</emphasis> refers to executing a given command in a terminal. You can find the terminal in <emphasis role="italic">Applications</emphasis> - <emphasis role="italic">Accessories</emphasis> - <emphasis role="italic">Terminal</emphasis>.</para>
+    <para>For a national server the recommended configuration is a multicore 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 10.10 64 bit edition is thus recommended. For this guide we assume that 4 Gb RAM is allocated for PostgreSQL and 7 GB RAM is allocated for Tomcat. If you are running a different configuration please adjust the suggested values accordingly.</para>
+    <para><emphasis role="bold">Install Java</emphasis></para>
+    <para>Enable Partner repositories by opening <emphasis role="italic">/etc/apt/sources.list</emphasis>and adding the line <emphasis role="italic">deb http://archive.canonical.com/ubuntu maverick partner</emphasis> at the end of the file. Then invoke <code>sudo apt-get -f install</code> to update the package list.</para>
+    <para>Install Java by invoking <code>sudo apt-get install sun-java6-jdk</code></para>
+    <para><emphasis role="bold">Install PostgreSQL</emphasis></para>
+    <para>Install PostgreSQL by invoking <code>sudo apt-get install postgresql-8.4</code></para>
+    <para>Set the password for the postgres Unix user by invoking <code>sudo passwd postgres</code> and following the instructions. Switch to the postgres user by invoking <code>su postgres</code> and entering the password when prompted.</para>
+    <para>Log into psql by invoking <code>psql</code> Create a user called <emphasis role="italic">dhis</emphasis>  by invoking <code>create user dhis with password &lt;dhis&gt;</code> Replace the password <emphasis role="italic">&lt;dhis&gt;</emphasis> with something secure. Create a database by invoking <code>create database dhis2 with owner dhis encoding &apos;utf&apos;</code> Exit psql by invoking <code>\q</code> Return to your session by invoking <code>exit</code> You now have a PostgreSQL user called <emphasis role="italic">dhis</emphasis> and a database called <emphasis role="italic">dhis2</emphasis>.</para>
+    <para>Do basic performance tuning by increasing the operating system kernel shared memory by opening file /etc/sysctl.conf and adding the line <emphasis role="italic">kernel.shmmax = 1073741824</emphasis> at the end of it. Make the change take effect by invoking <code>sysctl -p</code>  Then open  file <emphasis role="italic">/etc/postgresql/8.4/main/postgresql.conf</emphasis> and set the following properties: <code>shared_buffers = 250MB | synchronous_commit = on | wal_writer_delay = 10000ms | effective_cache_size = 3750MB</code></para>
+    <para>Restart PostgreSQL by invoking <code>sudo /etc/init.d/postgresql restart</code></para>
+    <para><emphasis role="bold">Set the database configuration</emphasis></para>
+    <para>The database connection information is provided to DHIS 2 through a configuration file called <emphasis role="italic">hibernate.properties</emphasis>. Create this file and save it in a convenient location. A  file corresponding to the above setup has these properties: </para>
+    <para><code>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 = dhis hibernate.hbm2ddl.auto = update</code></para>
+    <para><emphasis role="bold">Install Tomcat</emphasis></para>
+    <para>Download the Tomcat binary distribution from  <emphasis role="italic">http://tomcat.apache.org/download-70.cgi</emphasis> Extract to a convenient location. This guide assumes that you have navigated to the root directory of the extracted archive.</para>
+    <para>Clear the pre-installed web applications by invoking <code>rm -rf webapps/*</code> Download the latest DHIS 2 WAR file from <emphasis role="italic">http://dhis2.org/download</emphasis> and move it to the <emphasis role="italic">webapps</emphasis> directory.</para>
+    <para>Open file bin/startup.sh and add these lines. The first 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 <emphasis role="italic">hibernate.properties</emphasis> configuration file, note that you should adjust this to your environment:</para>
+    <para><code>export JAVA_HOME=&apos;/usr/lib/jvm/java-6-sun&apos; | export JAVA_OPTS=&apos;-Xmx6000m -XX:MaxPermSize=1000m&apos; | export DHIS2_HOME=&apos;/home/dhis/config&apos;</code></para>
+    <para><emphasis role="bold">Run DHIS 2</emphasis></para>
+    <para>Make the startup script executable by invoking <code>chmod 755 bin/*</code> DHIS 2 can now be started by invoking <code>bin/startup.sh</code> The log can be monitored by invoking <code>tail -f logs/catalina.out</code> DHIS 2 can be stopped by invoking <code>bin/shutdown.sh</code></para>
+  </section>
 </chapter>