Skip to content

Latest commit

 

History

History
221 lines (162 loc) · 8.63 KB

README.md

File metadata and controls

221 lines (162 loc) · 8.63 KB
Raw

OpenInfoMan

OpenInfoMan is XQuery and RESTXQ based implementation of the Care Services Discovery (CSD) profile from IHE which implements the following actors and transactions:

Info Manager : Find Matching Services (Ad-Hoc and Stored) [ITI-73]
               Query for Updated Services Transaction [ITI-74]
Services Directory : Query for Updated Services Transaction [ITI-74]

OpenInfoMan has been developed as part of OpenHIE and is intended to be the engine behind the CSD compliant Health Worker Registry and to be incorporated in OpenHIM.

Ubuntu Installation

You can easily install on Ubuntu 14.x and 16.x using the following commands

sudo add-apt-repository ppa:openhie/release
sudo apt-get update
sudo apt-get install openinfoman

Note that the Debian packaging creates an oim user.

Once you have installed the package, you should be able to access OpenInfoMan at:

http://localhost:8984/CSD

Ansible (CentOS only)

A series of Ansible playbooks are available in resources/scripts

CentOS Manual Installation

Requirements are a Java Runtime Environment (Java 8 for the current [1.4.61] release), PHP, git, wget, and unzip. Note that php-xml is an additional requirement for CentOS.

sudo yum install -y git wget unzip java-1.8.0-openjdk php php-xml

The default ingress point is TCP port 8984. Ensure that port 8984 is unblocked. For example:

sudo firewall-cmd --permanent --add-port=8984/tcp
sudo firewall-cmd --reload

OpenInfoMan runs on an unprivileged port. Any user can manage the processes. See notes on production deployments below.

Once requirements are created, install OpenInfoMan using the provided script in resources/scripts

# locally
bash resources/scripts/install.sh
# or on a remote host
ssh user@IP_ADDR 'bash -s' < install.sh

To install additional libraries:

# locally
bash resources/scripts/install_additional.sh
# or on a remote host
ssh user@IP_ADDR 'bash -s' < install_additional.sh

macOS Installation

macOS does not include Java (since 10.7 and above), git, or wget. It includes unzip and PHP.

It is suggested to use homebrew:

brew install git wget

And install Java. Once requirements are created, install OpenInfoMan using the provided script in resources/scripts

bash resources/scripts/install.sh
# and for additional libraries
bash resources/scripts/install_additional.sh

Tests

The generic install without libraries and the libraries installations include simple tests as bash scripts. The tests do not cover the majority of functions, they are rather meant as a simple test for first level functionality in a help desk environment.

$ bash resources/scripts/install_test.sh
PASS [200]: Landing page
PASS [302]: Add test document
PASS [200]: List Shared Value Sets
PASS [200]: List Stored Functions
PASS [200]: Export Stored Functions
PASS [200]: List sample dirs
PASS [302]: Load provider sample dir
PASS [200]: Get providers sample dir
PASS [302]: Reload providers dir
PASS [302]: Delete providers sample dir
PASS [302]: Remove test document
$ bash resources/scripts/install_additional_test.sh
Which OpenInfoMan libraries do you wish to test?
1) All_public	     4) ILR		  7) Quit
2) All_DATIM	     5) RapidPro_and_CSV
3) DHIS		         6) HWR
#? 1
PASS [302]: DHIS - Load Sierra Leone demo as CSD
PASS [200]: DHIS - Get Sierra Leone demo as CSD
PASS [302]: DHIS - Delete Sierra Leone demo as CSD
PASS [200]: ILR - Download validate provider facility service
PASS [200]: CSV-RapidPro - Download CSV for import
PASS [200]: HWR - Get all facilities

Backup and Restore

Logs and data are located in data. The logs are under data in the .logs folder. A one-liner can create a backup of the data in OpenInfoMan and a one-liner can restore it.

For example to backup data and logs and store them on S3:

basex -c"CREATE BACKUP provider_directory"
zip $HOME/openinfoman/data/logs-$(date +"%Y-%m-%d-%H-%M").zip $HOME/openinfoman/data/.logs
ls -la $HOME/openinfoman/data/
# move the logs and data zipfiles to a safe location, e.g.
aws s3 cp $HOME/openinfoman/data/logs-* s3://backup_bucket/logs
aws s3 cp $HOME/openinfoman/data/provider_directory-* s3://backup_bucket/data
# or
cp $HOME/openinfoman/data/logs-* ~/backup/logs
cp $HOME/openinfoman/data/provider_directory-* ~/backup/data

Restores require that just the name be used in the filename, e.g. provider_directory, and the additional timestamp will be ignored. For restores:

basex -c"RESTORE provider_directory"

The backup and restore process is the same on any operating system.

OpenInfoMan Libraries

There are additional libraries thatextend the core OpenInfoMan funcitonality:

To install additional libraries:

bash resources/scripts/install_additional.sh

There are six options. DATIM libraries require access to private repo and for SSH to be setup for git. All other options are in public repositories.

Which OpenInfoMan libraries do you wish to install?
1) All_public	     		  
2) All_DATIM	     
3) DHIS
4) ILR
5) RapidPro_and_CSV
6) HWR
7) Quit

Docker images

Docker builds suitable for testing are on https://hub.docker.com/r/openhie/openinfoman/ Note that the images do not use a mounted volume. This means that all data is removed when containers are destroyed. Releases are tagged with the SHA hash of the commit it is based upon in this repo.

To launch the latest Docker build:

docker run -d -p 8984:8984 docker pull openhie/openinfoman

See packaging/dockerfor Dockerfiles to build your own image.

OpenInfoMan in Production

  • Note that the Ansile or bash scripts are not designed for process maintenance. Use Monit or another tool to ensure that BaseX is running as expected.

  • OpenInfoMan does not include authentication or authorization. It is meant to be run inside a private cloud/cluster and behind a proxy. Follow instructions on this wiki manual to add authentication using OpenHIM, or this youtube video https://www.youtube.com/watch?v=bXLpNlMSZdM&feature=youtu.be or roll your own solution using another proxy with authentication.

  • OpenInfoMan should be run by a user without superuser privileges. It is recommended to create a non-root and non-sudo user for running OpenInfoMan. This means that another user with sudo privileges should use used to install prerequisite software and then not used to run OpenInfoMan.

  • Ensure that TCP port 8984 is open on security policy/firewall.

Note that when OpenInfoMan is installed using the Bash script that it increases memory to 3GB. This is meant for production use.

  • Increase memory usage by modifying the bin/basexhttp shell script and uncomment
#VM=Xmx512m

then change to suitable values:

VM="-Xms2g -Xmx2g"

CSD Schema

You can find documentation for the CSD schema data mode here which has be generated from CSD.xsd

Stored Functions

The base CSD standard can be extended using stored functions.

You can find documentation on the available stored functions across the OpenInfoMan libraries here.

(tra-la-la)