Investigate use of GitHub Bundler for testing HfLA website locally without Docker

[roslynwythe]

Overview

It would be desirable to have an alternate means for developers to run the HfLA website locally without the use of Docker. In this issue we will investigate the use of Bundler for the installation and execution of Jekyll.

Action Items

• Follow the steps for setting up Ruby and Bundler as outlined in Testing your GitHub Pages site locally with Jekyll
• Follow instructions under "Building Your Site locally", using the Jekyll command found in docker-compose.yml
• Preview the site at http://localhost:4000
• Write up your findings in this issue and in a DR and notify a merge team member for review

Resources/Instructions

• Testing your GitHub Pages site locally with Jekyll
• About GitHub pages and Jekyll
• docker-compose.yml

[github-actions]

Hi @LOSjr4, thank you for taking up this issue! Hfla appreciates you :)

Do let fellow developers know about your:-
i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?)
ii. ETA: (When do you expect this issue to be completed?)

You're awesome!

P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)

[LOSjr4]

Availability: M,T,TH (9AM-1PM)
ETA: By 1PM 4/18

[LOSjr4]

Update:
I ended up installing addition things for it to work but there were two main issues...

1. jekyll kept throwing an error that I needed to add a curly at the beginning of line 4 and then at the end (line 6).
   
2. Doing the above cleared the error and allowed a localhost preview, however it showed the website incorrectly.
   

I want to try to uninstall/reinstall a few things tomorrow to see if it makes a difference before submitting my final report.

[LOSjr4]

Update 5/23/23 THE INFORMATION IN THIS COMMENT IS INCORRECT! This did not solve the problem, it was an uncorrelated temporary fix that did not work while trying to repeat the steps. I no longer believe raw/endraw is relevant to this issue.

This morning I did a google search and luckily found this blogpost https://www.tomordonez.com/curly-braces-markdown-jekyll/ that simply explains and solved my viewing issue.

Basically, because "{{ site.url }}" has double curly braces around them, that part of the code doesn't show up. Adding {%raw%} and {%endraw%} tags before and after enables jekyll to see the code and the localhost preview works as intended.

As you can see I removed the curly braces that I had added in the previous comment and only added {%raw%}/{%endraw%} to the original code. I created a issue branch with that change, but I don't believe I will be making a PR request for this issue to submit my branch, correct?

[LOSjr4]

My install notes: (on a Windows 10 pro)
I used RubyInstaller to add ruby and then restarted my PC
(bundler was confusing but I started making progress from a stack overflow post)
(in bash)
gem install bundler
gem install rails (I question if this was necessary, and some others to be honest, but it worked in the end)
gem install jekyll
gem install jekyll bundler
bundle init
bundle install
bundle add jekyll
bundle exec jekyll serve
bundle add webrick
(I believe I had to address the error pointing to main.scss before bundle exec jekyll serve work show localhost preview. After adding curly braces it showed a flawed(no css) preview)

[roslynwythe]

Hi @LOSjr4 this is great; thank you for solving some tricky problems in your investigation. Could you add to your last comment, the command(s) that a dev would use to build the site? That will be useful if we write a follow-up issue to create a wiki page with instructions. Also, I'm trying to understand the context of the changes you describe in main.scss. Any links to documentation or even slackoverflow links would be helpful. You mentioned that you created an issue branch. I don't think we were expecting a PR for this issue but please advise, what files were committed in that branch?

[LOSjr4]

@roslynwythe
The command to build the site is "bundle exec jekyll serve".
Pressing Ctrl + C stops it (from the original Ruby terminal, Ctrl + C does nothing in a separate bash terminal)

My initial trouble was understanding how to install Bundler. The Bundler website says to type in "bundle install" but the trick was to type "gem" first to call upon Ruby (I suppose) and then add bundler from there.
So in git bash I typed: gem install bundler, gem install rails, gem install jekyll, gem install jekyll bundler
At that point the "bundle" keyword is recognized.
Then I typed: bundle init, bundle install, bundle add jekyll, bundle add webrick, bundle exec jekyll serve

https://stackoverflow.com/questions/10012181/bundle-install-returns-could-not-locate-gemfile the commands I followed can be found halfway down the page)

The only thing added to the main.scss page to make jekyll work was the {%raw%}{%endraw%}(<--THIS PART IS INCCORECT 5/23/23). Differences shown below.

[roslynwythe]

Thank you @LOSjr4 , that comment was very helpful. Please move the issue into the "Questions/In Review" column" and I will find our from Justin our dev lead, how the review should proceed.

[LOSjr4]

@roslynwythe
This is a summary and write up of my findings on why I don't recommend using Bundler.

The main GitHub article posted in this issue regarding Bundler would not install as written.
https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll

I had found a stackoverflow forum that helped with the install process.
https://stackoverflow.com/questions/10012181/bundle-install-returns-could-not-locate-gemfile

The problem with actually testing Bundler is it would constantly put up these two errors

Also when Bundler did work the website preview initially appears broken as shown in previous comments.

Here is a silly way to get it to work consistently. Delete the six dashes at the top of website/assetes/css/main.scss (important first step), save and type 'bundle exec jekyll serve' in the terminal.

The preview will work but broken. Then make about 15 changes and saves, causing Bundler to refresh ~15 times. In my last test I deleted the six dashes, save, then ctrl-z them back, save, about 15 times. After which, the website preview will finally display correctly. Of course this is only temporary because once you close Bundler you would have to go through the same process again AND it still shows ERROR `/assets/css/main.css' not found.

I thought it could be a formatting issue with the way our scss is written. It might also be a issue with Bundler not being able to follow @import "main".

I've researched several of these troubleshooting ideas and I haven't been able to figure it out.

This Bundler testing issue has grown into something more complicated, and Docker seems to work without flaw. That is why I don't believe it is feasible to continue efforts trying to make Bundler work.

[roslynwythe]

Hi @LOSjr4 thank you for the comment outlining your findings. That is exactly what we are looking for, except that I did not realize that now, for feasibility study issues such as this, a DR (Decision Record) should also be written for our wiki. Since the wiki is not fully migrated and ready for editing, you should create another comment in this issue, using this format. This page describes the process to draft and track DRs during this period, until the wiki is ready for editing. Basically all you have to do is copy the link from your draft DR comment and enter it into that page.

I edited the last Action Item to mention the DR and I apologize for the omission. Thank you for your thorough analysis on this issue. I'm going to put the issue back in In Progress. Please move it back to Questions/In Review once the draft DR has been added. Thank you.

[LOSjr4]

DR: Investigate use of GitHub Bundler for testing HfLA website locally without Docker

This is a record in the Decision Records on Solutions Not Implemented.

Issue

• Investigate use of GitHub Bundler for testing HfLA website locally without Docker #4409

Problem Statement

• It would be desirable to have an alternate means for developers to run the HfLA website locally without the use of Docker.

Potential Solution

• Investigate the use of Bundler for the installation and execution of Jekyll.

Feasibility Determination

• Bundler has multiple error issues converting our main.css into a localhost VM preview. Our current use of Docker has proven to be more dependable in comparison.