...
configuration of the images folder
Database
...
| Note |
|---|
This guide does not cover the database setup. Both PostgreSQL and Microsoft SQL Server are supported here, unless the REST API is needed. |
1 - Minimal Linux setup
This takes Ubuntu as example but can easily be adapted to most other distributions.
...
We will fetch the main application components, backend and frontend and backend:
| Code Block |
|---|
git clone https://github.com/openimis/openimis-be_py.git git clone https://github.com/openimis/openimis-fe_js.git |
...
| Code Block |
|---|
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 |
2.1.1 - Backend requirements installation
Adapt openimis.json to suit your needs of openIMIS modules to deploy.
...
Now, you will need to create a an .env file with the main parameters of the backend:
...
| Code Block |
|---|
cd ~/oi/openimis-be_py/openIMIS # If not already there from last step ./manage.py runserver |
| Info |
|---|
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. |
2.1.2 - Configure the automated restart
For systemd, create a file /lib/systemd/system/openimis.service:
| Code Block |
|---|
[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 |
| Note |
|---|
Be careful to adapt the 4 occurences of the “openimis” if your username is different:
|
Start the server manually:
...
2.2 - Configure the frontend
...
2.2.1 - node & yarn installation
The first step is to install node.js. OpenIMIS 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 available here, but a generic solution like nvm is also a good option.
For Ubuntu with stock Node:
...
| Code Block |
|---|
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 |
2.2.2 - Frontend requirements installation
Go the frontend folder:
| Code Block |
|---|
cd ~/oi/openimis-fe_js |
...
| Code Block |
|---|
yarn load-config yarn install yarn build yarn global add serve |
| Note |
|---|
If building yarn fails with an out of memory error, use |
At this stage, you should be able to run the app in dev mode with yarn start.
| Note |
|---|
This is not recommended for production !! |
So instead, let’s build a static bundle and deploy it in nginx’s path:
...
| Code Block |
|---|
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;
}
} |
...
| Info |
|---|
client_max_body_size was added in March 2023 |
...
to allow uploads of large pictures |
...
Now, restart nginx:
| Code Block |
|---|
sudo systemctl restart nginx.service |
...
| Code Block |
|---|
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):
|
3 - Install the mobile REST API
For At 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.
| Warning |
|---|
The REST API |
...
does NOT work with Postgres. You must use a Microsoft database |
...
for the REST API. |
3.1 - Setting up the REST API
First, go to oi and clone the REST API repository:
...
At this stage, you should be on the main branch. ⚠️
| Note |
|---|
Currently (May 4 |
...
2023), there are some issues that must be fixed on the |
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:
| Code Block |
|---|
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:
| Code Block |
|---|
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
|
...
| Code Block |
|---|
docker-compose up -d |
3.2 - Making sure the REST API is working
Once the container has finished building and has started, you can check that the REST API is properly working:
...