Skip to content

Mukau Installation Instructions Overview

Jump to bottom
Grace Amondi edited this page May 10, 2021 · 10 revisions

This section describes the steps required to install Mukau components in a single run. Mukau is installed with Docker and vasrious images, containers and volumes are created. Various Mukau components can be installed as standalone applications and updated and built seperately.

Mukau github repository represents the entrypoint to all Mukau components and set’s up dockerized containers that run them e.g CMS, CMS PostgreSQL database, nginx and redis.

Required Software

In order to install Mukau, the following softwares need to be installed first:

Mukau requires docker in order to function. Follow these instructions to install docker on Windows, and these instructions to install docker on Mac OS. If you are running Linux, follow the instructions on this page that are appropriate for the Linux distribution you are using.

Mukau Deployment with Docker Compose

Table of Contents

Installation

There are two ways to mukau:

A. Build all images locally (Quick Install)

B. Pull built images from a private registry (Developer friendly)

OPTION A. Build all images locally (Quick Install)

In this scenario, you are required to clone the independent mukau components as submodules i.e mukau-cms and mukau-mapserver at the root of the project then use docker-compose-dev.yml to build and run the docker images and containers. To install mukau this way, follow the instructions below:

1. Clone repo

To clone mukau together with its submodules, execute the commands below:

git clone https://github.com/icpac-igad/mukau.git

cd mukau

git submodule init

git submodule update

2. Create a .env file

This file contains contents similar to .env.sample file. Provide necessary variables. At the root of mukau execute,

cp .env.sample .env
Variable Description
PROTOCOL e.g http, https
HOST_IP IP address eg. 127.0.0.1
POSTGRES_USER_CMS cms postgres user
POSTGRES_HOST_CMS host for cms postgres
POSTGRES_PASSWORD_CMS password for the postgres cms database
POSTGRES_PORT_CMS cms postgres port
POSTGRES_DB_MS The mapserver database name
POSTGRES_USER_MS mapserver postgres user
POSTGRES_PASSWORD_MS password for the postgres mapserver user
POSTGRES_PORT_MS mapserver postgres port
GIS_USER gis
GIS_USER_PASS password for the gis user
MAP_USER mapuser
MAP_USER_PASS password for the map user
MAPSERVER_PORT port mukua mapserver will be running on
CMS_PORT port mukua mapserver will be running on
WEB_IMAGE_URI The web production image to use. This should be the URI to the image on a local or remote private registry, with the version tag e.g localhost:5000/mukau-cms:1.0
MAPSERVER_IMAGE_URI The mapserver production image to use. This should be the URI to the image on a local or remote private registry, with the version tag e.g localhost:5000/mukau-mapserver:1.0

You can view the available tags for mukau-cms image at https://eahazardswatch.icpac.net/v2/cms/tags/list. This requires authentication.

3. Create a .env.prod.db file

At the root of mukau execute,

cp .env.prod.db.sample .env.prod.db

The .env.prod.db file is utilized by db container in the docker-compose.yml file and expects the following Environmental Variables. N.B These variables should match with those specified in the env.prod file

POSTGRES_DB=>

POSTGRES_USER=>

POSTGRES_PASSWORD=>

4. Mapserver Database container Setup - mukau_mapserver_db

This is the container that runs the mukau postgresql database. This container does not need a Dockerfile since it uses the official postgis/postgis:12-master image that already has Postgresql + Postgis installed. All the files required by this container will be inside the /database directory.

A sql folder needs to be created inside the /database/initdb/ folder. This directory will contain a list of scripts and sql files to initialize the mukau database with users and data.

These files must be downloaded (https://edo.jrc.ec.europa.eu/documents/mukau/pgsql_data.tar) and copied into this sql/ folder like so:

  • cms_tables_a
  • cms_tables_b
  • gis_tables
  • map_tables

Inside the folder mukau-mapserver/database/initdb/ there are two scripts as described below:

  • 01.init.sh - Which will create the necessary database users and privileges
  • 02.database_data_population.sh - Which will populate the database using the sql files in the mukau-mapserver/database/initdb/sql folder

Ensure your directory structure appears as below:

.
└───mukau-mapserver
│   └───database
│       └───initdb
│           └───sql
└───nginx
└───mukau-cms
└───database

5. Executable file

To make the database init file execute as a program, run:

chmod +x mukau-mapserver/database/initdb/01.init.sh

6. Build Docker Images

To build docker images for both mapserver and cms, execute:

sudo docker-compose -f docker-compose-dev.yml build

7. Start Docker Compose (in the background)

Execute the command below and give it time to complete.

sudo docker-compose -f docker-compose-dev.yml up -d

To view the status of the database, run:

sudo docker logs mukau_cms_db -f

To view the status of the web app, run:

sudo docker logs mukau_cms_web -f

8. Migrate CMS Models (Database Tables)

sudo docker-compose exec mukau_cms_web web python manage.py migrate

9. Populate CMS Database with fixtures

sudo docker-compose exec mukau_cms_web python manage.py loaddata datadump.json

The CMS should now be running at http:<ip_address>:<CMS_PORT>

The CMS Admin interface can be accessed at http:<ip_address>:<CMS_PORT>/admin. Default credentials are:

Username: admin

Password: mukau@cms

The Mapserver should now be running at http:<ip_address>:<MAPSERVER_PORT>

To test whether Mapserver was run successfully, the url below should return an image:

http://<ip_address>:<MAPSERVER_PORT>/mukau/php/gis/mswms.php?map=mukau_w_mf&LAYERS=SPI%201%20dd&FORMAT=image%2Fpng&TRANSPARENT=TRUE&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&SELECTED_YEAR=2019&SELECTED_MONTH=08&SELECTED_TIMESCALE=03&SRS=EPSG%3A4326&BBOX=15,25,30,40&WIDTH=256&HEIGHT=256

OPTION B. Pull built images from a private registry (Developer friendly)

In this scenario, you only need to clone the repository without the submodules (mukau independent components). The mukau component images are built independetly and their tags mirrored to a remote on a private registry. The remote images from the private registries are then configured in the .env file and called within docker-compose.yml

1. Clone repo

To clone mukau repository, execute the commands below:

git clone https://github.com/icpac-igad/mukau.git

cd mukau

2. Create a .env file

This file contains contents similar to .env.sample file. Provide necessary variables. At the root of mukau execute,

cp .env.sample .env
Variable Description
PROTOCOL e.g http, https
HOST_IP IP address eg. 127.0.0.1
POSTGRES_USER_CMS cms postgres user
POSTGRES_HOST_CMS host for cms postgres
POSTGRES_PASSWORD_CMS password for the postgres cms database
POSTGRES_PORT_CMS cms postgres port
POSTGRES_DB_MS The mapserver database name
POSTGRES_USER_MS mapserver postgres user
POSTGRES_PASSWORD_MS password for the postgres mapserver user
POSTGRES_PORT_MS mapserver postgres port
GIS_USER gis
GIS_USER_PASS password for the gis user
MAP_USER mapuser
MAP_USER_PASS password for the map user
MAPSERVER_PORT port mukua mapserver will be running on
CMS_PORT port mukua mapserver will be running on
WEB_IMAGE_URI The web production image to use. This should be the URI to the image on a local or remote private registry, with the version tag e.g localhost:5000/mukau-cms:1.0
MAPSERVER_IMAGE_URI The mapserver production image to use. This should be the URI to the image on a local or remote private registry, with the version tag e.g localhost:5000/mukau-mapserver:1.0

You can view the available tags for mukau-cms image at https://eahazardswatch.icpac.net/v2/cms/tags/list. This requires authentication.

3. Create a .env.prod.db file

At the root of mukau execute,

cp .env.prod.db.sample .env.prod.db

The .env.prod.db file is utilized by db container in the docker-compose.yml file and expects the following Environmental Variables. N.B These variables should match with those specified in the env.prod file

POSTGRES_DB=>

POSTGRES_USER=>

POSTGRES_PASSWORD=>

4. Mapserver Database container Setup - mukau_mapserver_db

This is the container that runs the mukau postgresql database. This container does not need a Dockerfile since it uses the official postgis/postgis:12-master image that already has Postgresql + Postgis installed. All the files required by this container will be inside the /database directory.

A sql folder needs to be created inside the /database/initdb/ folder. This directory will contain a list of scripts and sql files to initialize the mukau database with users and data.

These files must be downloaded (https://edo.jrc.ec.europa.eu/documents/mukau/pgsql_data.tar) and copied into this sql/ folder like so:

  • cms_tables_a
  • cms_tables_b
  • gis_tables
  • map_tables

Inside the folder /database/initdb/ there are two scripts as described below:

  • 01.init.sh - Which will create the necessary database users and privileges
  • 02.database_data_population.sh - Which will populate the database using the sql files in the /database/initdb/sql folder

Ensure your directory structure appears as below:

.
└───database
│   └───initdb
│       └───sql
└───nginx

5. Pull New Image

Before pulling the new image in the production server, first ensure that within the .env file the tag version matches with the one pushed last i.e in this case:

WEB_IMAGE_URI=eahazardswatch.icpac.net/mukau-cms:1.2

MAPSERVER_IMAGE_URI=eahazardswatch.icpac.net/mukau-mapserver:1.2

Next, login to the eahazardswatch.icpac.net registry, execute the command below and provide appropriate credentials.

sudo docker login eahazardswatch.icpac.net

To get the latest changes pushed to the tag specified in the WEB_IMAGE_URI and MAPSERVER_IMAGE_URI tag version, run:

sudo docker-compose pull

N.B: You can also set WEB_IMAGE_URI and MAPSERVER_IMAGE_URI to point to a local private registry if you are working on the same machine that contains the locally built image e.g

WEB_IMAGE_URI=localhost:5000/mukau-cms:1.2

MAPSERVER_IMAGE_URI=localhost:5000/mukau-mapserver:1.2

6. Start Docker Compose (in the background)

Execute the command below and give it time to complete.

sudo docker-compose up -d

To view the status of the database, run:

sudo docker logs mukau_cms_db -f

To view the status of the web app, run:

sudo docker logs mukau_cms_web -f

7. Migrate CMS Models (Database Tables)

sudo docker-compose exec mukau_cms_web web python manage.py migrate

8. Populate CMS Database with fixtures

sudo docker-compose exec mukau_cms_web python manage.py loaddata datadump.json

The application should now be running at http:<ip_address>:<CMS_PORT>

The CMS Admin interface can be accessed at http:<ip_address>:<CMS_PORT>/admin. Default credentials are:

Username: admin

Password: mukau@cms

The Mapserver should now be running at http:<ip_address>:<MAPSERVER_PORT>

To test whether Mapserver was run successfully, the url below should return an image:

http://<ip_address>:<MAPSERVER_PORT>/mukau/php/gis/mswms.php?map=mukau_w_mf&LAYERS=SPI%201%20dd&FORMAT=image%2Fpng&TRANSPARENT=TRUE&SERVICE=WMS&VERSION=1.1.1&REQUEST=GetMap&STYLES=&SELECTED_YEAR=2019&SELECTED_MONTH=08&SELECTED_TIMESCALE=03&SRS=EPSG%3A4326&BBOX=15,25,30,40&WIDTH=256&HEIGHT=256

Other commands

Making Updates

To update the application, for example after changing the WEB_IMAGE_URI variable in .env file just run again:

sudo docker-compose pull

then

sudo docker-compose up

Stop and Clean Docker

To stop and remove everything including volumes run (reset). NOTE: This will result in lose of any data save to the database

sudo docker-compose down --volumes

Access database on cmd

docker exec -it <DB_CONTAINER> psql -U <DB_USER> <DB_NAME>

Backup postgres table

sudo docker exec -it <DB_CONTAINER> pg_dump -U <DB_USER> -t <DB_TABLE> <DB_NAME> > 'path_to_ouput.sql'

Backup postgres database

docker exec -t <DB_CONTAINER> pg_dumpall -c -U <DB_USER> | gzip > ./tmp/dump_$(date +"%Y-%m-%d_%H_%M_%S").gz

Restore database backups

gunzip < your_dump.sql.gz | docker exec -i <DB_CONTAINER> psql -U <DB_USER> -d <DB_NAME>

Access Docker Containers

Access to the running container (mukau-web or any container name, the one defined in docker-compose.yml)

docker exec -it <CONTAINER> bash

Sections

Home

Clone this wiki locally