Merge pull request #64 from openimis/feature/improve_installation

Simplify installation with docker

.env.example

@@ -10,21 +10,21 @@ HTTP_PORT=80
 HTTPS_PORT=443
 
 # Uncomment the line below to intiate the database with the DEMO dataset, it will create an empty openIMIS database otherwise
-#INIT_MODE=demo
+#DEMO_DATASET=true
 DB_PASSWORD=IMISuserP@s
 DB_USER=IMISuser
 DB_NAME=IMIS
-#MSSQL configuration comment DB_ENGINE=django.db.backends.postgresql and DB_PORT=5432,  uncomment DB_ENGINE=mssql and ACCEPT_EULA (= y if you accept MS EULA) DB_PORT=1433
+# If MSSQL DB required DB_DEFAULT=postgresql and DB_PORT=5432,  uncomment DB_DEFAULT=mssql, DB_PORT=1433 and ACCEPT_EULA (= y if you accept MS EULA)
 # database parameters
 DB_HOST=db
-# msssql port
-#DB_PORT=1433
-# psql port
+# Use PostgreSQL DB
+DB_DEFAULT=postgresql
+# PostgreSQL port
 DB_PORT=5432
-#psql engine
-DB_ENGINE=django.db.backends.postgresql
-#mssql engine
-#DB_ENGINE=mssql
+# Use MSSQL DB
+#DB_DEFAULT=mssql
+# MSSQL port
+#DB_PORT=1433
 #ACCEPT_EULA= <y if you accept MS EULA >
 GATEWAY_PORT_S=443
 # site root for backend

.gitignore

@@ -1,2 +1,4 @@
 **/.env
 openimis_env/*
+data/*
+openimis-dist_dkr.code-workspace

README.md

@@ -1,81 +1,80 @@
 # openIMIS dockerized
 
- This repository provides a dockerized openIMIS (all components) as a quick setup , testing or demoing.
+ This repository provides a Docker package for openIMIS that includes all components to quickly setup, test and demo the solution.
 
 
  Please look for further instructions on the openIMIS Wiki: https://openimis.atlassian.net/wiki/spaces/OP/pages/963182705/MO1.1+Install+the+modular+openIMIS+using+Docker
 
 
- The docker-compose currently contains the openIMIS database, backend + worker, frontend, and third parties components (lightning, opensearch, rabitMQ ... ).
+ The openIMIS docker compose currently includes the database, backend and worker, frontend, and third parties components (Lightning, OpenSearch, RabbitMQ, etc.).
 
 
-In case of troubles, please consult/contact our service desk via our [ticketing site](https://openimis.atlassian.net/servicedesk/customer).
+In case of troubles, please contact our service desk via our [ticketing platform](https://openimis.atlassian.net/servicedesk/customer).
 
-# Prerequisit
-- Docker installed
+## Prerequisite
 
+* Docker installed
 
-# fast lane
+## Fast lane
 
- You can use the script `deploy_openimis.sh`to initialize all components
+You can use the script `deploy_openimis.sh` to initialise all components (uses PostgreSQL DB).
 
-# First startup
+## First startup
 
-* create a `.env` file, use `.env.example` as starting point (respectivement for `.env.lightning`, `.env.openSearch`)
-* chose database vendor: the default is psql but you can edit the docker-compose.yml and change `docker-compose-psql.yml` to  `docker-compose-mssql.yml`
+* Copy `.env.example` to `.env` and make the necessary adjustments.
+* Choose a database default system to use. The default is PostgreSQL (`DB_DEFAULT=postgresql`, `DB_PORT=5432`), but you can also use MSSQL (`DB_DEFAULT=mssql`, `DB_PORT=1433`, `ACCEPT_EULA=Y`). 
+* Uncomment the line `DEMO_DATASET=true` in `.env` to initialise the database with the DEMO dataset. If you leave it commented, an empty openIMIS database will be created.
 
+## OpenFN/Lightning setup 
 
-## configure the gateway (optionnal)
-
-* uncomment the volume in the frontend config
-* make modification in openimis.conf
+If the implementation involves managing the social protection workflow/import, then OpenFN/Lightning must be set up with the following steps:
 
+* Copy `.env.lightning.example` to `.env.lightning` and make the necessary adjustments.
+* Create the `lightning_dev` database in the database container.
+* Build the container: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml build lightning`.
+* Run migrations: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning mix ecto.migrate`.
+* Set up the IMIS demo: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning ./imisSetup.sh`.
+* Start the service: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml up lightning`.
 
-## main database initialisation
-
-Include the line INIT_MODE=demo in .env or uncomment it in case it has been copied from .env.example copied to intiate the database with the DEMO dataset, it will create an empty openIMIS database otherwise
-
-## OpenFN/Lightning setup ( manage social protection workflow/import )
+## OpenSearch/OpenSearch Dashboards setup 
 
-  * Copy `.env.lightning.example` to `.env.lightning` and make adjustments 
-  * Create `lightning_dev` database in db container 
-  * Run container build `docker compose -f docker-compose.yml -f docker-compose.lightning.yml build lightning`
-  * Run migrations `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning mix ecto.migrate`
-  * Run imis demo setup `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning ./imisSetup.sh`
-  * Run service `docker compose -f docker-compose.yml -f docker-compose.lightning.yml up lightning`
+Both OpenSearch and OpenSearch Dashboards are not by default enabled in dockerized instance. To make them work, it's required to: 
 
-## OpenSearch/OpenSearch Dashboards setup 
-Both OpenSearch and OpenSearch Dashboards are not by default enabled in dockerized instance. To make them work it's required to: 
   * Copy `.env.openSearch.example` to `.env.openSearch` and make adjustments
   * Run container build `docker compose -f docker-compose.yml -f docker-compose.openSearch.yml build opensearch opensearch-dashboards nginx`
   * Run service `docker compose -f docker-compose.yml -f docker-compose.openSearch.yml up opensearch opensearch-dashboards nginx`
-This build provides also additional nginx proxy server in order to handle openSearch Dashboard application on frontend level. 
 
-To run on a Dockerized instance (database, backend, and frontend of openIMIS), please follow the steps below:
-  * Add a value for the OPENSEARCH_BASIC_TOKEN in the environment (env) file. This should be based on the admin and password credentials for openSearch.
-  * In the .env file in openimis-fe_js, use the following environment variable: `ENV OPENSEARCH_PROXY_ROOT="opensearch"`.
+This build provides also additional nginx proxy server in order to handle OpenSearch Dashboard application on frontend level. 
+
+To run on a dockerized instance of openIMIS (database, backend, and frontend), including OpenSearch, please follow the steps below:
+
+  * Add a value for the OPENSEARCH_BASIC_TOKEN in the environment (`.env`) file. This should be based on the admin and password credentials for OpenSearch.
+  * In the `.env` file in openimis-fe_js, use the following environment variable: `ENV OPENSEARCH_PROXY_ROOT="opensearch"`.
   * Run the backend and frontend services.
 
-# stop /start
+## Run openIMIS with Docker
 
-To stop all docker containers: `docker-compose  stop`
-To (re-)start all docker containers: `docker-compose  start` 
+You can run the docker compose commands from within `openimis-dist_dkr` folder.
 
-# pull new images
+### Pull new images
 
 To pull new images or images update `docker-compose pull` 
 
+### Start / Stop
+
+* To start or restart all docker containers: `docker-compose start` 
+* To stop all docker containers: `docker-compose stop`
 
-# create lets encrypt certs
+## Create LetsEncrypt certificates
 
-use the certbot docker compose file
+Use the certbot docker compose file. 
 
-export DOMAIN first
+`export DOMAIN [domain_name]`
 
+### Dry run 
 
-## dry run 
-docker-compose run --rm --entrypoint "  certbot certonly --webroot -w /var/www/certbot  --staging  --register-unsafely-without-email  -d  ${DOMAIN}    --rsa-key-size 2048     --agree-tos     --force-renewal" certbot
+`docker-compose run --rm --entrypoint "  certbot certonly --webroot -w /var/www/certbot  --staging  --register-unsafely-without-email  -d  ${DOMAIN}    --rsa-key-size 2048     --agree-tos     --force-renewal" certbot`
 
-## actual setup
+### Actual setup
 
-docker-compose run --rm --entrypoint "  certbot certonly --webroot -w /var/www/certbot    --register-unsafely-without-email  -d  ${DOMAIN}    --rsa-key-size 2048     --agree-tos     --force-renewal" certbot
+`docker-compose run --rm --entrypoint "  certbot certonly --webroot -w /var/www/certbot    --register-unsafely-without-email  -d  ${DOMAIN}    --rsa-key-size 2048     --agree-tos     --force-renewal" certbot`

deploy_openimis.sh

@@ -26,10 +26,10 @@ docker compose  run -e  PGPASSWORD=${POSTGRES_PASSWORD} --rm db createdb -h db -
 set -e
 docker compose  run --rm  web mix ecto.migrate
 docker compose  run --rm web mix run imisSetupScripts/imisSetup.exs
-#TODO init opensearch dashboard with API/ manage command
+#TODO init OpenSearch dashboard with API/ manage command
 echo "connect to https://{DOMAIN}"
 echo "then go to https://{DOMAIN}/opensearch"
-echo "then go in manage / saved object / import to import the openSearch dashboard"
+echo "then go in manage / saved object / import to import the OpenSearch dashboard"
 touch '.init.lock' 
 fi
 docker compose up -d

docker-compose.base.yml

@@ -2,6 +2,7 @@
 x-api: &default-api
   image: ghcr.io/openimis/openimis-be:${BE_TAG:-develop}
   environment:
+    - DB_DEFAULT=${DB_DEFAULT:-postgresql}
     - DB_HOST=${DB_HOST}
     - DB_PORT=${DB_PORT}
     - DB_NAME=${DB_NAME}
@@ -10,7 +11,6 @@ x-api: &default-api
     - SITE_ROOT=api
     - SITE_URL=${DOMAIN}
     - CELERY_BROKER_URL=amqp://rabbitmq
-    - DB_ENGINE=${DB_ENGINE}
     - MODE=${MODE:-Prod}
   volumes:
     - photos:/openimis-be/openIMIS/images/insurees
@@ -41,7 +41,7 @@ services:
     volumes:
       - ./data/certbot/conf:/etc/letsencrypt
       - ./data/certbot/www:/var/www/certbot
-      # uncomment to use custom openimis.conf
+      # comment the following line if you are using your own gateway
       - ./conf/nginx:/conf/
   backend:
     <<: *default-api

docker-compose.mssql.yml

@@ -10,7 +10,8 @@ services:
       - DB_NAME=${DB_NAME}
       - DB_USER=${DB_USER}
       - ACCEPT_EULA=${ACCEPT_EULA}
-      - INIT_MODE=${INIT_MODE}
+      - DEMO_DATASET=${DEMO_DATASET}
+      - DB_ENGINE=mssql
     healthcheck:
       test: "bash /app/healthcheck.sh"
       interval: 10s

docker-compose.psql.yml → docker-compose.postgresql.yml

@@ -7,7 +7,8 @@ services:
       - POSTGRES_PASSWORD=${DB_PASSWORD}
       - POSTGRES_DB=${DB_NAME}
       - POSTGRES_USER=${DB_USER}
-      - INIT_MODE=${INIT_MODE}
+      - DEMO_DATASET=${DEMO_DATASET}
+      - DB_ENGINE=django.db.backends.postgresql
     healthcheck:
       test: pg_isready -U ${DB_USER} -d ${DB_NAME}
       interval: 10s

docker-compose.yml

@@ -1,5 +1,5 @@
 include:
-  - path: docker-compose.psql.yml
+  - path: docker-compose.${DB_DEFAULT:-postgresql}.yml
     env_file: .env
   - path: docker-compose.base.yml
     env_file: .env