Stream: IG creation
Topic: Need help - trying to install Jekyll
Joan Harper (Nov 24 2021 at 19:18):
As part of my effort to learn FSH, I need to install the FHIR IG publisher.
According to https://confluence.hl7.org/display/FHIR/IG+Publisher+Documentation#IGPublisherDocumentation-UsingFHIRIGPublisher, in order to do that, I need to install Jekyll.
I have downloaded the publisher.jar.
I have gone to the Windows instructions to install Jekyll for Windows (http://jekyll-windows.juthilo.com/).
I have completed step 1, which is downloading and installing Ruby v2.0.0, then downloading and installing the Ruby DevKit that begins with DevKit-mingw64.
I am stuck on step 2 which is installing the Jekyll Gem. The instructions say to open a command line and enter the command "gem install jekyll". When I do that, I get the following error:
ERROR: Could not find a valid gem 'jekyll' (>= 0), here is why:
Unable to download data from https://rubygems.org/ - SSL_connect returned=1 errno=0 state=SSLv2/v3 read server hello A: tlsv1 alert protocol version (https://rubygems.org/latest_specs.4.8.gz)
Step 2 has a note that says v2.4 (from 2014) is the latest version at the time of writing which is compatible with Windows.
I went to rubygems.org and downloaded version 2.4, dropped it in the RubyDevKit directory and tried again to run the command. I received the following error:
ERROR: While executing gem ... (Gem::DependencyError)
Unable to resolve dependencies: jekyll requires liquid (~> 2.6.1), kramdown (~> 1.3), mercenary (~> 0.3.3), safe_yaml (~> 1.0), colorator (~> 0.1), pygments.rb (~> 0.6.0), redcarpet (~> 3.1), toml (~> 0.1.0), jekyll-paginate (~> 1.0), jekyll-gist (~> 1.0), jekyll-coffeescript (~> 1.0), jekyll-sass-converter (~> 1.0), jekyll-watch (~> 1.1), classifier-reborn (~> 2.0)
Can anyone help me to troubleshoot the Jekyll install?
Grahame Grieve (Nov 24 2021 at 19:23):
Could not find a valid gem 'jekyll' (>= 0), here is why:
Unable to download data from https://rubygems.org/ - SSL_connect returned=1 errno=0 state=SSLv2/v3 read server hello A: tlsv1 alert protocol version (https://rubygems.org/latest_specs.4.8.gz)
That's the important one, and we won't be able to help with that here, I think.
Grahame Grieve (Nov 24 2021 at 19:24):
do you have a network agent somewhere blocking that site?
Joan Harper (Nov 24 2021 at 19:26):
I don't think so. I was able to navigate to it directly from the same computer
Grahame Grieve (Nov 24 2021 at 19:32):
but the problem is reproducible?
Joan Harper (Nov 24 2021 at 19:33):
Yes. I got the same error message a couple of times.
Joan Harper (Nov 24 2021 at 19:34):
In the meantime, I have gone through the Jekyll installation instructions at https://jekyllrb.com/docs/installation/windows/. This installed the following:
Ruby 3.0.2p107
Jekyll 4.2.1
Joan Harper (Nov 24 2021 at 19:38):
I haven't got to the point of attempting to publish anything so I don't actually know if the newer version of Jekyll works with the IG Publisher. DO you know if it does?
Joan Harper (Nov 24 2021 at 20:03):
It looks like Jekyll is for creating websites.
How does Jekyll interact with the IG Publisher?
Is there any sort of education around setting up and using the IG Publisher/Jekyll?
I must admit that I am pretty lost here.
Grahame Grieve (Nov 24 2021 at 20:07):
the IG-publisher prepares a set of files for Jekyll to process. Because an IG is effectively a web site.
Grahame Grieve (Nov 24 2021 at 20:08):
I think we're feeling pretty lost too - we just use Jekyll, and if the install fails... I guess you have to ask on a Jekyll support forum
Joan Harper (Nov 24 2021 at 20:10):
so basically, If I have Jekyll installed successfully, then I create a new directory for my site (IG), I drop the output of the IG Publisher in that directory, and then I build and serve it with Jekyll?
Grahame Grieve (Nov 24 2021 at 20:12):
well, you can, but you don't need to - the IG output doesn't assume you're running a web server (some web sites do) and you can just load it by double clicking the files in explorer (we all do that). The IG publisher will use Jekyll internally - you don't need to do anything with it other than have it installed
Joan Harper (Nov 24 2021 at 20:15):
OK. So I am not actually going to use Jekyll - only install it.
Would you be able to send me a sample that I could run through IG Publisher in order to verify that the newer version of Jekyll works with IG Publisher. I don't have anything yet, as I am just starting to learn FSH. I am trying to get the environment fully set up before I really get into it.
Jose Costa Teixeira (Nov 24 2021 at 20:15):
Some time ago I had a portable Jekyll install - i.e. no install
Rob Hausam (Nov 24 2021 at 20:16):
@Joan Harper I'm running into a seemingly similar issue related to ssl when trying to install Jekyll on my new MITRE Macbook Pro. I think it's blocked by the VPN. You may have a similar issue? The IG build process definitely does use Jekyll.
Jose Costa Teixeira (Nov 24 2021 at 20:16):
I can recover the scripts for that portable Jekyll if you want @Joan Harper
Rob Hausam (Nov 24 2021 at 20:16):
I can let you know how I manage to solve it on my end. Or you can try Jose's option.
Joan Harper (Nov 24 2021 at 20:17):
@Rob Hausam I was able to install the newer version without any issues. I just don't have anything that I can use to validate if the newer version works.
Grahame Grieve (Nov 24 2021 at 20:17):
we use https://github.com/FHIR/sample-ig
Grahame Grieve (Nov 24 2021 at 20:17):
for sample testing
Joan Harper (Nov 24 2021 at 20:17):
@Jose Costa Teixeira That would be appreciated.
Joan Harper (Nov 24 2021 at 20:18):
@Grahame Grieve to use that sample, what would I do to run it through the IG publisher?
Grahame Grieve (Nov 24 2021 at 20:21):
see https://confluence.hl7.org/display/FHIR/IG+Publisher+Documentation#IGPublisherDocumentation-UsingFHIRIGPublisher - run it and point it at the folder that you put your local clone of that github repo in
Jose Costa Teixeira (Nov 24 2021 at 20:24):
https://gist.github.com/costateixeira/a427cb57b90d4cbddb6ef957b0ed64ec
Joan Harper (Nov 24 2021 at 20:24):
Thanks @Grahame Grieve .
Now I need to figure out how to make a local clone of a github repository.
I'm beginning to understand why everyone wants to use Simplifier instead of IG Publisher.
Joan Harper (Nov 24 2021 at 20:26):
@Jose Costa Teixeira Thanks. I will try that if the newer version of Jekyll does not work.
Jose Costa Teixeira (Nov 24 2021 at 20:26):
The link above is portable Jekyll. Basically it was a temporary solution so it requires an adaptation to the script as per instructions
Grahame Grieve (Nov 24 2021 at 20:26):
unfortunately, the simplifier mantainers have never done the work to make it possible for HL7 to publish IGs edited in simplifier. So we're stuck with what we have, which does require a set of technical skills around git, yes.
Grahame Grieve (Nov 24 2021 at 20:27):
installing Jekyll is usually straightforward though
Grahame Grieve (Nov 24 2021 at 20:27):
for now, you need a basic git tutorial
Grahame Grieve (Nov 24 2021 at 20:28):
I don't know if anyone has any recommendations for the last worst one of those
Jose Costa Teixeira (Nov 24 2021 at 20:28):
I also don't know why you are looking at ruby 2.0.0... I think Jekyll requires 2.6 or so
Joan Harper (Nov 24 2021 at 20:40):
@Jose Costa Teixeira The instructions that the Confluence page links to are at http://jekyll-windows.juthilo.com/1-ruby-and-devkit/. On that page, it has a screenshot of setting up using Ruby 2.0.0-p481-x64. Then for the DevKit, it says that for Ruby 2.0.0, the file name will begin with DevKit-mingw64.
On Step 2, it said the latest version of Jekyll at the time of writing is v2.4.0
I was following the instructions on that website. It's quite possible that the links on the Confluence page are out of date?
Grahame Grieve (Nov 24 2021 at 20:56):
that page it points to is out of date. Does anyone know of a more recent page?
Grahame Grieve (Nov 24 2021 at 20:58):
no. we should just reference https://jekyllrb.com/docs/installation/windows/
Vassil Peytchev (Nov 24 2021 at 21:03):
The Confluence page seems to be partially out of date. Probably the easiest way to get started would be:
- Install Java SDK
- Install the latest stable Ruby and Jeckyl
- Install Git for Windows
- From the Bash shell that comes with Git for Windows
git clone git@github.com:FHIR/sample-ig.git - reference the IG Guidance, and the Confluence page on how to use _updatePublisher[.bat or .sh] and _genonce[.bat or .sh]
Grahame Grieve (Nov 24 2021 at 21:08):
would you like to add that to the confluence page?
Joan Harper (Nov 24 2021 at 21:37):
@Grahame Grieve I cloned the git repository but I still have questions.
1) which file should I choose? Earlier you said to point to the folder but the 'choose' seems to want a file name.
2) the window that I see when opening the publisher.jar file only has one window, not a left side and right side as shown in the screenshot. It also doesn't have the version number showing at the bottom like the screenshot.
3) where would I expect to see the output from the execute operation, and what format should I expect that output to be in?
This is what I see when I open the publisher.jar
Vassil Peytchev (Nov 24 2021 at 22:29):
@Joan Harper The fastest way to see output of the sample IG is to navigate to the top folder of the cloned git repository, and there run _updatePublisher.bat (answer yes to all prompts) and then run _genonce.bat. if everything works as expected, you will have the IG in the output folder, where you can open index.html in a browser to see the result of the publisher.
Joan Harper (Nov 25 2021 at 15:19):
@Vassil Peytchev Thank you so much.
I was able to verify that the example IG builds correctly and look at the index.html in the browser.
Vassil Peytchev (Nov 26 2021 at 19:44):
I added a Quick Start section on the Confluence Page based on this discussion.
Last updated: Apr 12 2022 at 19:14 UTC
