Installing Jekyll on Ubuntu 24 for Jamulus website development

jekyll-ubuntu.md

Installing jekyll on Ubuntu 24.04 for the Jamulus website

These instructions can be followed to create an Ubuntu VM for working on the Jamulus website.

• Download the live server ISO from Get Ubuntu Server.

• Create a new VM in VirtualBox, and mount the ISO on the CD device.

• Boot the VM. If it already has had an OS installed, press F12 immediately and select boot from CD-ROM.

• Install the standard Server install, not the minimal.

• After installation and reboot, log in as the user that was created during the install.

• Update the packages:

  sudo apt update
  sudo apt upgrade

  Don't worry if some packages are not upgraded "due to phasing".

• Add required packages:

  sudo apt install ruby-full build-essential zlib1g-dev nodejs po4a

• Reboot the VM in case any of the updates require it. Then log in as the user again.

• Add the following lines to the end of .bashrc (this is important):

  # Install Ruby Gems to ~/gems
  export GEM_HOME="$HOME/gems"
  export PATH="$GEM_HOME/bin:$PATH"

  Log out and back in again, or paste those lines into the current shell.

  These settings are necessary so that gem installs packages in the user's own directory instead of trying to install them in a system directory such as /var/lib/gems/3.2.0/cache

• Install Jekyll and Bundler:

  gem install jekyll bundler

  Some items could take a long time to run, as they are compiling code from source. Be patient and have a coffee!

• Get the website repo from Github:

  Either:

  git clone [email protected]:jamulussoftware/jamuluswebsite.git

  Or:

  git clone https://github.com/jamulussoftware/jamuluswebsite.git

  The first version uses ssh, and expects the user's ssh key to have been set up. The second version doesn't need ssh, but may be less convenient if wanting to push changes back.

  Even better is to fork the repository and get it from the fork. Then changes can be pushed back and raised as a PR:

  git clone [email protected]:myusername/jamuluswebsite.git
  cd jamuluswebsite
  git remote add upstream https://github.com/jamulussoftware/jamuluswebsite.git
  git remote -v

• Now remain in the jamuluswebsite directory for the remaining steps.

• Checkout the next-release branch, as that contains the most recent Gemfile:

  git checkout next-release
  

• Rename the Gemfile.lock file, as it is currently locking in old and flawed versions of gems:
  (no longer required if next-release checked out)

• Install all required gems:

  bundle install

• The gem webrick is not installed by default. At the time of writing, it is not specified in Gemfile (this ought to be rectified with a PR). So install it explicitly:
  (no longer required if next-release checked out)

• Before serving or building the site, build the translations:

  _po4a-tools/po4a-create-all-targets.sh

  I noticed a couple of warnings about unclosed HTML tags. These should be investigated if not fixed already.

• The site is now ready to serve:

  bundle exec jekyll serve --host=0.0.0.0

  The --host=0.0.0.0 enables the site to be browsed from a different host. Without that, the Jekyll server will listen just on localhost (127.0.0.1).

  The server listens by default on port 4000. --port=N can be used to specify a different port.

  Ignore the error that says ** ERROR: directory is already being watched! **

• Now it should be possible to browse to the site under test at http://vm.ip.address:4000

• If any modifications are made or a different branch checked out (e.g. next-release), go back and repeat the _po4a-tools/... step above.

Just to add that --port=<some number other than 80> is useful syntax to know if you've already got port 80 in use.

OK, for me, the full process (on a box already running Ubuntu Server 24.04 LTS fully updated):

1. sudo apt install ruby-full build-essential zlib1g-dev nodejs po4a.
2. Add GEM_HOME and $GEM_HOME/bin to PATH to .bashrc, more or less as above (as GEM_HOME exists, use it 😃), log out/in.
3. Clone the repo (or update in my case).
4. No need to move Gemfile or run bundle add webrick - already sorted.
5. _po4a-tools/po4a-create-all-targets.sh.
6. bundle exec jekyll serve --host=0.0.0.0 --port 8098 (as my port 80 is in use).

jekyll serve defaults to port 4000, not 80.

Yes, I need to update the document now that Gemfile is up to date and includes webrick. -- DONE