Skip to content

Home

Jump to bottom
Eric Vennemeyer edited this page Aug 18, 2022 · 4 revisions

Welcome to the Hack for LA ghpages-docker Wiki!

This wiki provides some brief context around why we created our own Docker image for the Website team, as well as a technical explanation of how the Dockerfile works, and how and when the image can be updated as needed in the future. It is intended as a guide for any HFLA volunteers who may find they need to modify this Docker image, but have no prior experience in how to do so.

How does the Hack for LA Website team use Docker?

Developers on the Hack for LA Website team use Docker to run local instances of hackforla.org, the organization’s official website. In this case, Docker is used purely to spin up a Jekyll server on a dev’s computer so they can make changes to the site’s code and see the effects without having to first push those changes to the main repo.

When starting a Docker container to run a local copy of the website, devs use the docker compose up command, which tells Docker to look through a docker-compose.yml file in the root of the website directory for configuration options. This is what that file looks like at the time of this writing:

version: "3"
services:
  hfla_site:
    image: hackforlaops/ghpages:latest
    container_name: hfla_site
    command: jekyll serve --force_polling --livereload --config _config.yml,_config.docker.yml -I
    environment:
      - JEKYLL_ENV=docker
    ports:
      - 4000:4000
      - 35729:35729
    volumes:
      - .:/srv/jekyll

Note the image: key near the top, just under hfla_site. This tells Docker which image to use when creating a new container. It will first look on the user's local drive to see if the image already exists and, if it doesn't, will download it from the Docker Hub registry.

Why does Hack for LA need its own Docker image?

In April 2022, new volunteers joining the HFLA Website team began to experience an error when running docker compose up that prevented a container from being created. (See the original issue for more details.) The image we had been using for several years prior, jekyll/jekyll:pages, came from the official Jekyll Docker repo and was supposed to be designed specifically for use with GitHub Pages sites. It was eventually determined that an update in the Jekyll Docker Dockerfile had led to versions of Ruby and Jekyll being installed in that image which inherently conflicted with each other, and which did not match the versions being used by GitHub Pages.

After considering various options (See this issue for more info), it was decided the best way forward would be to create a custom Docker image that HFLA could update as needed, and which would be hosted on a Hack for LA repo on Docker Hub. This would have the benefit of providing a Docker image that matched all the dependency versions used by GitHub Pages without forcing the organization to rely on externally-created images that weren't always regularly maintained.

This new image is called ghpages-docker. It's built from the Dockerfile contained in this repo, and is hosted at hackforlaops on Docker Hub.

When would ghpages-docker need to be updated?

Because the purpose of ghpages-docker is to mimic the GitHub Pages server environment on a local computer, it will need to be updated whenever GitHub Pages' dependency versions are updated. We'll go into more detail about how the Dockerfile works here, but for now it's important to know that there are two specific pieces of software that need to be manually kept up to date: Ruby and the github-pages Ruby gem.

The Ruby version is specified at the very top of the Dockerfile, in the form of another Docker image using a lightweight distribution of Linux called Alpine, and again at the beginning of the second build stage. The github-pages version is not specified--when the image is built, it automatically installs the latest version. This is handy, because the github-pages gem bundles all of the other dependencies required by GitHub Pages apart from Ruby.

How do you update ghpages-docker?

If GitHub Pages changes either the version of Ruby or the version of the github-pages gem that it uses, the ghpages-docker image will need to be rebuilt and pushed to Docker Hub. The procedure for this varies slightly depending on which software needs updating.

If the version of Ruby has changed:

  1. Search the official Ruby image repo on Docker Hub for a Ruby image tag that matches the new Ruby version number. The tags follow the format <Ruby_Version>-<Alpine_Version>. For example, at the time of this writing, GitHub pages uses Ruby 2.7.3, and the image tag is 2.7.3-alpine3.13. The Alpine version number doesn't necessarily have to be 3.13--if in doubt, go with the latest release version that still matches the correct Ruby version.
  2. In the ghpages-docker Dockerfile, find the following code near the top: (The specific image tag may be different by the time you're reading this, but the important thing is to find the line that reads FROM <Ruby_Image> AS build.)
###
### BUILD STAGE 1
###

...

FROM ruby:2.7.3-alpine3.13 AS build
  1. Replace the image tag after FROM with the new tag you found in step 1.
  2. Find the following code for Build Stage 2 in the middle of the Dockerfile and replace the image tag there, as well:
###
### BUILD STAGE 2
###

FROM ruby:2.7.3-alpine3.13
  1. Push the updated Dockerfile to the ghpages-docker repo. This will automatically trigger a GitHub action to rebuild and push the updated image to Docker Hub.

If the version of the github-pages gem has changed:

No update to the Dockerfile is necessary in this case, because the github-pages gem is installed without a version number specified. This means that any time the image is rebuilt, the latest version of github-pages will be installed automatically. So, when github-pages changes, all we need to do is rebuild the image with the following steps:

  1. Navigate to the Actions tab in the menu at the top of the ghpages-docker repo.
  2. In the list of workflows on the left, click the Publish Docker Image workflow.
  3. Click the Run Workflow button on the right. This will manually trigger the GitHub action to rebuild and push the image.

Looking for a more detailed explanation of the contents of the Dockerfile?

You can find a walkthrough here.

Helpful Links and References

Clone this wiki locally