Troubleshooting

Problems running `bundle install` or `bundle update`#

If you have a problem running bundle install or bundle update one potential problem is that the version of Ruby on your system is too old (the Jekyll theme requires Ruby v3.0.0 or later). Try running ruby --version and see what version you’re using.

Bundler could not find compatible versions for gem “jekyll-autoprefixer-re”#

In mid-May 2022, one of the gems we depend on dropped off rubygems (see this for discussion). As a result, bundle install on a new machine may now throw the following error:

Fetching gem metadata from https://rubygems.org/..........
Resolving dependencies...
Bundler could not find compatible versions for gem "jekyll-autoprefixer-re":
  In Gemfile:
    jekyll-plugins-anu was resolved to 2.2.0, which depends on
      jekyll-autoprefixer-re

Could not find gem 'jekyll-autoprefixer-re', which is required by gem
'jekyll-plugins-anu', in rubygems repository https://rubygems.org/ or installed
locally.

The quickest fix for this is add the GitHub repo for that gem to the :jekyll_plugins group in your site’s Gemfile like so:

group :jekyll_plugins do
  ## other stuff goes here... you can leave it alone
  ## ...
  ##
  ## adding this line is the important part
  gem "jekyll-autoprefixer-re", :git => "git@gitlab.anu.edu.au:jekyll-anu/gems/jekyll-autoprefixer-re.git", :branch => "master"
end

We’re (Ben and co.) investigating a better solution—that gem is important for the browser compatibility stuff it does, but it does seem to be withering on the vine, so there may a better maintained solution out there. We’ll update these instructions if a better option comes to light.

Note: if you’ve got a cached version of the jekyll-autoprefixer-re gem then you’ll be fine until you blow away said cache. Even if your local setup is borked, the latest docker build image (docker.io/anucecsit/anu-jekyll-build:v2.2.0) still has the dep cached. Still, that’s not a great situation to be in—so the suggested fix is still recommended.

How to fix “Page Not Found (404)” when deployed?#

There could be many causes for this. If a particular page is showing up when served locally but failing to show up when deployed with a Page Not Found (404), then check that your permalink in the header of the file has a trailing slash, e.g.,:

---
title: Seminar
permalink: /deliverables/seminar/
---

How to fix “Forbidden Access (403)” when deployed?#

There could be many causes for this.

If your website passes the build and deploy pipeline checks, then update your site. Usually this is caused from an out-of-date .gitlab-ci.yml file. Make sure that the BUILD_DIR and and DEPLOY_DIR are as follows:

BUILD_DIR: $STAGING_DIR/$CI_PIPELINE_ID/$CI_COMMIT_REF_NAME/$CI_PROJECT_PATH
DEPLOY_DIR: $STAGING_DIR/$CI_JOB_ID/$CI_COMMIT_REF_NAME

Alternatively, this can be caused by an incorrect permalink. All permalinks require a trailing slash: permalink: /assignments/ not permalink: /assignments

My website is taking a very long time to build/deploy#

Check for any videos and large files stored on your website. If you have any large files contact the Computing Facilities Team for an alternative solution. In the meantime, in the .gitlab-ci.yml file, set the GIT_DEPTH variable to 1 or an appropriately small number. The current default depth is 1000, so overriding this will should speed up your CI build/deploy.

variables:
  GIT_DEPTH: 1