Skip to content

KENYAEMR 3.x Facility-Wide v1.10.25 (2024-07-24) with Nginx
Compare
Choose a tag to compare
@Murithijoshua Murithijoshua released this 25 Jul 06:42
· 152 commits to main since this release
v1.10.25.1
1936eec
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.

KenyaEMR v19.0.0 Release Notes with nginx Configuration

Overview

This release introduces KenyaEMR v19.9.0 for the 3.x platform, running on MySQL 8. It brings significant enhancements, new features, and important bug fixes to improve the overall functionality and user experience of the system.

Important Notes

⚠️ PLEASE READ BEFORE UPGRADING

  1. Prerequisite Upgrade: You must have upgraded to KENYAEMR3.X_FACILITY_WIDE_v1.10.23_MON-2O-MAY-2024 before proceeding with this upgrade.
  2. DWAPI Compatibility: This version is compatible with the latest version of DWAPI (Data Warehouse and Analytics Platform Interface).
  3. Nginx Configuration: Proper Nginx setup is crucial for optimal performance gains. Please follow the installation guide carefully.

New Features and Enhancements

  1. Nginx Integration for Performance Boost

    • Implemented Nginx as a reverse proxy to significantly reduce page load times.
    • Improved handling of concurrent connections for better system responsiveness.
    • Enhanced static content delivery and caching mechanisms.

  2. Appointment Form Enhancement

    • Now supports retrospective documentation of appointments, providing greater flexibility in managing patient schedules.

  3. IIT Risk Scores Optimization

    • Significantly reduced processing time for generating Interruption in Treatment (IIT) Risk Scores, improving system performance.

  4. Order Basket Expansion

    • Added capability to include Radiology and Procedures in the Order Basket, streamlining the ordering process.

  5. Contact Listing Feature

    • Introduced a new feature for listing and managing patient contacts.

  6. Automatic KP Identifier Generation

    • Implemented functionality to auto-generate Key Population (KP) identifiers, enhancing data management for this group.

Retired Features

  • The Missed Appointment Report has been retired in this version.

Bug Fixes

  • Various bug fixes have been implemented to improve system stability and reliability. (Detailed list of fixes can be provided upon request)

System Requirements

  • Platform: KenyaEMR 3.x
  • Database: MySQL 8

Installation and Training Materials

Comprehensive Guide: Setting up Nginx for OpenMRS with Tomcat as backend

This guide will walk you through the process of installing Nginx and configuring it for OpenMRS with a Tomcat backend. We'll include necessary validations and explanations at each step.

1. Install Nginx

sudo apt-get update
sudo apt-get install nginx

Validation:
After installation, check if Nginx is running:

sudo systemctl status nginx

You should see "active (running)" in the output.

2. Configure Nginx for OpenMRS

  1. Open the Nginx configuration file:

    sudo nano /etc/nginx/sites-available/default

  2. Replace the contents with the following configuration:

    upstream backend_assets {
    server localhost:8081;
}

server {
    listen 8080;
    server_name _;
    root /var/lib/OpenMRS/frontend;

    # CORS configuration
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
    add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization' always;
    add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;

    location /openmrs/ {
        proxy_pass http://backend_assets;
        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 $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_cache_valid 200 60m;
        proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;

        # CORS headers for proxied requests
        add_header 'Access-Control-Allow-Origin' '*' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization' always;
        add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;
    }

    # accessing legacy
    location ~ ^/openmrs/(kenyaemr|reports|admin|ms|scripts|moduleResources|dwr) {
        proxy_pass http://backend_assets;
        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 $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # proper redirections
    location / {
        tcp_nopush on;
        keepalive_timeout 65;
        proxy_cache_valid 200 60m;
        proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
        try_files $uri /index.html;
    }

    # CSS files
    location ~* \.css$ {
        add_header Content-Type text/css;
        proxy_cache_valid 200 60m;
        proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
    }

    # JavaScript files
    location ~* \.js$ {
        add_header Content-Type application/javascript;
        proxy_cache_valid 200 60m;
        proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
    }

    location ^~ /openmrs/spa/ {
        alias /var/lib/OpenMRS/frontend;
        try_files $uri /var/lib/OpenMRS/frontend/index.html;

        # Rewrite to check assets from root
        location ~* ^/openmrs/spa/(.+\.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|json|eot))$ {
            sendfile on;
            sendfile_max_chunk 1m;
            # Cache Prevention Start
            proxy_ignore_headers Cache-Control;
            add_header Last-Modified $date_gmt;
            add_header Cache-Control 'no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0';
            if_modified_since off;
            expires off;
            etag off;
            proxy_cache_valid 200 60m;
            proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
            try_files /$1 =404;
        }
    }

    location = / {
        rewrite ^ /openmrs/ permanent;
    }

    location = /openmrs/spa {
        rewrite ^ /openmrs/spa/ permanent;
    }

    location = /openmrs/spaa {
        rewrite ^ /openmrs/spa/ permanent;
    }

    # Enable gzip compression
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml application/json application/javascript application/rss+xml application/atom+xml image/svg+xml;

    error_log /var/log/nginx/openmrs_error.log;
    access_log /var/log/nginx/openmrs_access.log;
}

  3. Save and exit the editor (in nano, press Ctrl+X, then Y, then Enter).

Validation:
Check the Nginx configuration for syntax errors:

sudo nginx -t

You should see "syntax is okay" and "test is successful".

3. Configure Tomcat

Ensure Tomcat is configured to run on port 8081 as specified in the Nginx upstream configuration:

  1. Open the Tomcat server configuration file:

    sudo nano /var/lib/tomcat9/conf/server.xml

  2. Find the Connector element and ensure it's set to port 8081:

    <Connector port="8081" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443" />

  3. Save and exit the editor.

  4. remove SPA module

rm /var/lib/OpenMRS/modules/spa-1.0.9-SNAPSHOT.omod

Validation:
Check if port 8081 is not already in use:

sudo netstat -tuln | grep 8081

If this command returns no output, the port is free to use.

4. Restart Services

Restart both Tomcat and Nginx to apply the changes:

sudo systemctl restart tomcat9
sudo systemctl restart nginx

Validation:
Check if both services are running without errors:

sudo systemctl status tomcat9
sudo systemctl status nginx

Both should show "active (running)" without any error messages.

5. Final Validation

  1. Test the Nginx configuration:
    Open a web browser and navigate to http://localhost:8080/openmrs/
    You should see the OpenMRS login page or welcome screen.

Troubleshooting

  • If you encounter issues, check the Nginx error logs: 
    sudo tail -f /var/log/nginx/openmrs_error.log
  • For Tomcat issues, check its logs: 
    sudo tail -f /var/log/tomcat9/catalina.out

Notes on the Nginx Configuration

  • This configuration sets up Nginx to listen on port 8080 and proxy requests to a Tomcat server running on localhost:8081.
  • It includes CORS headers to allow cross-origin requests.
  • There are specific rules for handling static files (CSS, JS) and the OpenMRS Single Page Application (SPA).
  • Gzip compression is enabled for better performance.

Ensure that your OpenMRS application is properly set up in the specified directories, particularly the frontend files in /var/lib/OpenMRS/frontend.

Assets 5
Loading