Introduction
We have seen in the previous section that Docker packaging is managing all components of the modular openIMIS. If you wish to install the modular openIMIS without Docker, you will have to install separately the backend, the frontend and the gateway (and other optional modules)
Installing openIMIS directly is a tradeoff: it is more complex to get running, has more components to update and monitor but it is also much more flexible for low-bandwidth environments where downloading large docker images is an issue.
TO DO
This guide is still missing:
configuration of the images folder
Database
This guide does not cover the database setup. Both PostgreSQL and Microsoft SQL Server are supported here.
Minimal Linux setup
This takes Ubuntu as example but can easily be adapted to most other distributions.
mkdir oi cd oi sudo apt install openssh-server curl sudo apt install git python3-venv python3-wheel libpq-dev python3-dev gcc g++ make
If you are going to use the Microsoft database, install the corresponding driver:
Here is the version for Ubuntu until 2021:
if ! [[ "16.04 18.04 20.04 21.04 21.10" == *"$(lsb_release -rs)"* ]]; then echo "Ubuntu $(lsb_release -rs) is not currently supported."; exit; fi sudo su curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add - curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list > /etc/apt/sources.list.d/mssql-release.list exit sudo apt-get update sudo ACCEPT_EULA=Y apt-get install -y msodbcsql17 # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y apt-get install -y mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo apt-get install -y unixodbc-dev
Now, let’s create a Python virtual environment. This is not mandatory but strongly advised to avoid interactions between Python applications:
cd ~/oi # if you are not in this folder anymore python3 -mvenv venv source venv/bin/activate
Fetching and installing openIMIS apps
We will fetch the main application components, frontend and backend:
git clone https://github.com/openimis/openimis-be_py.git git clone https://github.com/openimis/openimis-fe_js.git
Configure the backend
cd openimis-be_py # if you are not going to work from the main branch (latest release): git checkout develop # You might need here to adapt the requirements.txt file. If pandas fails to install below, change to pandas==1.4.2
Adapt openimis.json
to suit your needs of openIMIS modules to deploy.
pip install -r requirements.txt python modules-requirements.py > modules-requirements.txt pip install -r modules-requirements.txt
Now, you will need to create a .env file with the main parameters of the backend:
DB_HOST=mssql-host-server DB_PORT=1433 DB_NAME=database-name DB_USER=database-user DB_PASSWORD=database-password DB_ENGINE=mssql INSUREE_NUMBER_LENGTH=10 INSUREE_NUMBER_MODULE_ROOT=7 SITE_ROOT=api MASTER_PASS=')(#$1HsD'
Now, we just need to generate the static files:
cd openIMIS ./manage.py collectstatic
Then, try to run the backend server:
cd ~/oi/openimis-be_py/openIMIS # If not already there from last step ./manage.py runserver
If the server takes a really long time to start, the database connection parameters are probably wrong and it is waiting for a database timeout to print an error.
Configure the automated restart
For systemd, create a file /lib/systemd/system/openimis.service
:
[Unit] Description=openIMIS backend After=network-online.target [Service] WorkingDirectory=/home/openimis/oi/openimis-be_py/openIMIS/ ExecStart=/home/openimis/oi/venv/bin/python manage.py runserver Restart=always RestartSec=15s KillMode=process TimeoutSec=infinity User=openimis Group=openimis [Install] WantedBy=multi-user.target
Be careful to adapt the 4 occurences of the “openimis” if your username is different:
two /home/openimis
User/Group
Start the server manually:
sudo systemctl start openimis.service
To make it start automatically at boot:
sudo systemctl enable openimis.service
If the service fails to start, check the logs with:
sudo journalctl -u openimis.service
Configure the frontend
First step is to install node.js. OpenIMIS versions 1.2 to 1.5 are using node 16. The node installation instructions are https://github.com/nodesource/distributions/blob/master/README.md#deb but a generic solution like nvm is also a good option.
For Ubuntu with stock Node:
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash - sudo apt-get install -y nodejs
Then, install yarn:
curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list sudo apt-get update && sudo apt-get install yarn
Go the frontend folder:
cd ~/oi/openimis-fe_js
You can now edit the openimis.json for the frontend to select the components to install.
When done, load the configuration:
yarn load-config yarn install yarn build yarn global add serve
If building yarn fails with an out of memory error, use export GENERATE_SOURCEMAP=false
At this stage, you should be able to run the app in dev mode with yarn start
. This is not recommended for production !!
So let’s build a static bundle and deploy it in nginx’s path:
yarn build # If not already done above sudo apt install nginx # We'll set it up below, so if you didn't install it already... sudo mkdir /var/www/html/front/ sudo chown $USER /var/www/html/front/ cp -r build/* /var/www/html/front/
Configure nginx (gateway/reverse proxy)
The docker-compose version uses an openresty image that only relays, here we will be deploying a regular nginx pointing to the static site.
Nginx will also be handling the TLS (HTTPS) with Letsencrypt.
sudo apt install nginx sudo rm /etc/nginx/sites-enabled/default # remove the default site (it’s just a link, don’t worry) sudo vi /etc/nginx/sites-available/openimis.conf sudo ln -s /etc/nginx/sites-available/openimis.conf /etc/nginx/sites-enabled/openimis.conf
Here is a sample configuration, to be tuned to your setup. The SSL parts are commented out, they will be updated by Letsencrypt’s certbot:
upstream docker-backend { server localhost:8000; } upstream docker-frontend { server localhost:3000; } upstream restapi { server localhost:8080; } server { server_name example.openimis.org; # Don't forget to edit the URL # return 301 https://$host$request_uri; #} #server { # # listen 443 ssl; # server_name example.openimis.org; # ## ssl_certificate /etc/ssl/certs/example.openimis.org.crt; ## ssl_certificate_key /etc/ssl/private/example.openimis.org.key; client_max_body_size 100M; location /.well-known { root /var/www/html; } location /LegacyHome { return 204; } location /keepLegacyAlive { return 204; } location / { return 301 /front/; } location /home { return 301 /front/; } location /Home.aspx { return 301 /front/; } location ~/front/(.*) { root /var/www/html; try_files $uri $uri/ /front/index.html; #error_page 404 $scheme://$host/front/; } location /iapi/ { proxy_pass http://docker-backend/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Host $server_name; } location /api/ { proxy_pass http://docker-backend/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Host $server_name; } location /rest/ { proxy_pass http://restapi/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-Host $server_name; } }
(note that a client_max_body_size was added March 2023 so that uploads of large pictures can go through)
Now, restart nginx:
sudo systemctl restart nginx.service
Finally, enable TLS/SSL with Letsencrypt:
sudo apt-get install python3-certbot-nginx sudo certbot --nginx -d example.openimis.org # don't forget to edit the URL
You will then need to choose whether or not to redirect HTTP traffic to HTTPS:
Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1: No redirect - Make no further changes to the webserver configuration. 2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for new sites, or if you're confident your site works on HTTPS. You can undo this change by editing your web server's configuration. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Select the appropriate number [1-2] then [enter] (press 'c' to cancel):
Install the mobile REST API
For the moment, the REST API is the last part of the openIMIS system that was not adapted to Postgres. It can be installed on Linux or other systems via Docker. This guide will show how to set it up as a stand-alone docker.
The REST API requires a Microsoft database!
First, go to oi
and clone the REST API repository:
cd /oi git clone https://github.com/openimis/rest_api_c-sharp cd rest_api_c-sharp
At this stage, you should be on the main
branch. ⚠️ Currently (4 May 2023), there are some issues that must be fixed on the main
branch, so you should go to the fix/docker_compose
until it has been merged into main
: git switch fix/docker_compose
.
Before starting the REST API, you will need to edit the docker-compose
and Dockerfile
files with the database information.
Here is a sample docker-compose
file. Replace the database values in the environment
section:
version: '2.4' services: restapi: build: context: ./ args: BUILD-FLAVOUR: ${BUILD-FLAVOUR:-Release} environment: - DB_HOST=Server - DB_NAME=IMIS - DB_USER=IMISuser - DB_PASSWORD=IMISuser@1234 - DB_PORT=1433 ports: - 8080:80 volumes: - ./OpenImis.RestApi/config:/app/config - ./OpenImis.RestApi/logs:/app/log - ./OpenImis.RestApi/Certificates:/app/wwwRoot/Certificates - ./photos:/app/photos - ./Escape:/app/Escape - ./FromPhone:/app/FromPhone restart: always
Here is a sample Dockerfile
file. Replace the ENV database values:
FROM mcr.microsoft.com/dotnet/core/sdk:2.1 AS build-env WORKDIR /app COPY /OpenImis.RestApi/*.csproj ./ RUN dotnet restore ARG BUILD-FLAVOUR=Release COPY . ./ RUN dotnet publish OpenImis.RestApi/OpenImis.RestApi.csproj -c $BUILD-FLAVOUR -o out FROM mcr.microsoft.com/dotnet/core/aspnet:2.1 WORKDIR /app ENV DB_HOST=Server ENV DB_NAME=IMIS ENV DB_USER=IMISuser ENV DB_PASSWORD=IMISuser@1234 # copy appsettings templates COPY ./OpenImis.RestApi/config/appsettings.Production.json.dist /app/tpl/ COPY ./OpenImis.RestApi/config/appsettings.json /app/config/ COPY ./scripts/entrypoint.sh /app/ RUN chmod a+x /app/entrypoint.sh COPY --from=build-env /app/OpenImis.RestApi/out . RUN echo 'deb http://archive.debian.org/debian/ stretch main' > /etc/apt/sources.list \ && echo 'deb http://archive.debian.org/debian-security/ stretch/updates main' >> /etc/apt/sources.list \ && apt-get -o Acquire::Check-Valid-Until=false update \ && apt-get install gettext -y \ && rm -rf /var/lib/apt/lists/* ENTRYPOINT /app/entrypoint.sh
Then, you can start the Docker service:
docker-compose up -d
Once the container has finished building and has started, you can check that the REST API is properly working:
First, you can type
docker ps
. In theSTATUS
column, you should see something similar toUp xx minutes
.Then you can access the REST API and see if you see any data fetched from the database, for instance by accessing the following page: <your-openIMIS-URL>/rest/api/claim/Controls
Previous step: MO1.1 Install openIMIS using Docker | Next step: |