Installation and Tagging Reference

Jekyll Docker images are distributed through Docker Hub. This guide describes how to pull these images, understand the version pinning logic, and select the appropriate base layer.

Basic Pull Instructions

Ensure your target host has a running container runtime (such as Docker Engine, Docker Desktop, or Podman). Pull the image that corresponds to your development or production pipeline stage:

# Pull the standard development image (aliases to 4.2.2)
docker pull jekyll/jekyll:latest

# Pull the CI/CD-focused builder image
docker pull jekyll/builder:latest

# Pull the stripped-down production/minimal image
docker pull jekyll/minimal:latest

Tagging Philosophy & Release Strategy

The repository manages version tracking dynamically through template variables defined in opts.yml. This decouples the maintenance of individual Dockerfiles from upstream Jekyll releases.

Version Mappings and Aliases

To maintain API stability, rolling tags point to tested releases. In the current release tier, several common tags are mapped as aliases to enforce version consistency:

  • latest → Aliased to 4.2.2
  • stable → Aliased to 4.2.2
  • 4.0 → Aliased to 4.2.2
  • 4 → Aliased to 4.2.2

By referencing jekyll/jekyll:4 or jekyll/jekyll:stable, you receive the latest tested minor and patch revisions of the Jekyll 4.x engine, protecting your pipelines from unexpected breakages associated with major framework updates.

The GitHub Pages Engine (pages tag)

GitHub Pages runs a highly specific, restricted subset of gems and engines. To emulate this local deployment target accurately, Jekyll Docker provides a dedicated pages image stream:

  • pages → Pins Jekyll to 3.8.5 (and pre-installs github-pages alongside jekyll-github-metadata).
  • Use Case: Pull this tag if you are deploying directly to GitHub Pages and want to prevent compilation mismatches between your local machine and GitHub's processing servers.

Base OS Selection & Alpine Implications

All flavors of Jekyll Docker are built atop an Alpine Linux distribution (ruby:3.1.1-alpine3.15 as specified in the master opts.yml). This base image offers several advantages and technical trade-offs:

Advantages

  • Reduced Footprint: Alpine Linux images are significantly smaller than Debian or Ubuntu equivalents, reducing download times and bandwidth overhead on CI runners.
  • Security Profiles: Alpine's small package footprint reduces the overall vulnerability attack surface.

Technical Trade-offs & Musl Libc

  • C Extensions: Alpine uses musl libc instead of the more common GNU C Library (glibc). While standard Ruby gems compile successfully, certain complex gems that rely on precompiled binary wheels or specific C-standard layouts may require compilation from source.
  • Compilation Speed: The first time you install gems with native extensions in the container, compilation may take longer because the extensions must compile against Alpine's libraries. To mitigate this, configure a persistent gem volume as shown in the Configuration & Customization Guide.