Docker & Ruby -installation MD update suggestions

[gavinf97]

What is the problem?

Problem Description
When attempting to run the RSQKit local development environment, two main issues were encountered with the setup instructions in INSTALL.md:

Ruby Local Setup Conflict: The guide does not advise on isolating the Ruby environment, leading to potential conflicts with pre-existing system or local Ruby installations.

Docker Container Build Failure: The provided docker-compose up command fails to build the site due to an inability to detect the GitHub repository context required by the remote Jekyll theme.

Suggested Improvements for INSTALL.md
1. Ruby Local Environment Guidance (Isolation)
To ensure a smooth experience and prevent dependency conflicts, the installation guide should recommend using a dedicated environment manager (like Conda) for the Ruby setup.

Recommendation: Add a step recommending the creation and activation of a new Conda environment specifically for the Ruby installation. This should precede the general local setup instructions.

Example Code Snippet to Add:

Bash

Recommended: Create and activate a new Conda environment to avoid conflicts
conda create -n rsqkit_ruby ruby
conda activate rsqkit_ruby

Then proceed with standard Ruby/Jekyll install...

2. Docker Container Fix (Jekyll Remote Theme Error)
The jekyll-remote-theme failed inside the container because it couldn't detect the GitHub repository name (likely due to running outside a standard git clone environment or due to container isolation).

Error Encountered (Log Snippet):

jekyll-1 | Liquid Exception: No repo name found. Specify using PAGES_REPO_NWO environment variables, 'repository' in your configuration, or set up an 'origin' git remote pointing to your github.com repository. in /tmp/jekyll-remote-theme-.../_layouts/page.html
jekyll-1 | ERROR: YOUR SITE COULD NOT BE BUILT:
jekyll-1 | No repo name found. Specify using PAGES_REPO_NWO environment variables, 'repository' in your configuration, or set up an 'origin' git remote pointing to your github.com repository.

Confirmed Solution
A possible fix identified to work on my machine was the need to explicitly define the repository in the Jekyll configuration file (_config.yml). This satisfies the theme’s requirement without relying on git remote detection inside the container.

Location of the problem (optional)

Install.md guidance

[anenadic]

What is the problem?

Problem Description When attempting to run the RSQKit local development environment, two main issues were encountered with the setup instructions in INSTALL.md:

Ruby Local Setup Conflict: The guide does not advise on isolating the Ruby environment, leading to potential conflicts with pre-existing system or local Ruby installations.

Docker Container Build Failure: The provided docker-compose up command fails to build the site due to an inability to detect the GitHub repository context required by the remote Jekyll theme.

Suggested Improvements for INSTALL.md 1. Ruby Local Environment Guidance (Isolation) To ensure a smooth experience and prevent dependency conflicts, the installation guide should recommend using a dedicated environment manager (like Conda) for the Ruby setup.

Recommendation: Add a step recommending the creation and activation of a new Conda environment specifically for the Ruby installation. This should precede the general local setup instructions.

Example Code Snippet to Add:

Bash

Recommended: Create and activate a new Conda environment to avoid conflicts conda create -n rsqkit_ruby ruby conda activate rsqkit_ruby

Then proceed with standard Ruby/Jekyll install...

I'll add a note to create a virtual environment but we intentionally do not provide any code for installation as there are separate documentation pages where instructions are explained in detail. And we also do no recommend how people should install or manage they Rubies.

[kennethrioja]

I was able to reproduce the error by changing the name of the git remote origin (which is the default remote name when we do git clone) to anything else but origin (the command is git remote rename origin anothername

Then indeed, adding repository: EVERSE-ResearchSoftware/RSQKit to _config.yml doesn't trigger the error (what Gavin has done) – even though adding repository: a/b works as well...

This addition of any repository path does not interfere with the way we can pre-visualize on localhost.

Then I would say there are two ways to avoid this Liquid Exception:

1. Rename your origin git repo as origin (git remote -v to see the list of remotes, then git remote rename <old-name> origin
2. Add a repository: EVERSE-ResearchSoftware/RSQKit line to _config.yml (this is the safest and less harming for both users and maintainers)