ODK-X Website

This repository is home to the ODK-X homepage.

Table of Contents

• ODK-X Website
  • Table of Contents
  • Installing requirements
    • MacOS, Linux
    • Windows
  • Running the website
  • Contributing
  • Troubleshooting
    • Permissions
    • Nokogiri

Installing requirements

The ODK-X website is built with Ruby and below are the installation steps we recommend for getting a Ruby environment that will work best with the ODK-X website.

MacOS, Linux

1. Installing rbenv

   MacOS: Installation instructions using Homebrew can be found in the rbenv documentation. This is the preferred method for MacOS. To install rbenv without Homebrew, refer to the Linux instructions.

   Linux: The rbenv-installer is a script which idempotently installs or updates rbenv on your system.

2. Installing Ruby

   Once rbenv has been installed, install the latest Ruby (currently 2.7.2):

   rbenv install 2.7.2
   

Windows

1. Windows users should use RubyInstaller.

Running the website

1. Follow the instructions in the contribution guide to fork the website repository and then clone your fork.

2. Configure your project to use the correct version of Ruby.

   a. Navigate to the root directory of your project.

   cd /MY/DEVELOPMENT/DIRECTORY/website
   

   b. Set the local application-specific Ruby version by using rbenv-local.

   rbenv local 2.7.2
   

   c. Verify that your project is using Ruby version 2.7.2:

   ruby -v
   

3. Install bundler.

gem install bundler

4. Install this project.

bundle install

5. Launch the server. The site will update as changes are made.

bundle exec jekyll serve

Contributing

One quick way to contribute is to review the website and file issues documenting the problems you see. If you would like to help fix those issues, see the contribution guide.

Troubleshooting

Permissions

If you encounter the following error: You don't have write permissions for the /var/lib/gems/x.x.x directory. then please review the installation instructions to make use of rbenv.

Only root has write permissions for /var/lib; using sudo for subsequent gem install comands won't work, and changing permissions for that directory using chmod is considered dangerous. This issue is avoided when using rbenv.

Nokogiri

Nokogiri (鋸) is a Rubygem providing HTML, XML, SAX, and Reader parsers with XPath and CSS selector support.

The installation command bundle install tries to install nokogiri.

If you face following error: Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

You can fix it as follows:

For Ubuntu/Debian OS: Run the command sudo apt-get install build-essential patch ruby-dev zlib1g-dev liblzma-dev and try again.

If you are using any other OS, you can follow the instructions mentioned here: http://www.nokogiri.org/tutorials/installing_nokogiri.html