Ably's use of Jekyll deployed on Heroku:

To get up and running on a Mac:

  • I've now captured the installation in a Mac installation script
    • You can find it here
    • Scroll down a bit to the set of commands headed "Install Ruby and Jekyll and everything needed to support the Jekyll wiki site"
    • It's basically these commands (some of which might be redundant / overkill, I'm not sure):
# Install ruby-install
brew install ruby-install
# Install chruby 
brew install chruby
source /usr/local/share/chruby/chruby.sh
source /usr/local/share/chruby/auto.sh
# Install ruby
ruby-install ruby 2.6.5
# Make the Ruby version stick at ruby 2.6.5
chruby ruby-2.6.5
# Install bundler
gem install bundler
bundle install
# Install jekyll
gem install bundler jekyll
# Install heroku CLI (needs sudo pw)
curl https://cli-assets.heroku.com/install.sh | sh
  • Here are my original notes:
    • clone the repo containing the jekyll site (currently clare-wiki-jekyll)
    • install git
    • install ruby and jekyll and heroku stuff: https://blog.heroku.com/jekyll-on-heroku
      • NB: Change those instructions slightly:
      • Instead of ruby-install ruby, use ruby-install to install the same Ruby version as specified in Gemfile, like this: ruby-install ruby 2.6.5
    • MacOS Catalina has the wrong version of Ruby - see Ruby Version Stuff

Deploying jekyll using heroku: https://blog.heroku.com/jekyll-on-heroku

  • Clare-specific notes available here (accessible to Clare only).
  • In Ubuntu 16:
    • I followed the instructions for getting ruby-install and chruby to get latest Ruby version
      • prob not necessary though, as I forgot I'd alrteady installed Ruby.
      • and it took ages!
    • I got an error saying "chruby: command not found" when I ran the command chruby ruby
      • I fixed this by adding these two lines to ~/.bashrc:
      • source /usr/local/share/chruby/chruby.sh
      • source /usr/local/share/chruby/auto.sh
    • MacOS Catalina has the wrong version of Ruby - see Ruby Version Stuff
    • Then I installed Heroku CLI: curl https://cli-assets.heroku.com/install.sh | sh
    • When I ran the bundle command to install rake, I had to add some permissions:
      • sudo chown -R claresudbery:claresudbery /home/claresudbery/.bundle

Deploying ruby using heroku

Creating a site with Jekyll

Useful Jekyll Stuff:

Ruby Version Stuff

When I had problems running jekyll on command line (GitBash, Windows) after installing jekyll using gem install jekyll bundler

  • Updated ruby version in .ruby-version
  • Ran bundle install
  • Then prefixed all jekyll commands with bundle exec - eg bundle exec jekyll -v and bundle exec jekyll build

MacOS Catalina has the wrong version of Ruby

  • MacOS Catalina has the wrong version of Ruby, so I ran ruby-install ruby 2.6.5
    • ... but I still got an error "Your Ruby version is 2.6.3, but your Gemfile specified 2.6.5" on MacOS
    • So I ran gem install bundler and then bundle install, and that fixed it.
    • I also did some other stuff previously, but I'm pretty sure none of it made any difference:

Ruby version problems when deploying with Heroku

  • I got an error on heroku deploy at one point:
  • "Your Ruby version is 2.5.1, but your Gemfile specified 2.6.5"
  • It turned out this was because I had checked in Gemfile with the new Ruby version, but hadn't checked in Gemfile.lock

Using ruby-install with a specific Ruby version

  • Instead of ruby-install ruby, you can use ruby-install to install the same Ruby version as specified in Gemfile, like this: ruby-install ruby 2.6.5

Favicon Stuff

Favicon showing up in Google Chrome

Error: favicon.ico not found

Css/layout not the same locally as remote

  • Stored relevant files in C:\Users\CLARE\Downloads\images\BigIndex
  • See screenshots: Local-layout.PNG and Remote-layout.PNG
  • Html and search js are identical (see files in same folder)
  • But _site/assets/main.css are slightly different. See local-main.css and remote-main.css
  • It turns out this happened because of the Windows ming stuff that finds its way into Gemfile.lock if you run jekyll serve from GitBash.
  • The solution is to remove all the lines in Gemfile.lock that contain the ming thing.
  • Otherwise Heroku complains about Gemfile.lock having been created by Windows, and somehow the dependencies get mucked up on the server.
  • If it happens again, fix Gemfile.lock by running the bundle command in Ubuntu and then pushing the resulting Gemfile.lock up to the server.

Keeping a file in git without tracking changes

Issue with site layout caused when you push Gemfile.lock changes

  • Issue: The search box appears top left instead of top right
  • Cause: Every time you run jekyll serve (js) in GitBash, extra windows stuff gets added to Gemfile.lock which is fine locally but doesn't work remotely.
  • Solution: Revert any pushed changes to Gemfile.lock
  • Prevention: Never push changes to Gemfile.lock. I have a shortcut alias set up - just run discard Gemfile.lock on command line before changes are staged.

Jekyll installation for windows

  • Here: https://jekyllrb.com/docs/installation/windows/
  • First I installed the Windows subsystem for linux (WSL)
  • Then I basically ran all the following commands (see below for some of the explanation):
    • sudo apt update && sudo apt upgrade
    • sudo apt-get update -y && sudo apt-get upgrade -y
    • sudo apt-get install libgdbm-dev
    • sudo apt-get install libpng-dev
    • sudo apt-add-repository ppa:brightbox/ruby-ng
    • sudo apt-get update
    • sudo apt-get install ruby2.5 ruby2.5-dev build-essential dh-autoreconf
    • sudo chown -R claresudbery /var/lib/gems/2.5.0/
    • sudo chown -R claresudbery /usr/local/bin
      • (!! Those sudo chown commands are to get round the permissions errors you get otherwise when you run the next command (gem update))
    • gem update
    • gem install jekyll bundler
  • Then I got permission errors when trying to run bundle exec jekyll serve
  • Then localhost simply not accessible from browser
    • Someone with similar problem here: https://github.com/microsoft/WSL/issues/2471
    • I gave up in the end. I now run jekyll serve from GitBash, but do everything else in Ubuntu.
    • Sadly this does mean that Gemfile.lock keeps getting Windows-related stuff added to it, that breaks things if I push it up to Heroku.
  • https://docs.microsoft.com/en-gb/windows/wsl/install-win10?redirectedfrom=MSDN
  • When I followed the jekyll instructions, I got the following errors when I ran sudo gem update (immediately after sudo apt-get install ruby2.5 ruby2.5-dev build-essential dh-autoreconf):
    • ERROR: Error installing dbm: ERROR: Failed to build gem native extension. checking for -lgdbm... no
    • ERROR: Error installing gdbm: ERROR: Failed to build gem native extension. checking for gdbm_open() in -lgdbm... no
    • ERROR: Error installing zlib: ERROR: Failed to build gem native extension.
      • checking for deflateReset() in -lz... no
      • checking for deflateReset() in -llibz... no
      • checking for deflateReset() in -lzlib1... no
      • checking for deflateReset() in -lzlib... no
      • checking for deflateReset() in -lzdll... no
      • checking for deflateReset() in -lzlibwapi... no
    • They were all followed by the following:
      • extconf.rb failed
      • Could not create Makefile due to some reason, probably lack of necessary libraries and/or headers.
      • Check the mkmf.log file for more details. You may need configuration options.
    • The mkmf.log files were available here:
      • /var/lib/gems/2.5.0/extensions/x86_64-linux/2.5.0/dbm-1.1.0/mkmf.log
      • /var/lib/gems/2.5.0/extensions/x86_64-linux/2.5.0/gdbm-2.1.0/mkmf.log
      • /var/lib/gems/2.5.0/extensions/x86_64-linux/2.5.0/zlib-1.1.0/mkmf.log
    • I found this article for a similar problem: https://github.com/zendesk/zendesk_apps_tools/issues/245
      • Based on that and a bit of deduction / experimentation, I ran these lines:
        • sudo apt-get install libgdbm-dev
        • sudo apt-get install libpng-dev
      • Then I ran sudo gem update again and all was good.

Viewing heroku logs:

  • Runtime logs via Command line
  • Build logs Via web UI
    • Click pipeline, then clare-wiki, then Activity, View build logs under a build
  • Clare-specific notes available here (accessible to Clare only).

Downloading individual files from GitHub

  • You'll find you often get told to download individual files from GitHub when using plugins etc.
  • But GitHub doesn't easily allow that via its UI.
  • Click on the file in GitHub UI, then click Raw, then copy the url
  • Now use this command on command line in root of your project (this one was going to _plugins folder, you might need to tweak):
    curl -L https://raw.githubusercontent.com/shigeya/jekyll-category-archive-plugin/master/_plugins/category_archive_plugin.rb > _plugins/category_archive_plugin.rb

OmniAuth vulnerability

  • Before doing any auth stuff, check whether there is still a vulnerability in OmniAuth (see alert here or check the front page of the clare-wiki-ably repo in GitHub - the alerts show up there (but NOT in notifications)

Error on jekyll serve: "invalid byte sequence in UTF-8 included in /_layouts/default.html"

The full error: Liquid Exception: Liquid error (C:/development/clare-wiki-ably/_includes/toc.html line 35): invalid byte sequence in UTF-8 included in /_layouts/default.html jekyll 3.7.4 | Error: Liquid error (C:/development/clare-wiki-ably/_includes/toc.html line 35): invalid byte sequence in UTF-8 included

The problem

It turned out this was caused by a particular line of text in a markdown file (pages\coding\infra\security\oauth.md). I found it by using the equivalent of Saff squeeze (same concept as binary search algorithm) to identify the commit that caused the problem (it was commit 77698c8 on 20/4/20, "New content from Cadogan notes"). I then used the same technique to narrow down the problematic line of text. I used "View | Show symbol | Show all characters" in Notepad++ to ty and see what the problem was and there was nothing visible.

The fix

I tried running dos2unix on that file, but it didn't work. Then agian, I ran it in GitBash. Should I have run it in Linux? Anyway, in the end I fixed it by manually typing out the same words again, removing the original text. So it's a bit of a mystery!

Error on jekyll serve: "warn_for_outdated_bundler_version"

Full error: C:/RailsInstaller/Ruby2.3.3/lib/ruby/gems/2.3.0/gems/bundler-1.15.3/lib/bundler/lockfile_parser.rb:108:in `warn_for_outdated_bundler_version': You must use Bundler 2 or greater with this lockfile. (Bundler::LockfileError)

I ran bundle install and that told me to run gem install bundler, which worked.