smart-on-fhir/installer

Name: installer

Owner: SMART on FHIR

Description: null

Created: 2016-06-02 11:49:41.0

Updated: 2018-01-15 17:56:23.0

Pushed: 2018-01-12 18:24:39.0

Homepage: null

Size: 31336

Language: Shell

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Building your own SMART on FHIR platform

This installer will create a full SMART on FHIR platform including a FHIR server, an OAuth server, and a SMART launch simulator.

Supported System Architectures

The SMART on FHIR platform will be installed on a single machine in one of the following layouts:

1. VM Instance Install (ie: an Ubuntu server running on VirtualBox on a developer machine)
2. Native Install (ie: an Ubuntu server)

More advanced installations are possible by modifying this installer (mainly inventory.yml) but are not supported by our technical team.

Supported Operating Systems

The SMART on FHIR platform is tested on Ubuntu 16.04. Other linux-based systems may require different commands or packages.

• Ubuntu 16.04 may be used as a platform server or controller machine

• Mac OSx may be used as a controller machine or VirtualBox host

• Windows may be used as a VirtualBox host for a native install

  See Windows Notes

SMART on FHIR Platfrom

When complete, you will have a SMART on FHIR platform!

• {host}:9080/ for the Sandbox Manager application
• {host}:9071/api/smartdstu2/data for a FHIR DSTU2 API server
• {host}:9071/api/smartdstu2/data/metadata for the FHIR DSTU2 API conformance
• {host}:9074/api/smartstu3/data for a FHIR STU3 API server
• {host}:9074/api/smartstu3/data/metadata for the FHIR STU3 API conformance
• {host}:9060/auth/ for an OAuth2 authorization server
• {host}:9093 for a SMART apps server
• {host}:10389 for an ApacheDS LDAP server
• {host}:3306 for a MySQL database

A demo account is created to simulate a practitioner login: demo/demo.

• See SMART on FHIR Platform Systems

---

VM Instance Install using VirtualBox

In this install, we are going to build the SMART on FHIR platform on a Ubuntu server running on VirtualBox.

Prerequisites

• VirtualBox 5.1.28
• Vagrant 2.0.0
• Ansible 2.3.2.0

If you have the pip Python package manager installed, the easiest way to install the correct version of Ansible is to run the following:

 pip install ansible==2.3.2.0

Prepare the host

ant plugin install vagrant-vbguest
clone https://github.com/smart-on-fhir/installer
nstaller

Load the Ansible Galaxy roles

ble-galaxy install -r roles/requirements.yml -p ./roles/ --force

Run the Installer

ant up

… wait ~20min while everything installs (depending on your Internet connection speed).

You can poke around the virtual machine by doing:

ant ssh

And when you're done you can shut the virtual machine down with:

ant halt

---

Native Install on Ubuntu 16.04

In this install, we are going to build a SMART on FHIR platform directly on an Ubuntu 16.04 server.

Prerequisites

• Ubuntu 16.04 machine
• See SMART on FHIR AWS Test Configuration

Prepare the server

From the Ubuntu 16.04 machine:

 apt-get update; sudo apt-get -y install curl git python-pycurl python-pip python-yaml python-paramiko python-jinja2 unzip libwww-perl libdatetime-perl; sudo pip install ansible==2.3.2.0; pip install --upgrade pip;
clone https://github.com/smart-on-fhir/installer
nstaller

Download the Ansible Galaxy roles

ble-galaxy install -r roles/requirements.yml -p ./roles/ --force

Run the site.yml playbook for the local environment

*Note: replace the services_host with your IP address or host name

ble-playbook site.yml -i "localhost," -c local \
extra-vars "env=local installer_user=ubuntu services_host=34.239.242.159"

Modify the vars for your environment. You will also need to define which set of environment files your deployment is using. We set an inventory property in our Ansible Galaxy inventory such as:

env: “test”

nvironments/{env}.yml

Sensitive properties can be stored in the {env}-secrets.yml files. There is an excellent tutorial here: Ansible Vault Tutorial.

• set “installer_user” to your ssh username
• set “services_host” to a real-world route-able IP for your Ubuntu machine
• setting passwords, ports, and other properties as desired

Load the Ansible Galaxy roles

ble-galaxy install -r roles/requirements.yml -p ./roles/ --force

Run the Installer

 ansible-playbook site.yml

---

SMART on FHIR Platform Components

The SMART on FHIR platform consists of several open-source systems that together support the SMART on FHIR launch and security specification for apps. These open-source systems are reference systems, meaning they have not been created with the intention of supporting production use cases “out of the box”. Please contact each of these open-source projects with further questions.

| Functional Role | System Name | More Information | | ————————– | ———————— | ——————————————————————– | | DSTU2 & STU3 FHIR Server | HSPC Reference API | https://bitbucket.org/hspconsortium/reference-api | | | HAPI FHIR | http://jamesagnew.github.io/hapi-fhir/ | | OAuth2 Server | HSPC Reference Auth | https://bitbucket.org/hspconsortium/reference-auth | | | MITRE Open ID Connect | https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server | | SMART Launch Simulator | HSPC Sandbox Manager | https://bitbucket.org/hspconsortium/sandbox-manager | | Cardiac Risk App | Cardiac Risk App | https://github.com/smart-on-fhir/cardiac-risk-app | | BP Centiles App | BP Centiles App | https://github.com/smart-on-fhir/bp-centiles-app | | Growth Chart App | Growth Chart App | https://github.com/smart-on-fhir/growth-chart-app | | Sandbox Manager | HSPC Sandbox Manager | https://bitbucket.org/hspconsortium/sandbox-manager | | User Management | ApacheDS | http://directory.apache.org/apacheds | | Messaging Server | HSPC Reference Messaging | https://bitbucket.org/hspconsortium/reference-messaging |

---

Tips and Tricks

AWS Test Configuration

Here is the exact configuration we use to test the installer using an AWS EC2 instance. The ports must all be open for inbound connections in the security group.

| Item | Value | | ————- | ———————–:| | Instance Type | t2.large | | AIM | Ubuntu Server 16.04 LTS | | SSH PORT | 22 | | HTTP PORT | 80 | | HTTPS PORT | 443 | | LDAP PORT | 10389 | | APPS PORTS | 9070-9099 |

TLS

By default, the install process will not enable TLS. To enable TLS for specific services, you can set the following variable:

• use_secure_http: true

What certificates will be used? You have two options:

1. Set use_custom_ssl_certificates: true and custom_ssl_certificate_path: /path/to/cert/dir. For an example, see our testing server settings. And for an example of what the directory layout should look like, see here.

2. If you set use_custom_ssl_certificates: false, the installer will generate self-signed SSL certificates. Please note that with self-signed certificates, you will get a number of trust warning in your web browser that can be resolved by adding certificate exceptions in your browser, or updating your CA list on a client by client basis. Before you even try the apps, you should probably load the API server and add the self-signed certificate to your browser's security exceptions.

Sample data

By default, the server will load data for only 20 sample patients. To automatically load the entire set of ~60 samples patients, you can update your inventory to increase this limit:

• api_dstu2_sample_patients_limit: 100

Log Files

The installer creates servers that log to the journal. You can view the journal logs using this command:

• sudo journalctl -u api-dstu2-server.service
• sudo journalctl -u api-stu3-server.service
• sudo journalctl -u auth-server.service

Use the -f option tail the logs.

Aliases

The installer creates several aliases that can be used to help you manage and navigate the sandbox system.

You can see the aliases by typing “alias” from the command prompt. The aliases are defined in the ~/.bash_profile file.

tu$ alias

These aliases are helpful to navigate the most important folders.

s f='cd $hosting_user_home'
s i='cd $installer_project_home'
s n='cd $NGINX_SITES'
s s='cd $SERVICE_HOME'

These aliases are helpful for starting services.

s startn='sudo service nginx start'
s stopn='sudo service nginx stop'

These aliases are helpful for viewing (ex: v…) or tailing (ex: t…) different service logs.

s tapi='sudo journalctl -f -u api-dstu2-server.service'
s tapi='sudo journalctl -f -u api-stu-server.service'
s tauth='sudo journalctl -f -u auth-server.service'
s tmsg='sudo journalctl -f -u messaging-server.service'
s tpwm='sudo journalctl -f -u pwm-server.service'
s tsand='sudo journalctl -f -u sandbox-manager-server.service'
s vauth='sudo journalctl -u auth-server.service'
s vmsg='sudo journalctl -u messaging-server.service'
s vpwm='sudo journalctl -u pwm-server.service'
s vsand='sudo journalctl -u sandbox-manager-server.service'

Windows Notes

• Windows Note: Ansible is not supported on Windows. If you want to build a SMART on FHIR VM on Windows, you should create a VM instance for Ubuntu 16.04 and perform a please use the version of the installer which runs Ansible on the guest machine instead of using the one on the host OS. To enable this mode, please edit Vagrantfile by commenting out the “ansible” provisioner and enabling second “shell” provisioner before running vagrant up. An alternative options is to follow the instructions in the “Building SMART-on-FHIR on fresh Ubuntu 16.04 machine (without Vagrant)” section in this document.

• Windows Note: The default installation of GIT on Windows enables a LF to CRLF conversion upon checkout which is going to mess up the install. You will need to make sure that this conversion is disabled by running: