dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #31530
[Branch ~dhis2-devs-core/dhis2/trunk] Rev 16078: dhis2-tools:
------------------------------------------------------------
revno: 16078
committer: Bob Jolliffe <bobjolliffe@xxxxxxxxx>
branch nick: dhis2
timestamp: Thu 2014-07-10 19:05:30 +0100
message:
dhis2-tools:
Improved documentation. Added two new scripts:
dhis2-clone to clone an instance
dhis2-logtail to "tail" the logfile of an instance.
added:
tools/dhis2-tools-deb/pkg/usr/bin/dhis2-clone
tools/dhis2-tools-deb/pkg/usr/bin/dhis2-logtail
modified:
tools/dhis2-tools-deb/docs/architecture.svg
tools/dhis2-tools-deb/docs/manual.xml
--
lp:dhis2
https://code.launchpad.net/~dhis2-devs-core/dhis2/trunk
Your team DHIS 2 developers is subscribed to branch lp:dhis2.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-devs-core/dhis2/trunk/+edit-subscription
=== modified file 'tools/dhis2-tools-deb/docs/architecture.svg'
--- tools/dhis2-tools-deb/docs/architecture.svg 2014-07-04 10:56:19 +0000
+++ tools/dhis2-tools-deb/docs/architecture.svg 2014-07-10 18:05:30 +0000
@@ -15,7 +15,10 @@
id="svg2"
version="1.1"
inkscape:version="0.48.3.1 r9886"
- sodipodi:docname="architecture.svg">
+ sodipodi:docname="architecture.svg"
+ inkscape:export-filename="/home/bobj/src/dhis/test/dhis2/tools/dhis2-tools-deb/docs/architecture.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90">
<defs
id="defs4">
<marker
@@ -637,8 +640,8 @@
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
- inkscape:window-width="1280"
- inkscape:window-height="776"
+ inkscape:window-width="1680"
+ inkscape:window-height="1026"
inkscape:window-x="0"
inkscape:window-y="24"
inkscape:window-maximized="1" />
@@ -650,7 +653,7 @@
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage"; />
- <dc:title />
+ <dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
@@ -1088,22 +1091,6 @@
id="path5173"
inkscape:connector-curvature="0"
transform="translate(0,308.2677)" />
- <text
- xml:space="preserve"
- style="font-size:22px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
- x="905.71429"
- y="51.237339"
- id="text5179"
- sodipodi:linespacing="125%"
- transform="translate(0,308.2677)"><tspan
- sodipodi:role="line"
- id="tspan5181"
- x="905.71429"
- y="51.237339">MOHCC</tspan><tspan
- sodipodi:role="line"
- x="905.71429"
- y="78.737335"
- id="tspan5183">Premises</tspan></text>
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="M 844.28571,271.23734 C 818.57143,422.66591 818.57143,422.66591 818.57143,422.66591"
@@ -1216,33 +1203,7 @@
height="127.14286"
x="67.14286"
y="552.66589" /></flowRegion><flowPara
- id="flowPara5505" /></flowRoot> <g
- transform="translate(782.85715,-272.14285)"
- id="g5507-3">
- <path
- transform="translate(0,308.2677)"
- d="m 285.71428,613.38019 c 0,28.00873 -44.13193,50.71428 -98.57143,50.71428 -54.43949,0 -98.571424,-22.70555 -98.571424,-50.71428 0,-28.00873 44.131934,-50.71429 98.571424,-50.71429 54.4395,0 98.57143,22.70556 98.57143,50.71429 z"
- sodipodi:ry="50.714287"
- sodipodi:rx="98.571426"
- sodipodi:cy="613.38019"
- sodipodi:cx="187.14285"
- id="path5493-7"
- style="opacity:0.22633745;fill:#aff1dc;fill-opacity:1;stroke:#00fff9;stroke-width:0.00670627;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
- sodipodi:type="arc" />
- <text
- transform="translate(0,308.2677)"
- sodipodi:linespacing="125%"
- id="text5495-3"
- y="619.80878"
- x="135.71429"
- style="font-size:22px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
- xml:space="preserve"><tspan
- y="619.80878"
- x="135.71429"
- id="tspan5497-5"
- sodipodi:role="line">Users</tspan></text>
- </g>
- <path
+ id="flowPara5505" /></flowRoot> <path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
d="m 278.57143,609.80877 c 78.57143,-2.85714 80,-2.85714 80,-2.85714"
id="path5539"
@@ -1346,5 +1307,5 @@
height="40"
x="-227.14285"
y="394.09448" /></flowRegion><flowPara
- id="flowPara4295"></flowPara></flowRoot> </g>
+ id="flowPara4295" /></flowRoot> </g>
</svg>
=== modified file 'tools/dhis2-tools-deb/docs/manual.xml'
--- tools/dhis2-tools-deb/docs/manual.xml 2014-07-04 10:56:19 +0000
+++ tools/dhis2-tools-deb/docs/manual.xml 2014-07-10 18:05:30 +0000
@@ -33,15 +33,15 @@
</para>
</listitem>
<listitem>
- <para>to provide a set of scripts to assist the administrator with tasks related to managing their
- dhis2 system, beyond the one-off process of installation.</para>
+ <para>to provide a set of scripts to assist the administrator with tasks related to managing
+ their dhis2 system, beyond the one off process of installation.</para>
</listitem>
</orderedlist>
The package remains a work in progress and there are a number of areas where it could and should
(and hopefully will be improved). For example,
<orderedlist>
- <listitem><para>currently the tuning of the postgresql database is not covered. There are ways in which
- this could be at least semi-automated;</para></listitem>
+ <listitem><para>currently the tuning of the postgresql database is not covered. There are ways in which this
+ could be at least semi automated;</para></listitem>
<listitem><para>nginx configuration is assisted by means of providing a sample configuration file.
This configuration could be made more dynamic;</para></listitem>
<listitem><para>the format of what is currently packaged is an Ubuntu linux deb package. There is
@@ -50,43 +50,92 @@
</para></listitem>
</orderedlist>
</para>
-
+ </chapter>
+
+ <chapter>
+ <title>Architecture</title>
<para>
+ The figure below shows the main components involved in a DHIS2 system.
<figure>
<title>Single machine all-in-one installation</title>
- <graphic fileref="architecture.svg" align="center" width="80%"/>
+ <graphic fileref="architecture.png" align="center" width="80%" format="PNG"/>
</figure>
+ The dhis2-tools are primarily concerned with the creation and managing of the tomcat instances
+ which deliver the web application. As you can see in the diagram there may be one or more of these.
+ In addition the system requires a postgresql database server and an nginx web proxy server. There
+ are many possible configurations where these can be running on a different server than the dhis2
+ instances. These tools for the most part assume that they are all installed together on the one machine.
+ Some customisation is required to separate them.
+ </para>
+ <para>
+ When an instance is created with the dhis2-create-instance command, a new user is created with the name
+ of the instance (lets say its called hmis). The home directory of that user is located at /var/lib/dhis2/hmis.
+ A database role is created also called hmis together with a database with the name of hmis. The DHIS2_HOME
+ environment variable for the instance is set to the same home directory of the user.
+ </para>
+ <para>The essential components of a standalone tomcat instance are also created within the same directory
+ (modelled after the ubuntu tomcat7-user package). The web.xml file of that tomcat instance has been customized
+ to allow an upstream web proxy server (such as nginx) to cache the static content of the dhis2 application.
+ </para>
+ <para>
+ The user will also have a crontab configuration automatically setup to manage daily backups, start on computer restart
+ and log file rotation.
+ </para>
+ <para>
+ Note that postgresql optimization, as described in the dhis2 user documentation, is not managed by this package and
+ needs to be done as a post-installation step.
</para>
</chapter>
<chapter>
<title>Installation</title>
- <para> This manual assumes that you have installed a minimal distribution of ubuntu server 12.04 LTS.
- By minimal we mean that only the base operating system is installed together with an openssh server.
- During the installation you shouls avoid to install ANY other packages (like java, postgres, nginx etc).
- The dhis2-tools package and install.sh script will ensure that these required packages are installed
- as dependencies.</para>
+ <para> This manual assumes that you have installed a minimal distribution of ubuntu server 12.04
+ LTS or 14.04 LTS. By minimal we mean that only the base operating system is installed together
+ with an openssh server. During the installation you should avoid to install ANY other packages
+ The dhis2-tools package will ensure that the required packages are installed as dependencies.</para>
<para>
It is recommended as a general guideline that before proceeding any further you should strengthen the
- security of the system at this point by securing your ssh service properly and installing a host based
+ security of the system at this point by improving the security of your ssh service and installing a host based
firewall like ufw. This process is described eleswhere(?).
</para>
- <para> Once your base system is properly installed and secured you can proceed to install the
- dhis2-tools package. To do so you need to copy the two file dhis2-tools-xxx.deb and install.sh
- to the server. Place them together in a directory under your user's home directory. To do this
- you will need to use a tool like scp (on linux) or winscp on windows.
- </para>
- <para>
- Once the files are in place you can install the tools by typing the following:
- </para>
- <para><code>sudo ./install.sh</code></para>
- <para>there must be at least
- one user who has full sudo rights (usermod -G sudo bobj). That user can run the
- dhis-create-admin command and create new dhis administrators. These dhis admins do not need to
- have root access at all, but they have full rights to the database and all (other) dhis
- commands. The idea being that as you work with fledgling dhis admin users you can give them
- rights without making them all root. Maybe it is too fanciful .. all the magic is happening in
- /etc/sudoers.d/dhis2 (though looking at that again I suspect I actually have something wrong
- there) </para>
+ <para>
+ Once your base system is properly installed and secured you can proceed to install the
+ dhis2-tools package from the apt repository at http://apt.dhis2.org. The easiest way to do so is to
+ run the install.sh script available at ...
+ </para>
+ <para>
+ The simplified set of steps to get a dhis2 instance up and running from here are:
+ <orderedlist>
+ <listitem>
+ <para>turn your user (eg bobj) into a dhis2-admin user by running:</para>
+ <para>sudo dhis2-create-admin bobj </para>
+ </listitem>
+ <listitem>
+ <para>create an instance named eg dhis with:</para>
+ <para>dhis2-instance-create dhis</para>
+ </listitem>
+ <listitem>
+ <para>deploy the latest stable war file with:</para>
+ <para>dhis2-deploy-war dhis</para>
+ </listitem>
+ <listitem>
+ <para>setup a basic nginx template with:</para>
+ <para>dhis2-nginx</para>
+ <para>
+ Note that nginx configuration is not done automatically. Though running the command dhis2-nginx will
+ create a simple site configuration file under /etc/nginx/sites-enabled/dhis2. You may need to edit this file
+ to ensure that instance names and port numbers are correct.
+ </para>
+ </listitem>
+ <listitem>
+ <para>start your dhis instance with:</para>
+ <para>dhis2-startup dhis</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>
+ A full description of these commands and others used for managing your instance is included in the
+ command reference section below.
+ </para>
</chapter>
<chapter>
@@ -150,6 +199,14 @@
<para>http port</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>-n</term>
+ <listitem>
+ <para>DO NOT create the database when creating the instance. Note if you use this
+ option you will have to manually edit the properties file at
+ /var/lib/dhis2/<instance>/hibernate.properties.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
<refsect1>
@@ -178,7 +235,7 @@
<refsynopsisdiv>
<cmdsynopsis>
<command>/usr/bin/dhis2-startup</command>
- <arg choice="opt">instance name</arg>
+ <arg choice="req">instance name</arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -190,6 +247,10 @@
<title>Examples</title>
<para>dhis2-startup myInstance</para>
</refsect1>
+ <refsect1>
+ <title>See also</title>
+ <para>dhis2-shutdown (1), dhis2-deploy-war (1) and dhis2-instance-create (1).</para>
+ </refsect1>
</refentry>
<!-- ============================================================================== -->
@@ -206,7 +267,7 @@
<refsynopsisdiv>
<cmdsynopsis>
<command>/usr/bin/dhis2-shutdown</command>
- <arg choice="opt">instance name</arg>
+ <arg choice="req">instance name</arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -218,11 +279,53 @@
<title>Examples</title>
<para>dhis2-shutdown myInstance</para>
</refsect1>
+ <refsect1>
+ <title>See also</title>
+ <para>dhis2-startup (1)</para>
+ </refsect1>
</refentry>
<!-- ============================================================================== -->
<refentry>
<refmeta>
+ <refentrytitle>dhis2-clone</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>dhis2-clone</refname>
+ <refpurpose>Clones the database of one instance to another instance</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>/usr/bin/dhis2-clone</command>
+ <arg choice="req">master</arg>
+ <arg choice="req">copy</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>This command creates a copy of the database and war file of one instance into another
+ instance. The main use case for this is where you want to setup an instance for training
+ purposes. Trainees can be "let loose" on the training instance without fear of disturbing
+ the data or configuration of the production instance. They will however be working with the
+ same usernames, forms and reports which exist in the master. The command should be executed with
+ care as it will completely replace the existing database of the target instance</para>
+ <para>Scheduled datamart and analytics generation jobs are disabled in the target instance.</para>
+ <para>The command could conceivably be scheduled to run in the early morning to ensure that the database is
+ restored to a pristine state for the start of each day's training. Or it can be run on demand.</para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>dhis2-clone hmis training</para>
+ <para>Creates a new instance called training from an existing instance called hmis.</para>
+ </refsect1>
+ </refentry>
+
+ <!-- ============================================================================== -->
+ <refentry>
+ <refmeta>
<refentrytitle>dhis2-deploy-war</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
@@ -295,24 +398,62 @@
<refname>dhis2-logview</refname>
<refpurpose>Shows log file</refpurpose>
</refnamediv>
-
+
<refsynopsisdiv>
<cmdsynopsis>
<command>/usr/bin/dhis2-logview</command>
- <arg choice="opt">instance name</arg>
+ <arg choice="req">instance name</arg>
</cmdsynopsis>
</refsynopsisdiv>
-
+
<refsect1>
<title>Description</title>
- <para>Use this tool to view log of dhis2 instance using less.</para>
+ <para>Use this tool to view log of dhis2 instance using less. Type ":q" to exit.
+ See the man page for less for tips in navigating and searching the file.</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>dhis2-logview myInstance</para>
</refsect1>
- </refentry>
-
+ <refsect1>
+ <title>See also</title>
+ <para>dhis2-logtail (1).</para>
+ </refsect1>
+
+ </refentry>
+
+ <!-- ============================================================================== -->
+ <refentry>
+ <refmeta>
+ <refentrytitle>dhis2-logtail</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>dhis2-logtail</refname>
+ <refpurpose>Shows the bottom log file in real time. Type Ctrl-C to exit.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>/usr/bin/dhis2-logtail</command>
+ <arg choice="req">instance name</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>Use this tool to show the log of dhis2 instance in real time.</para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>dhis2-logtail myInstance</para>
+ </refsect1>
+ <refsect1>
+ <title>See also</title>
+ <para>dhis2-logview (1).</para>
+ </refsect1>
+ </refentry>
+
<!-- ============================================================================== -->
<refentry>
<refmeta>
@@ -327,7 +468,7 @@
<refsynopsisdiv>
<cmdsynopsis>
<command>/usr/bin/dhis2-create-admin</command>
- <arg choice="opt">username</arg>
+ <arg choice="req">username</arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -343,4 +484,75 @@
</refsect1>
</refentry>
</chapter>
+
+ <chapter>
+ <title>Troubleshooting guide</title>
+ <para>The following table shows some common problems which occur and likely remedies:</para>
+ <para>
+ <table>
+ <title>Troubleshooting guide</title>
+ <tgroup cols="2" align="left" colsep="1" rowsep="1">
+ <colspec colname="c1" colwidth="1*"/>
+ <colspec colname="c2" colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>Problem</entry>
+ <entry>Solution</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para> When you attempt to access the site with your browser it does not connect.
+ </para>
+ </entry>
+ <entry>
+ <para> Either there is a network problem or nginx is not running. Check first to see
+ if you can ping the host. If not you have a network problem. If you can ping the
+ site, the most likely problem is that nginx is not installed or is not running.
+ Verify that nginx is up and running and listening on ports 443 and 80 by typing: </para>
+ <para><code>sudo netstat -ntlp</code>
+ </para>
+ <para>You should see the nginx process listening on those 2 ports</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para> You can access the site but you see a 502 gateway error in your browser.
+ </para>
+ </entry>
+ <entry>
+ <para> This means that nginx is unable to connect to your backend dhis2 instance.
+ Either the instance is not running or your nginx location configuration has an
+ error. Running the same netstat command above should show your instance listening
+ on 127.0.0.1 with a port number typically 8080 or whatever you have configured it
+ as. </para>
+ <para> If its not running, try to start it with <code>dhis2-startup [instance
+ name]</code>
+ </para>
+ <para>If it is still not running, check the log file with <code>dhis2-logview
+ [instance name]</code> to see if there is any information indicating why it has
+ failed to start.</para>
+ <para>If it is running and you can see it with netstat then you need to check your
+ nginx configuration file to ensure that the locatio is correctly mapped.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>You can access the site but you see a blank page in your browser.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This usually means that the dhis2 instance is running, but you have forgotten
+ to deploy a war file to it. You need to run dhis2-deploy-war on that instance.
+ See the reference section above for details of options.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </chapter>
</book>
=== added file 'tools/dhis2-tools-deb/pkg/usr/bin/dhis2-clone'
--- tools/dhis2-tools-deb/pkg/usr/bin/dhis2-clone 1970-01-01 00:00:00 +0000
+++ tools/dhis2-tools-deb/pkg/usr/bin/dhis2-clone 2014-07-10 18:05:30 +0000
@@ -0,0 +1,36 @@
+#!/bin/bash
+# ____ __ ______________
+# / __ \/ / / / _/ ___/__ \
+# / / / / /_/ // / \__ \__/ /
+# / /_/ / __ // / ___/ / __/
+# /_____/_/ /_/___//____/____/
+#
+# Clone a DHIS2 instance
+
+if [ "$#" -ne 2 ]; then
+ echo "usage: dhis2-clone <master> <slave>"
+ exit 1
+fi
+
+# set -e
+
+MASTER=$1
+SLAVE=$2
+
+[ -d /var/lib/dhis2/$1 ] || { echo "Oops! Make sure $1 instance exists before cloning."; exit 1; }
+[ -d /var/lib/dhis2/$2 ] || { echo "Oops! Make sure $2 instance exists before cloning."; exit 1; }
+
+echo "cloning $2 from $1 ..."
+dhis2-shutdown $2 2>/dev/null;
+sleep 5
+
+dropdb $2
+createdb -O $2 $2
+pg_dump $1 | psql $2
+
+psql -c "reassign owned by $1 to $2" $2
+# disable midnight scheduled tasks on the clone
+psql -c "delete from systemsetting where name = 'keyScheduledTasks';" $2
+
+# make sure clone runs the same war file as master
+dhis2-deploy-war -f /var/lib/dhis2/$1/webapps/$1.war $2
=== added file 'tools/dhis2-tools-deb/pkg/usr/bin/dhis2-logtail'
--- tools/dhis2-tools-deb/pkg/usr/bin/dhis2-logtail 1970-01-01 00:00:00 +0000
+++ tools/dhis2-tools-deb/pkg/usr/bin/dhis2-logtail 2014-07-10 18:05:30 +0000
@@ -0,0 +1,17 @@
+#!/bin/sh
+# ____ __ ______________
+# / __ \/ / / / _/ ___/__ \
+# / / / / /_/ // / \__ \__/ /
+# / /_/ / __ // / ___/ / __/
+# /_____/_/ /_/___//____/____/
+#
+# DHIS2 instance log viewer
+
+if [ "$#" -ne 1 ]; then
+ echo "usage: dhis2-logview <instance name>"
+ exit 1
+fi
+
+INSTANCE=$1
+
+sudo -u $INSTANCE less /var/lib/dhis2/$INSTANCE/logs/catalina.out
