This application provides a web application to configure and manage the OpenHIM-core component. It provides the following features:
See the development road-map for more details on what is to come!
See documentation and tutorials at openhim.org.
First ensure that you have the OpenHIM-core server up and running. See details on how to get the OpenHIM-core setup
Clone the repository and then run
npm install
To start up a development instance of the webapp run
npm start
For file changes to apply run npm build
before starting the server.
To run tests:
npm test
To spin up a full OpenHIM environment, navigate to the infrastructure
folder and execute: docker-compose up
The config for the console is controlled via the default.json
file in the config directory. The file is copied from your local repo on start up.
To edit the file:
#docker exec -it {console-container} bash
docker exec -it openhim-console bash
apt-get update && apt-get install vim -y
vi /usr/share/nginx/html/config/default.json
Or the sed command can be used
sed -i -e "s/localhost/<yourDomainHere>/g" /usr/share/nginx/html/config/default.json
Your file should look something like this:
{
"protocol": "https", // Change the protocol to 'http' when the OpenHIM core API protocol is 'http'. The default OpenHIM core API protocol is 'https'
"host": "localhost", // change this to the hostname for your OpenHIM-core server (This hostname _MUST_ be publicly accessible)
"port": 8080, // change this to the API port of the OpenHIM-core server, default is 8080
"title": "OpenHIM Admin Console", // You may change this to customize the title of the OpenHIM-console instance
"footerTitle": "OpenHIM Administration Console", // You may change this to customize the footer of the OpenHIM-console instance
"footerPoweredBy": "<a href='http://openhim.org/' target='_blank'>Powered by OpenHIM</a>",
"loginBanner": "", // add text here that you want to appear on the login screen, if any.
"showLoginForm": true, // this could be disabled in favor of a SSO using keycloak
"mediatorLastHeartbeatWarningSeconds": 60, // Mediator heartbeat check intervals to issue a warning status
"mediatorLastHeartbeatDangerSeconds": 120, // Mediator heartbeat check intervals to issue a danger status
"ssoEnabled": false, // enable SSO with Keycloak
"keyCloakUrl": "http://localhost:9088", // Keycloak URL
"keyCloakRealm": "platform-realm", // Keycloak Realm name
"keyCloakClientId": "openhim-oauth" // Keycloak client ID
}
Now, navigate to your web server and you should see the OpenHIM-console load (eg. http://localhost:9000
) and login. The default username and password are:
root@openhim.org
openhim-password
You will be prompted to change this.
Note: You will have problems logging in if your OpenHIM server is still setup to use a self-signed certificate (the default). To get around this you can use the following workaround (the proper way to solve this is to upload a proper certificate into the OpenHIM-core):
Visit the following link: https://localhost:8080/authenticate/root@openhim.org
in Chrome. Make sure you are visiting this link from the system that is running the OpenHIM-core. Otherwise, replace localhost
and 8080
with the appropriate OpenHIM-core server hostname and API port. You should see a message saying "Your connection is not private". Click "Advanced" and then click "Proceed". Once you have done this, you should see some JSON, you can ignore this and close the page. Ths will ignore the fact that the certificate is self-signed. Now, you should be able to go back to the Console login page and login. This problem will occur every now and then until you load a properly signed certificate into the OpenHIM-core server.
Clone the repository and then run
npm install
To start up a development instance of the webapp run
npm run start:dev
To start up a production instance run
npm start
For file changes to apply run npm build
before starting the server.
To run tests:
npm test
All commits to the master
branch will automatically trigger a build of the latest changes into a docker image on dockerhub.
The build process for the RPM package is based off this blog. The reason for using vagrant instead of docker is so that we can test the RPM package by running it as a service using SystemCtl - similar to how it will likely be used in a production environment. SystemCtl is not available out the box in docker containers.
Refer to this blog for a more detailed description of a possible work-around. This is not recommended since it is a hack. This is where vagrant comes in since it sets up an isolated VM.
Setup environment
Navigate to the infrastructure folder: infrastructure/centos
Provision VM and automatically build RPM package:
vagrant up
or without automatic provisioning (useful if you prefer manual control of the process):
vagrant up --no-provision
[Optional] The Vagrant file provisions the VM with the latest source code from master and attempts to compile the RPM package for you. However in the event an error occurs, or if you prefer to have manual control over the process, then you'll need to do the following:
vagrant ssh
npm i && npm i speculate
npm run spec
ln -s ~/openhim-console ~/rpmbuild
rpmbuild -bb ~/rpmbuild/SPECS/openhim-console.spec
Install & Test package
sudo yum install -y ~/rpmbuild/RPMS/x86_64/openhim-console-{current_version}.x86_64.rpm
sudo systemctl start openhim-console
curl http://localhost:9000
Note: In order for openhim-console to run successfully, you'll need to point it to a valid instance of Openhim-core or install it locally:
How to check the logs?
sudo systemctl status openhim-console
sudo tail -f -n 100 /var/log/messages
If everything checks out then extract the RPM package by leaving the VM.
Install Vagrant scp plugin:
vagrant plugin install vagrant-scp
Then copy the file from the VM:
vagrant scp default:/home/vagrant/rpmbuild/RPMS/x86_64/{filename}.rpm .
You may view/add issues here: https://github.com/jembi/openhim-console/issues
To contribute code, please fork the repository and submit a pull request. The maintainers will review the code and merge it in if all is well.