dhis2-devs team mailing list archive

[Bob Jolliffe <bobjolliffe@xxxxxxxxx>]

Hi guys

I haven't used this myself, but looking at the docs it seems that
nginx is setup to do straight http proxying ie. it is not talking ajp
to the backend tomcat server.  Is this correct?

I could be wrong, but Jo/Morten this might have some implication with
the absolute URLs being used in the web-api.

Cheers
Bob

On 12 December 2011 07:15,  <noreply@xxxxxxxxxxxxx> wrote:
> ------------------------------------------------------------
> revno: 426
> committer: Jason P. Pickering <jason.p.pickering@xxxxxxxxx>
> branch nick: dhis2-docbook-docs
> timestamp: Mon 2011-12-12 09:11:53 +0200
> message:
>  Added section on using nginx as a reverse proxy to the setup documentation. Polished up the GIS section a bit.
> modified:
>  src/docbkx/en/dhis2_implementation_guide_installation_detailed.xml
>  src/docbkx/en/dhis2_user_man_creating_gis.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_detailed.xml'
> --- src/docbkx/en/dhis2_implementation_guide_installation_detailed.xml  2011-10-04 14:33:11 +0000
> +++ src/docbkx/en/dhis2_implementation_guide_installation_detailed.xml  2011-12-12 07:11:53 +0000
> @@ -532,7 +532,30 @@
>       <para>Now, just restart Apache and you should be able to view https://foo.mydomain.org/dhis. </para>
>       <screen>/etc/init.d/apache2 restart</screen>
>     </section>
> -    <section/>
> +    <section>
> +      <title>Reverse proxy with nginx</title>
> +      <para><ulink url="http://wiki.nginx.org";>Nginx</ulink> is a high-performance web server and reverse proxy with built with high concurrency, performance and low-memory usage in mind. For more installations, <application>nginx </application>may be a better alternative than the Apache web server for reverse proxy implementations. </para>
> +      <para>To get started, simply install nginx on your system with the following command.</para>
> +      <para><screen>sudo apt-get install nginx</screen></para>
> +      <para>A sample configuration file is below, and should be placed in <filename>/etc/nginx/sites-available</filename>.</para>
> +      <para><screen>server {
> +    listen  *:80;
> +    server_name  dhis.foo.org;
> +location ~ \.(gif|jpg|png|css|js)$ {
> +
> +root /var/lib/tomcat6/webapps/;
> +}
> +
> +location / {
> +      proxy_pass http://localhost:8080/;
> +      proxy_set_header        X-Real-IP $remote_addr;
> +      proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
> +      proxy_set_header        Host $http_host;
> + }
> +}
> +</screen></para>
> +      <para>You will need to adjust the <varname>server_name</varname>, and <varname>proxy_pass</varname> variables to suit your particular setup. The server name must match exactly the name of the server which will be running DHIS. In this particular setup, nginx will serve all static content and then redirect dynamic requests to the application server. Once you have adjusted the configuration file to suit your needs, be sure to activate it by creating a symbolic link in the <filename>/etc/nginx/sites-enabled </filename>directory which points to the file.</para>
> +    </section>
>     <section>
>       <title>Performance tuning</title>
>       <para>To increase Tomcat&apos;s performance, you can install the native APR library by invoking:</para>
>
> === modified file 'src/docbkx/en/dhis2_user_man_creating_gis.xml'
> --- src/docbkx/en/dhis2_user_man_creating_gis.xml       2011-12-01 07:05:24 +0000
> +++ src/docbkx/en/dhis2_user_man_creating_gis.xml       2011-12-12 07:11:53 +0000
> @@ -4,26 +4,29 @@
>   <title>Setting up GIS</title>
>   <section>
>     <title>Context</title>
> -    <para>
> -      Setting up the GIS simply means storing coordinates for the organisation units you want to show on the map in the database. Coordinates are  often distributed in  proprietary formats. ESRI shapefiles are the most common geospatial vector data format for desktop applications.  You might find shapefiles for your country <ulink url="http://www.diva-gis.org/gd";>here</ulink> or many other geospatial data repositories on the web. Some amount of work needs to be done in order to use these coordinates in DHIS 2 GIS, namely transforming the data into a suitable format and ensuring the name which are contained in the geospatial data match exactly with the names of the organization units which they should be matched to. </para>
> +    <para>Setting up the GIS simply means storing coordinates for the organisation units you want to show on the map in the database. Coordinates are  often distributed in  proprietary formats and will need to be converted to a format which DHIS2 uses. ESRI shapefiles are the most common geospatial vector data format for desktop applications.  You might find shapefiles for your country <ulink url="http://www.diva-gis.org/gd";>here</ulink> or in many other geospatial data repositories on the web. Some amount of work needs to be done in order to use these coordinates in DHIS 2 GIS, namely transforming the data into a suitable format and ensuring the name which are contained in the geospatial data match exactly with the names of the organization units which they should be matched to. </para>
>     <para>If you go to the organisation unit module and edit one of the units, you can see a text field called Coordinates. Here you may fill in its coordinates directly (geojson format) which is useful if you just want to update a couple of units.</para>
>     <para>An example point/facility coordinate:</para>
>     <para><programlisting><userinput>[29.341,-11.154]</userinput></programlisting></para>
>     <para>An example polygon/area coordinates string:</para>
>     <para><programlisting><userinput>[[[[29.343,-11.154],[28.329,-11.342],[28.481,-10.239],[29.833,-10.412]]]]</userinput></programlisting></para>
> -    <para>However, if you are going to e.g. add coordinates for all units at a certain level you don&apos;t want to do that manually. This is where the automatic GML import comes into play and the following section explains the preferred way of using it.<note>
> -        <para>The only projection system supported by DHIS2 is EPSG 4326. Coordinates must be stored with the longitude (east/west position) proceeding the latitude (north/south position. If you vector data is in a different format than EPSG 4326, you will need to reproject first before importing. </para>
> -      </note></para>
> +    <para>However, if you are going to e.g. add coordinates for all units at a certain level you don&apos;t want to do that manually. This is where the automatic GML import comes into play and the following section explains the preferred way of using it.<important>
> +        <para>The only co-ordinate reference system supported by DHIS2 is EPSG:4326, also known as geographic longitude/latitude. Coordinates must be stored with the longitude (east/west position) proceeding the latitude (north/south position). If your vector data is in a different CRS than EPSG 4326, you will need to reproject the data first before importing into DHIS2. </para>
> +      </important></para>
>   </section>
>   <section id="gisSetup">
>     <title>Importing coordinates</title>
> -    <para>Step 1 - Simplify/generalize your shapefile</para>
> -    <para>
> -      The boundaries in shapefiles are usually very accurate. This does not cause any trouble for hardware accelerated desktop based GIS software, but it might be too heavy for the web based GIS application in DHIS 2. Thus, we need to make the boundary lines less detailed by removing some of the line points. Go to <ulink url="http://mapshaper.com/test/demo.html";>http://mapshaper.com/test/demo.html</ulink> and upload your shapefile. Then, at the center bottom you see a slider that starts at 0%. It is usually ok to drag it up to about 80%. In the left menu you can check &quot;show original lines&quot; to compare the result and you may want to give a different simplification method a try. When you are happy with the result, click &quot;export&quot; in the top right corner. Then check the first of the four options called &quot;Shapefile - polygons&quot;, click &quot;create&quot; and wait for the download buttons to appear. Now, download the two files and overwrite the existing .shp and .shx files in your shapefile set (a shapefile is actually a set that has three mandatory files called .shp, .shx and .dbf and sometimes up to 15 files in total). Move on to the next step with your new simplified shapefile.
> +    <para>Step 1 - Simplify/generalize your geographical data</para>
> +    <para>The boundaries in geographical data files are usually very accurate, too much so for the needs of a web-based GIS. This usually does not affect the performance when using GIS files on a a local system, but it is usually necessary to optimize the geographical data for the web-based GIS system of DHIS2. All geographical data needs to be downloaded from the server and rendered in a browser, so if the data is overly complex, the performance of the DHIS2 GIS will be negatively impacted. This optimization process can be described as follows:</para>
> +    <para><simplelist>
> +        <member>Coordinates: The number of significant decimal digits (e.g. 23.02937874993774) should be shortened to fewer digits (e.g. 23.03). Although this will result in some inaccuracies on the map, given the usual scale at which maps in DHIS2 are produced (&gt; 1:50,000), the loss of precision should not be noticeable. Normally, no more than four significant digits after the decimal point should be necessary.</member>
> +        <member>Polygons: In addition to shortening the number of significant digits, the actual number of points should also be reduced to an optimal level. Finding this optimal level may take a bit of experimentation. Decreasing the precision of the points as well as the number of points through generalization, will lead to degradation of the polygon. However, after a bit of experimentation, an optimal level of generalization can be found, where the accuracy of the polygon is visually acceptable, and the performance of the GIS is optimal. </member>
> +      </simplelist></para>
> +    <para>For polygons, we need to make the boundary lines less detailed by removing some of the line points. One possible method is the use of <ulink url="http://www.mapshaper.com/test/demo.html";>MapShaper</ulink>   which is an online tool which can be used to generalize geographical data. To use MapShaper, simply upload your shapefile to the site. Then, at the center bottom you see a slider that starts at 0%. It is usually acceptable to drag it up to about 80%. In the left menu you can check &quot;show original lines&quot; to compare the result and you may want to give a different simplification method a try. When you are happy with the result, click &quot;export&quot; in the top right corner. Then check the first of the four options called &quot;Shapefile - polygons&quot;, click &quot;create&quot; and wait for the download buttons to appear. Now, download the two files to your local computer (being sure to rename the file so that you do not overwrite your existing, original data). Move on to the next step with your new simplified shapefile.
>     </para>
>     <para>Step 2 - Convert the shapefile to GML</para>
>     <para>
> -      The recommended tool for geographical format conversions is called &quot;ogr2ogr&quot;. This should be available for most Linux distros (&quot;sudo apt-get install gdal-bin&quot;). For Windows, go to http://fwtools.maptools.org/ and download &quot;FWTools&quot;, install it and open up the FWTools command shell. During the format conversion we also want to ensure that the output has the correct coordinate projection (called EPSG:4326 with geographic longitude and latitude). For a more detailed reference of geographic coordinates, please refer to this <ulink url="http://www.epsg-registry.org/";>site</ulink>.  If you have already reprojected the geographic data to the geographic latitude/longitude (EPSG:4326) system, there is no need to explicitly define the output coordinate system, assuming that <command>ogr2ogr</command> can determine the input spatial reference system. You can determine the spatial reference system by executing the following command.</para>
> +      The recommended tool for geographical format conversions is called &quot;ogr2ogr&quot;. This should be available for most Linux distributions (&quot;<command>sudo apt-get install gdal-bin&quot;</command>). For Windows, go to <ulink url="http://fwtools.maptools.org/";>http://fwtools.maptools.org/ </ulink>and download &quot;FWTools&quot;, install it and open up the FWTools command shell. During the format conversion we also want to ensure that the output has the correct coordinate projection (called EPSG:4326 with geographic longitude and latitude). For a more detailed reference of geographic coordinates, please refer to this <ulink url="http://www.epsg-registry.org/";>site</ulink>.  If you have already reprojected the geographic data to the geographic latitude/longitude (EPSG:4326) system, there is no need to explicitly define the output coordinate system, assuming that <command>ogr2ogr</command> can determine the input spatial reference system. You can determine the spatial reference system by executing the following command.</para>
>     <para><programlisting><userinput>ogrinfo -al -so filename.shp</userinput></programlisting></para>
>     <para>Assuming that the projection is reported to be EPSG:27700 by <command>ogrinfo</command>, we can transform it to EPSG:4326 by executing the following command.<programlisting><userinput> ogr2ogr -s_srs EPSG:27700 -t_srs EPSG:4326 -f GML filename.gml filename.shp </userinput></programlisting></para>
>     <para>If the geographic data is already in EPSG:4326, you can simply transform the shapefile to GML by executing the following command. </para>
> @@ -41,11 +44,11 @@
>       Go to Services -&gt; Import-Export, select &quot;Preview&quot;, select the GML file and click &quot;Import&quot;. Look for new/updated organisation units. Our intention is to add coordinates to already existing organisation units in the database, so we want as many updates as possible and 0 new. Those listed as new will be created as root units and mess up the organisation unit trees in DHIS 2. If any listed as new, click the number and the organisation units in question will appear in the list below. If there are any slight misspellings compared to the organisation unit names in the database - fix them and do the preview again. Otherwise, click the &quot;discard all&quot; button below the list and then the &quot;Import all&quot; button above the list.
>     </para>
>     <para>
> -      If the import process completes successfully, you are good to go. If not, check the log for hints and look for common errors such as:
> +      If the import process completes successfully, you should now be able to utilize the geographical data in the DHIS2 GIS. If not, check the log for hints and look for common errors such as:
>     </para>
>     <para>- Name duplicates in the GML file. The name column in the database is unique and does not accept two organisation units with the same name.</para>
>     <para>- The &quot;shortname&quot; column in the organisationunit table in your database has a too small varchar definition. Increase it to 100.</para>
> -    <para>- Special name characters in the GML file. Rename or remove.</para>
> +    <para>- Special name characters in the GML file. Be sure to convert these to appropirate XML equivalents or escape sequences.</para>
>   </section>
>   <section>
>     <title>Administering the GIS module</title>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~dhis2-devs
> Post to     : dhis2-devs@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~dhis2-devs
> More help   : https://help.launchpad.net/ListHelp
>