Skip to content

Latest commit

 

History

History
119 lines (75 loc) · 5.22 KB

DEPLOYMENT_GUIDE.md

File metadata and controls

119 lines (75 loc) · 5.22 KB
Raw

HospitalRun Deployment Guide

Welcome to HospitalRun Deployment Documentation. You can log issues, comments or contributions on the public repository here.

Overview

1. Pre-requisites

2. Important Configuration Scripts

Here are some configuration scripts that have been used in designing this application. It is important you know exactly what they do, so you can manipulate your configuration or scale them as you desire.

  • docker-compose.yml
  • config-example.js
  • Dockerfile
  • utils/elasticsearch.sh
  • nginx/conf/certbot-auto
  • nginx/conf/.tmpl, nginx/conf/.conf
  • nginx/conf/entrypoint.sh
  • nginx/Dockerfile
  • logstash/pipeline/logstash.conf
  • logstash/Dockerfile
  • data
  • conf/initcouch.sh
  • conf/entrypoint.sh

Deploying HospitalRun to a Production Environment

Assumptions: You should have git, docker and docker-compose running on your machine before the steps above can work. The instructions also assume you will be running this on a Linux machine, preferably Ubuntu LTS >=14.04

Step-by-Step Guide

Follow these five easy steps to get HospitalRun up and running

  1. Clone the repository git clone [email protected]:HospitalRun/hospitalrun-server.git.
  2. Run cd hospitalrun-server. This should take you into the hospitalrun-server root folder
  3. From this location, edit the docker-compose.yml file.
  • To use automatic SSL cert generation, edit the DOMAIN_NAME argument and replace www.example.com as shown in the image below with the publicly accessible domain name that HospitalRun will run on.
  • To instead use your own SSL cert, change the SSL_TYPE argument to self and place your certificate files at data/nginx/cert/ssl.crt and data/nginx/cert/ssl.key. You will need to create a data/nginx/cert path from the root folder if you haven't run the server yet. screenshot
  1. Save the file and run docker-compose up --build. You should wait for some ten minutes or less for your environment to be up and running. Deployment speed will vary based on your internet connection speed and the quality of your infrastructure
  2. Go to http://localhost/ in a browser and login with username hradmin and password test

Troubleshooting

Check which containers run and which do not

Run docker-compose ps. Note the State column of the command's output.

Error starting userland proxy: Bind for 0.0.0.0:80: unexpected error Permission denied'

or something similar: the port 80 is in use already. Either find which application uses that and free the port or edit the docker-compose.yml and change the "80:80" into "<another port which is free>:80".

Nginx container shuts down soon after being started

Usually due to SSL configuration being incorrect. Either 'auto' configuration and the cert generation is failing, or 'self' and the cert files are not placed correctly. Viewing the container's log output should provide more info.

The Data Folder

This folder contains all the data needed to be available should the containers be shutdown, or restarted for any reason. It should contain after startup, the following:

  1. Nginx folder, and Let's Encrypt certificates
  2. CouchDB Data
  3. Elasticsearch Data

If you delete this folder, you WILL lose all your data and installed SSL certificate

Docker Containers on HospitalRun Server

List of Containers:

  1. Nginx - WebServer
  2. HospitalRun - Node.JS App Server
  3. Logstash - Log Streaming Application
  4. Elasticsearch - For Search
  5. CouchDB - NoSQL Data Store

Nginx

The Nginx container contains configuration files for routing requests to the app server. It definitely can handle more requests in a production environment and is suited for such. This container is also designed to automatically install letsencrypt certificates for secure HTTP. It receives requests from the internet and routes it to port 3000 on the hospitalrun container. It listens for requests on ports 80 and 443

HospitalRun

This container runs the application and listens for requests on port 3000. At startup, it has entry point scripts that initialize couchdb using the conf/initcouch.sh script and another that at utils/elasticsearch.sh that initializes elasticsearch mappings. The container also runs the npm start command on successful deployment

Logstash

This container gets relevant data from the couchdb container using the instruction in logstash/conf/logstash.conf file and passes over relevant data to the elasticsearch container

Elasticsearch

This container receives data passed to it from logstash, making it possible to have lightening fast search results from the HospitalRun application

CouchDB

This container saves user authentication and all other data within the HospitalRun application.