If you're looking for a maintained alternative to this repository

[Oliboy50]

Why

I'm writing this issue just because I used this Docker image before (thank you Starefossen ❤️, you did a great job here), but now it does not work anymore for me... So I found a well maintained alternative that I wanted to share with other folks in this situation.

Requirements

A recent pages-gem Docker image must be available on your computer:

git clone [email protected]:github/pages-gem.git
cd pages-gem
make image
cd ..
rm -rf pages-gem

Go to your project directory to run your website locally

docker run -it --rm \
    -p 4000:4000 \
    -v $(pwd):/src/site \
    gh-pages jekyll serve --watch --force_polling -H 0.0.0.0 -P 4000

[jgroenen]

Until yesterday used starefossen, but now I get a segmentation fault because of arm. Guess because of an update. Trying this solution, I get an error "cannot load such file", because "webrick is not part of the default gems since Ruby 3.0.0. Install webrick from RubyGems."

[pmarinova]

This is how I use the pages-gem docker image:

1. Build a recent github-pages image

git clone https://github.com/github/pages-gem
cd pages-gem
git checkout v229
docker build -t gh-pages .

2. Run the github-pages image from the root of the site

docker run --rm -it \
    -p 4000:4000 \
    -v ${PWD}:/src/site \
    gh-pages \
    sh -c "bundle install && jekyll serve -H 0.0.0.0 -P 4000"

In order for this to work a Gemfile like this is required in the site root:

source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
gem 'webrick', '~> 1.8'

The explicit dependency on webrick is required since the docker image in v229 was updated to Ruby 3.

[sohang3112]

@pmarinova I tried the instructions you suggested - built gh-pages docker and modified Gemfile, but got the following error when I ran the docker run command in my site's root folder:

Bundler 2.5.9 is running, but your lockfile was generated with 2.5.7. Installing Bundler 2.5.7 and restarting using that version.
Fetching gem metadata from https://rubygems.org/.
Fetching bundler 2.5.7
Installing bundler 2.5.7
Fetching gem metadata from https://rubygems.org/.........
Resolving dependencies...
(... removed Fetching & Installing messages ...)
Bundle complete! 16 Gemfile dependencies, 95 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
/usr/local/bundle/gems/bundler-2.5.7/lib/bundler/runtime.rb:304:in `check_for_activated_spec!': You have already activated base64 0.2.0, but your Gemfile requires base64 0.1.1. Since base64 is a default gem, you can either remove your dependency on it or try updating to a newer version of bundler that supports base64 as a default gem. (Gem::LoadError)
        from /usr/local/bundle/gems/bundler-2.5.7/lib/bundler/runtime.rb:25:in `block in setup'
        from /usr/local/bundle/gems/bundler-2.5.7/lib/bundler/spec_set.rb:191:in `each'
        from /usr/local/bundle/gems/bundler-2.5.7/lib/bundler/spec_set.rb:191:in `each'
        from /usr/local/bundle/gems/bundler-2.5.7/lib/bundler/runtime.rb:24:in `map'
        from /usr/local/bundle/gems/bundler-2.5.7/lib/bundler/runtime.rb:24:in `setup'
        from /usr/local/bundle/gems/bundler-2.5.7/lib/bundler.rb:162:in `setup'
        from /usr/local/bundle/gems/jekyll-3.9.5/lib/jekyll/plugin_manager.rb:50:in `require_from_bundler'
        from /usr/local/bundle/gems/jekyll-3.9.5/exe/jekyll:11:in `<top (required)>'
        from /usr/local/bundle/bin/jekyll:25:in `load'
        from /usr/local/bundle/bin/jekyll:25:in `<main>'

This is my Gemfile:

source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
gem 'webrick'
gem 'jemoji'

I tried adding gem update bundler && at the start of the sh command in docker run but that didn't work - the same error came.

Also tried running with this Dockerfile:

FROM gh-pages
WORKDIR /src/site
ADD Gemfile .
COPY . .
RUN bundle install
EXPOSE 4000
CMD jekyll serve -H 0.0.0.0 -P 4000

But that also didn't work:

$ docker build -t my-blog .
$ docker run --rm -it -p 4000:4000 -v ${PWD}:/src/site my-blog
Resolving dependencies...
/usr/local/lib/ruby/3.3.0/bundler/definition.rb:596:in `materialize': Could not find nokogiri-1.16.3-x86_64-linux, racc-1.6.2, i18n-1.14.4, rexml-3.2.5, activesupport-7.1.3.2, concurrent-ruby-1.2.3, base64-0.1.1, bigdecimal-3.1.3, drb-2.1.1, minitest-5.16.3, mutex_m-0.1.2, ffi-1.16.3, rb-inotify-0.10.1 in cached gems or installed locally (Bundler::GemNotFound)
        from /usr/local/lib/ruby/3.3.0/bundler/definition.rb:203:in `specs'
        from /usr/local/lib/ruby/3.3.0/bundler/definition.rb:270:in `specs_for'
        from /usr/local/lib/ruby/3.3.0/bundler/runtime.rb:18:in `setup'
        from /usr/local/lib/ruby/3.3.0/bundler.rb:162:in `setup'
        from /usr/local/bundle/gems/jekyll-3.9.5/lib/jekyll/plugin_manager.rb:50:in `require_from_bundler'
        from /usr/local/bundle/gems/jekyll-3.9.5/exe/jekyll:11:in `<top (required)>'
        from /usr/local/bundle/bin/jekyll:25:in `load'
        from /usr/local/bundle/bin/jekyll:25:in `<main>'

Adding the mentioned gems (eg. nokogiri, racc, etc.) to Gemfile also had no effect - the same error came again.

Do you have any idea how this issue can be solved??

[pmarinova]

@pmarinova I tried the instructions you suggested - built gh-pages docker and modified Gemfile, but got the following error when I ran the docker run command in my site's root folder:

Bundler 2.5.9 is running, but your lockfile was generated with 2.5.7. Installing Bundler 2.5.7 and restarting using that version.
.........

@sohang3112 Have you tried deleting the Gemfile.lock file and starting it clean?

[mikecole]

This is how I use the pages-gem docker image:

1. Build a recent github-pages image

git clone https://github.com/github/pages-gem
cd pages-gem
git checkout v229
docker build -t gh-pages .

2. Run the github-pages image from the root of the site

docker run --rm -it \
    -p 4000:4000 \
    -v ${PWD}:/src/site \
    gh-pages \
    sh -c "bundle install && jekyll serve -H 0.0.0.0 -P 4000"

In order for this to work a Gemfile like this is required in the site root:

source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
gem 'webrick', '~> 1.8'

The explicit dependency on webrick is required since the docker image in v229 was updated to Ruby 3.

What would this look like using docker compose?

[pmarinova]

@mikecole, thanks for suggesting to use a docker compose file, here it is:

services:
  gh-pages:
    build:
      context: https://github.com/github/pages-gem.git#v231
      dockerfile: Dockerfile.alpine
    command: sh -c "bundle install && jekyll serve -H 0.0.0.0 -P 4000"
    ports:
      - "4000:4000"
    volumes:
      - "./:/src/site"

Place this in a compose.yaml file at the root of your site and simply run docker compose up.

Make sure to delete your Gemfile.lock file and start clean if you are upgrading to a newer version of the pages-gem.

[mikecole]

@pmarinova Confirmed, this worked for me. Thank you!

I did slightly modify the command: command: sh -c "bundle install && jekyll serve --watch --force_polling -H 0.0.0.0 -P 4000"

[beeradmoore]

Just curious from those who have made the change, is it still working for you?

I put compose.yaml in my docs folder which is what my GitHub Pages is,

services:
  gh-pages:
    build:
      context: https://github.com/github/pages-gem.git#v232
      dockerfile: Dockerfile
    command: sh -c "bundle install && jekyll serve --watch --force_polling -H 0.0.0.0 -P 4000"
    ports:
      - "4000:4000"
    volumes:
      - "./:/src/site"

and I run that I get the output of,

gh-pages-1  | fatal: not a git repository (or any of the parent directories): .git
gh-pages-1  | Bundle complete! 9 Gemfile dependencies, 125 gems now installed.
gh-pages-1  | Use `bundle info [gemname]` to see where a bundled gem is installed.
gh-pages-1  | Configuration file: /src/site/_config.yml
gh-pages-1  |             Source: /src/site
gh-pages-1  |        Destination: /src/site/_site
gh-pages-1  |  Incremental build: disabled. Enable with --incremental
gh-pages-1  |       Generating...
gh-pages-1  |       Remote Theme: Using theme pages-themes/slate
gh-pages-1  |                     done in 2.183 seconds.
gh-pages-1  |                     Auto-regeneration may not work on some Windows versions.
gh-pages-1  |                     Please see: https://github.com/Microsoft/BashOnWindows/issues/216
gh-pages-1  |                     If it does not work, please upgrade Bash on Windows or run Jekyll with --no-watch.
gh-pages-1  |  Auto-regeneration: enabled for '/src/site'
gh-pages-1  |     Server address: http://0.0.0.0:4000
gh-pages-1  |   Server running... press ctrl-c to stop.

Unsure if that fatel error is a problem as I am in a subdirectory. "Auto-regeneration may not work on some Windows versions." appears to be resolved according that github issue. Also I am using Windows Terminal directly, not WSL. (Though I am unsure if docker itself runs via WSL in that case)

If I save a file I see regeneration working,

gh-pages-1  |       Regenerating: 1 file(s) changed at 2024-09-08 05:15:30
gh-pages-1  |                     index.md
gh-pages-1  |       Remote Theme: Using theme pages-themes/slate
gh-pages-1  |                     ...done in 0.262281949 seconds.

But the rendered site is just the markdown fed into it and being served back to me 😅

I have also tried to use the alpine and non-alpine versions above, as well as v232 and v231. All seem to just serve my static site.

Am I missing something?

[pmarinova]

@beeradmoore, I had the same issues and finally realized this docker image is intended for development of the github-pages gem itself, whereas my case is to simply run a github-pages site locally. I am now using the latest version of the github-pages gem from rubygems like this: https://gist.github.com/pmarinova/0b345a2656abe079c322ad0a90a32c61

See also https://github.com/github/pages-gem/issues/891

[beeradmoore]

Thanks for the info @pmarinova

I copied your Dockerfile.alpine locally and combined it with my compose.yaml

services:
  gh-pages:
    build:
      dockerfile: Dockerfile.alpine
    ports:
      - "4000:4000"
    volumes:
      - "./:/src/site"

When I tried to use this I got an error of

Liquid Exception: No such file or directory - git in /_layouts/default.html

Looking up that error lead me here with someone saying git is not on the system path.

I modified your Dockerfile.alpine to install git (I assumed it would have been in build-base)

RUN apk update && apk add --no-cache make build-base git

This eventually got it to run with the output,

gh-pages-1  | Configuration file: /src/site/_config.yml
gh-pages-1  | To use retry middleware with Faraday v2.0+, install `faraday-retry` gem
gh-pages-1  |             Source: /src/site
gh-pages-1  |        Destination: /src/site/_site
gh-pages-1  |  Incremental build: disabled. Enable with --incremental
gh-pages-1  |       Generating...
gh-pages-1  |       Remote Theme: Using theme pages-themes/slate
gh-pages-1  | fatal: not a git repository (or any parent up to mount point /src)
gh-pages-1  | Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
gh-pages-1  |    GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
gh-pages-1  |                     done in 1.697 seconds.
gh-pages-1  |                     Auto-regeneration may not work on some Windows versions.
gh-pages-1  |                     Please see: https://github.com/Microsoft/BashOnWindows/issues/216
gh-pages-1  |                     If it does not work, please upgrade Bash on Windows or run Jekyll with --no-watch.
gh-pages-1  |  Auto-regeneration: enabled for '/src/site'
gh-pages-1  |     Server address: http://0.0.0.0:4000
gh-pages-1  |   Server running... press ctrl-c to stop.

But as before, its just serving up my markdown pages back to me.

EDIT: Nevermind, this was probably always working. I was going to http://localhost:4000/index.md (see above screenshot 😅). Going to http://localhost:4000/index.html shows the correct site

EDIT 2: I had to add some other stuff to re-generate my site. I also updated ruby to 3.3.4 to match versions listed here. Here is the setup I have now,

Dockerfile.alpine

FROM ruby:3.3.4-alpine

RUN apk update && apk add --no-cache make build-base git

COPY Gemfile .

RUN bundle install

WORKDIR /src/site

CMD ["jekyll", "serve", "--watch", "--force_polling", "--host", "0.0.0.0", "-P", "4000"]

compose.yaml

services:
  gh-pages:
    build:
      dockerfile: Dockerfile.alpine
    ports:
      - "4000:4000"
    volumes:
      - "./:/src/site"

Gemfile

source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
gem 'webrick', '~> 1.8'

[pmarinova]

Thanks, @beeradmoore. To be honest, I never got into too much detail about the Ruby/Jekyll setup as all I wanted was to be able to test a very simple site. So my version of the Dockerfile is the absolute minimum setup. I was actually surprised that I couldn't find any info about setting it up with a container. Perhaps someone will share a more detailed explanation of it.

[mrmanc]

A while ago I published the built Docker image from my fork of https://github.com/github/pages-gem, so you can use this to get a site up and running simply by using this in your docker-compose.yml:

services:
  github-pages:
    volumes:
      - '${PWD}/docs/:/src/site/'
    ports:
      - '4000:4000'
    image: markcrossfield/pages-gem:231-alpine

You should then be able to run docker compose up to build and serve your GitHub Pages site. I checked with GitHub, but they consider their repo to be unsupported, and so have no plans to publish their own image.

[sohang3112]

A while ago I published the built Docker image from my fork of https://github.com/github/pages-gem

Thanks @mrmanc - that should be useful!

[beeradmoore]

@mrmanc , unfortunatly that didn't work. The webserver came up, but only gave me a file list but would never create the hosting files.

I am unsure if the problem is because of this warning,

github-pages-1 | Auto-regeneration may not work on some Windows versions. github-pages-1 | Please see: https://github.com/Microsoft/BashOnWindows/issues/216 github-pages-1 | If it does not work, please upgrade Bash on Windows or run Jekyll with --no-watch.

or because of

! github-pages The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64/v3)

Ironically I usually use macOS (as arm64), but this particular project is Windows only so I am normally wirting docs on my Windows machine 😅