Preview GitHub Pages content locally with Docker and Visual Studio Code - 2nd Update

Introduction

This is a short update for the older article about previewing GitHub Pages content locally with Docker and Visual Studio Code and its update. It uses a non-root user by default now.

Changes

In the earlier versions of the Dockerfile the -y (short version of --yes) was missing in the apt upgrade command so that it didn’t perform package upgrades.
The devcontainer.json has also been updated and uses a non-root user devcontainer by default now. This is achieved through a Dev Container Features called “Common Utilities (common-utils)”. To still get root privileges in the container, one can use sudo or change the remoteUser variable in the devcontainer.json file to root.

Dockerfile

The first step is to create (or re-use) the Dockerfile that specifies your development environment. The GitHub Pages documentation describes the prerequisites and dependencies for GitHub Pages. This information is contained in the following Dockerfile:

# Create a GitHub Pages container with the required Jekyll dependencies from a Debian Bullseye image with Ruby

# Currently GitHub requires Ruby 2.7.x, see https://pages.github.com/versions/
FROM ruby:2.7-bullseye

# Update image
RUN apt update && apt upgrade -y

# Update dependency manager and install GitHub Pages and its dependencies
RUN gem update bundler && gem install github-pages

WORKDIR /var/www/

EXPOSE 4000

CMD [ "jekyll", "serve", "--livereload", "--force_polling", "-H", "0.0.0.0", "-P", "4000" ]

# usage without development containers:
# docker run -it --rm -v "$PWD":/var/www -p "4000:4000" <image_name>

Additionally it defines that the website content inside the Docker container should be put into /var/www/, that it exposes port 4000 for communicating with the HTTP server and that the default executing command is to start Jekyll. The --livereload flag adds some JavaScript to your page so that you don’t need to refresh the page manually while doing changes. It refreshes it automatically when you save an edited file but you need also need to expose port 35729 (but I’m not sure if it’ll always be this port so I left it out).

Visual Studo Code

Using remote development with Visual Studio Code requires a .devcontainer folder with a devcontainer.json file that contains the instructions for your development environment. The file below provides the configuration for Jekyll with enabled live reload since it doesn’t need to rebuild the Docker image if the port changed, you simply adapt it in the devcontainer.json if required. Additionally it installs git thus it is possible to use source code management from within your editor.

// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
// https://github.com/microsoft/vscode-dev-containers/tree/v0.241.1/containers/alpine
{
	"name": "Jekyll for GitHub Pages",
	"build": {
		"dockerfile": "Dockerfile"
	},

	// Use 'forwardPorts' to make a list of ports inside the container available locally.
	"forwardPorts": [4000, 35729],

	// 'postAttachCommand' to run a command each time a tool has successfully attached to the container.
	"postAttachCommand": [ "jekyll", "serve", "--livereload", "--force_polling", "-H", "0.0.0.0", "-P", "4000" ],

    "customizations": {
        // Configure properties specific to VS Code.
        "vscode": {
            // IDs of extensions you want installed when the container is created.
            "extensions": [
                // jekyll and liquid templating syntax highlighting
                "sissel.shopify-liquid",
                // markdown
                "yzhang.markdown-all-in-one",
                "DavidAnson.vscode-markdownlint",
                // editing
                "streetsidesoftware.code-spell-checker",
            ]
        }
      },

    // A set of simple and reusable Features. Quickly add a language/tool/CLI to a development container.
    "features": {
        "ghcr.io/devcontainers/features/common-utils:2": {
            "installZsh": "true",
            "upgradePackages": "true",
            "username": "devcontainer",
            "userUid": "1000",
            "userGid": "1000"
        },
        // Install an up-to-date version of Git.
        "ghcr.io/devcontainers/features/git:1": {
            "version": "os-provided"
        }
    },

    // Set `remoteUser` to `root` to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
    "remoteUser": "devcontainer"
}

Conclusion

Several Dockerfiles and write-ups are available but none used the correct requirements as stated by GitHub Pages. They were written some time ago and are therefore outdated/no longer maintained.
Thus we have here a new version that is current at the moment.

Sources

Visual Studio Code - Code Editing. Redefined
Docker
Remote - Containers - Visual Studio Marketplace
GitHub Pages Documentation - GitHub Docs
Jekyll • Simple, blog-aware, static sites | Transform your plain text into static websites and blogs
VSCode, Docker, and Github Pages
Debian “bullseye” Release Information

Bi0T1N's GitHub Page

Some (hopefully) useful information