Install Docker Desktop

In order to install the modular openIMIS using Docker, you first need to install Docker Desktop. Please download and install the platform from the Docker Desktop website. Make sure to use Windows container (Docker image operating system "windows" cannot be used on this platform).

Download openIMIS Docker script

Download and unzip the release from Github openimis-dist_dkr repository into a new folder.

First startup

The first startup is special since it will create the necessary docker images and containers to run openIMIS. To build necessary, docker images, docker-compose relies on local docker files. In order to build these images, you need to clone, next to openimis-dist_dkr/ the following Github repository:

• openimis-db_dkr (not for production)

• openimis-be_py

• openimis-fe_js

• openimis-gateway_dkr

Or clone the 5 folders with git:

git clone https://github.com/openimis/openimis-dist_dkr.git
git clone https://github.com/openimis/openimis-db_dkr.git
git clone https://github.com/openimis/openimis-be_py.git
git clone https://github.com/openimis/openimis-fe_js.git
git clone https://github.com/openimis/openimis-gateway_dkr.git

From within openimis-dist_dkr/windows directory:

• create a .env file, providing the following variables:

 DB_SQL_SCRIPT=<URL pointing to the SQL script>
 ACCEPT_EULA=<must put Y but it means you accept Microsoft EULA for the MSSQL database container>
 DB_HOST=database
 DB_PORT=1433
 DB_NAME=<your database name, imis if you use the demo docker 'db' service>
 DB_USER=<your database user, sa if you use the demo docker 'db' service >
 DB_PASSWORD=<your database password, generate one if you use the demo docker 'db' service>
 NEW_OPENIMIS_HOST=<(sub)domain under which the (new) openIMIS will be served (e.g. openimis.domaine) >
 LEGACY_OPENIMIS_HOST=frontend

• on the same level as openimis-dist_dkr directory, create a new conf directory (this is used for storing instance-specific configuration that will be reused if the docker containers are restarted)

• if you use the demo docker 'db' service (not for production!):

  • choose the SQL script to create/restore the database in DB_SQL_SCRIPT. Reference models are provided in the database installation tutorial. Example:

    • Empty database: https://raw.githubusercontent.com/openimis/database_ms_sqlserver/v1.4.2/Empty%20databases/openIMIS_ONLINE.sql 

    • Demo database: https://raw.githubusercontent.com/openimis/database_ms_sqlserver/v1.4.2/Demo%20database/openIMIS_demo_ONLINE.sql

  • accept the Microsoft EULA for the MSSQL database container (set the value of ACCEPT_EULA to Y)

  • build and start the database docker image: docker-compose up db

  • create the openIMIS database into the container:

    • docker container ls and spot the line (CONTAINER ID) with openimis-db IMAGE name

    • docker exec <CONTAINER ID> /create_database.bat

  • create the database user

    • docker exec <CONTAINER ID> /create_user_db.bat

• build and start the gateway, frontend and backend docker image: docker-compose up (note: at each start, openIMIS will apply the necessary database migrations to update the database scheme)

• If connecting to a brand new database, register your openIMIS superuser:

  • list running containers and spot the backend: docker container ls (the gateway should be named openimis-backend)

  • connect to the gateway: docker exec -it <CONTAINER ID> /bin/bash (bash and not sh this time)

  • you should be in /openimis-be/openIMIS directory, if not, just cd /openimis-be/openIMIS)

  • register your openIMIS superuser: python manage.py createsuperuser (and follow instructions)

stop/start

From within openimis-dist_dkr/windows directory:

• To stop all docker containers: docker-compose stop 

• To (re-)start all docker containers: docker-compose start