0. Prerequisite

To install openIMIS using Docker, you first need first to install Docker on your computer/server. Please visit https://docs.docker.com/get-docker/ website to download and install the version that matches your OS.

1. Download openIMIS Docker script

Clone the https://github.com/openimis/openimis-

dist_dkr on your machine into a new folder.

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

2. First startup

• Create the .env file from the .env.example and configure the environment variables according to the comments in the file. By default, PostgreSQL database is used.

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

• if 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 Build and start the docker compose: docker-compose up -d

  • If you prefer to use Microsoft SQL Server database: docker-compose -f docker-compose-mssql.yml up -d

    • Accept the Microsoft EULA (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)

• • • , not required for PGSQL)

3. SSL certificate / https

there is a docker-compose that support let’s encrypt certificates

first export NEW_OPENIMIS_HOST ,

dry run

docker-compose run --rm --entrypoint " certbot certonly --webroot -w /var/www/certbot --staging --register-unsafely-without-email -d ${NEW_OPENIMIS_HOST} --rsa-key-size 2048 --agree-tos --force-renewal" certbot

actual setup

docker-compose run --rm --entrypoint " certbot certonly --webroot -w /var/www/certbot --register-unsafely-without-email -d ${NEW_OPENIMIS_HOST} --rsa-key-size 2048 --agree-tos --force-renewal" certbot

4. Actions

From within openimis-dist_dkr/windows directory:

• To stop all docker containers: docker-compose stop 

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

• To pull new images or images update `docker-compose pull`