Toward a More Approachable Install

Development
1

Hi Team!

I’m still relatively new, I have been focusing on understanding the various OpenMRS installs, some impressions lead me to make some suggestions but I do not want to proceed without your more experienced thoughts.

I’ll go into some detail about my attempted installs here, and if you have any suggestions for specific fixes I am all ears, but I here I am interested in proposing changes to the web page, wiki, and readme files, I’ll try explicit about delineating suggestions here.

Suggestion: For each release we should be specific about the configurations on which we have successfully installed and tested.

I get that we need to support many different hardware platforms for the community and that much of that hardware is old and highly constrained. I get that if we have a user in the community with an “unusual” config we will do what we can to support them.

That being true there are enormous benefits to the community of converging on specific “standard” configs of hardware, os, and required tools (e.g. tomcat and mysql).

I picked the config I used very deliberately, it’s the current default Debian instance at Google Cloud Platform (we could just as easily have done AWS). It contains “default” releases of java (currently 11), tomcat (9), and MySQL (15.1).

I went to the OpenMRS download page and was successfully convinced to start with the standalone ref app 2.10.0. That was unsuccessful, after waiting several mins openmrs fails to start, I have logs, happy to pursue separartely.

While the standalone install with embedded tomcat and mysql is clever and I can see how it could help, in my experience it was not helpful, when it does not work I have zero visibility into what’s going on (as I would with e.g. regular tomcat).

OK so I decide I’ll deal with tomcat and MySQL myself and install the plain openmrs.war. I get a little further but OpenMRS is unable to write its runtime.profile file, Daniel was very helpful in another thread but I remain stuck.

This doc is with my config almost certainly inaccurate but I don’t yet know what the correct behavior is to update:

https://wiki.openmrs.org/display/docs/Overriding+OpenMRS+Default+Runtime+Properties

I would really, really like to fix either the code or the doc - I can see other users have had issues.

In order to attempt to proceed I rammed :slight_smile: a profile file into the directory it looks for it in, it seems to read it but then it gets upset about not being able open the database, I used the .properties file from the standalone install but I have no idea if it’s valid, I declared myself flailing unproductively.

Bottom line - my Debian config does not work with OpenMRS’s current releases, which asks the question “what configs were the current releases tested on?” With some automated testing this could evolve between releases as well.

I have no idea what is going on in the field (too new!) but it seems like the development community who pipe up on talk run on:

  • Windows
  • Mac
  • Ubuntu/Debian

Is that true? Could we ever have “release configs” on which we explicitly test prior to release? THAT WOULD BE SO COOL I’d love to help.

Suggestion: Consolidate all docs relating to install and config

there is the download page, the wiki, sometimes READMEs in the distributions, discussions on talk and comments in the wiki. They contain a lot of outdated and and inconsistent information at a high level of detail, it’s super disruptive.

With the next major release do you think we could consolidate all the install/release info into a single source - say one place in the wiki? All other places reference that wiki doc and we QA and update it with each release.

I’ll start this work now with some edits on really old stuff.

Suggestion: Rigorously document OpenMRS interfaces to the OS, to the web server, and to the database.

E.g. how - specifically - does OpenMRS expect MySql configured on install? I suppose the install wizard is supposed to help but that was super frustrating for me. E.g. there are multiple profile file examples on the wiki and in the packages with different values for connection.username and connection.password, ugh I want to fix but I see no single source of truth.

Suggestion - Remove all references to versions of e.g. OSs, java, MySQL, Tomcat, etc from the wiki - replace with a single doc updated on each release

You see a pattern here :slight_smile: does this make any sense? I’m gonna get started.

1 Like
2

You’re welcome.

3

I’m new here as well and have run into similar issues. I agree that this is a problem that should be improved on. The various documentation on various platforms is confusing to navigate and it really should be consolidated in some way. Figuring out which version of x, y, z is needed for a given installation is troublesome as well. I’d love to help work on this if it is approved, because I think it is important.

4

Bless you all for your willingness & passion!

Wikis frequently get blamed for their ability to demonstrate the second law of thermodynamics: Entropy. With over a decade of contributions, out documentation is full of crust. It would undoubtedly benefit from a good Spring cleaning.

I agree with your sentiments of trying to focus efforts. That’s why, for example, I shamelessly direct new devs to om.rs/gettingstarted and keep promoting om.rs/devmanual as a dev reference and to om.rs/guide for an implementer guide along with the wiki. It’s not because I think these are the perfect resources; rather, we’re better of trying to get everyone looking at the same artifacts and iterate on improving them instead of continually making new artifacts that end up getting outdated and adding to the problem.

So, here’s a big cheers to anyone willing to roll up their sleeves and improve what we’ve got instead of making the next new thing! :slight_smile:

It’s worth noting that our latest platform release is made for Java 8 and does not support later versions. The next platform release (Platform 2.4) will support Java 8, 11, 13, and 14 (most importantly Java 8, which is in most production environments, and Java 11, as our goal is to support LTS versions).

The recently released Reference Application 2.10 uses Platform 2.3, so will need Java 8 and will undoubtedly require old versions of Tomcat & MySQL.

Personally, I’d like to see us migrating toward production support of containers (e.g., a Docker stack), which avoids the OS-specific variations and gives us more flexibility & predictability with deployment. Let those with the time & expertise play with custom installs of J2EE containers, databases, etc.

But this will take some time. For now, some clear direction on how to quickly get a system up & running in the wiki & community reference manuals would be most welcome.

1 Like
5

Burke I am really excited to be here, the work you and the team have done is uniquely well suited to support my work, I am self-conscious about how I engage the team, you are always so welcoming thank you.

OK this did not surprise me after being here a couple of weeks, but it’s insanely valuable information for newbies like me, as you agent I’m going to look to give it higher profile and keep it updated.

(I have the same profile file issue with the nightly release, I think it may be a real bug, I’ll use it learn how you all use Jira)

When the smoke clears I’ll build cloud image templates that work with java 8 for the current release and we’ll be all over documenting config testing for the next release.

I hear you, I see me mapping stuff out at the instance level, maybe a container story is cleaner, psyched to learn more.

6

One :slight_smile: more thing, not at all surprisingly the team assumes experience with java, I think I was going on in another thread, there is a class of community member who might be fairly technical but engage primarily with the API and not a java heavy. Like me. I’ll try adding a little context in the docs about what’s up with distributing java apps.

7

I like this idea - it seems like this is in line with one of the Documentation Team’s goals for this year: making sure that developer/implementer documentation is up to date and consistent across sites.