Skip to content

INSTALL.md

Latest commit

 

History

History
87 lines (55 loc) · 3.94 KB

INSTALL.md

File metadata and controls

87 lines (55 loc) · 3.94 KB

Local Installation

NOTE: it is not necessary to install and run RSQKit locally to make contributions to it - check our Contribution Guidelines for details.

The RSQKit website is automatically built and deployed whenever changes are merged into the main branch of this repository. For every pull request, a preview version of the resulting site will be generated by Netlify. Therefore, it is generally not necessary to install the RSQKit locally and contributions can be made via GitHub interface too.

Nevertheless, if you do wish to run the RSQKit website locally for development and testing purposes, please follow the instructions below.

We provide instructions for installing RSQKit and all the software necessary to run it directly on you machine or within a Docker container.

Running RSQKit locally using Jekyll

Prerequisites: ruby, bundler and jekyll.

The RSQKit uses Jekyll to generate the website based on the files and information located in this repository. Jekyll is a Ruby gem which can be installed on most systems.

To install Ruby, follow the Ruby installation instructions for your operating system. You will also need Bundler (a gem to manage other Ruby gems on your system) - but it is usually preinstalled with modern distributions of Ruby.

To install Jekyll, follow the official installation instructions.

Managing Ruby environment

It is recommended to install a Ruby version and environment (package) manager tool. This is to ensure that each Ruby project (including RSQKit) you are working on has an isolated version of Ruby and required Ruby gems (dependencies).

There are several Ruby environment manager tools to chose from - use the one of your choice. If you have not used one before - try rbenv.

Installing and running RSQKit locally

After successfully installing ruby, bundler and jekyll, clone the RSQKit repository on your machine (e.g. using SSH):

git clone git@github.com:EVERSE-ResearchSoftware/RSQKit.git

Navigate to RSQKit folder.

cd RSQKit

Create your Ruby environment for the RSQKit project (using whatever tool you selected for this).

Next, install the RSQKit's dependencies:

bundle install

You can build and run the RSQKit locally using the following command from within the RSQKit folder:

bundle exec jekyll serve

You should now be able to access your local copy of RSQKit on http://127.0.0.1:4000.

Installing RSQKit using a Docker container

Prerequisites: docker and docker-compose.

To install a Docker engine locally, follow the official installation instructions. Docker Compose is available natively on Docker Desktop, as a Docker Engine plugin, and as a standalone tool - check Compose installation instructions for your setup.

We provide docker-compose.yml file for RSQKit container to help you set up.

After successfully setting up docker and docker-compose, run the following commands.

docker-compose build
docker-compose up

You should now be able to access your local copy of RSQKit on http://127.0.0.1:4000.

If you experience a message error like jekyll-1 | Liquid Exception: No repo name found., it might be that Jekyll cannot find the origin Git remote pointing to your github.com repository. To fix this error, you can either:

  • Rename your local Git remote to origin. Do git remote -v to see the list of remotes, then git remote rename <old-name-current-repo> origin, or
  • Add repository: EVERSE-ResearchSoftware RSQKit line to _config.yml.

Then re-run the previous two docker-compose commands.
⚡