docker-jekyll

Run jekyll in a Docker container without installing jekyll on your host system.

This is mainly intended for trying out GitHub Pages locally before committing them.

How To Serve Existing GitHub Pages

If you already have your GitHub Pages checked out in a local directory ~/my-proj, do the following:

1. Run the docker image with your GitHub Pages mapped to /home/jekyll/doc-root

   docker run -v ~/my-proj:/home/jekyll/doc-root -t -i fstab/jekyll
   

   or, if you are using boot2docker

   docker run -v ~/my-proj:/home/jekyll/doc-root -p 4000:4000 -t -i fstab/jekyll
   

2. Go to the doc-root directory

   cd /home/jekyll/doc-root
   

3. Update jekyll.

   If you have a Gemfile in your GitHub Pages, run

   sudo bundle update
   

   If you don't use Gemfile, run

   sudo gem update github-pages
   

4. Serve your project

   jekyll serve --host=0.0.0.0 --force_polling
   

You can access the jekyll pages on the docker container's IP address, port 4000, or on boot2docker's IP address, port 4000.

Make it a Single Command

The commands above are a lot to type. Fortunately, all of them can be put in a single line:

docker run -v ~/my-proj:/home/jekyll/doc-root -p 4000:4000 -t -i fstab/jekyll bash -c 'cd /home/jekyll/doc-root; sudo bundle update; jekyll serve --host=0.0.0.0 --force_polling'

If you are using the bash shell, you can create an alias for that line like this:

alias jekyll="docker run -v ~/my-proj:/home/jekyll/doc-root -p 4000:4000 -t -i fstab/jekyll bash -c 'cd /home/jekyll/doc-root; sudo bundle update; jekyll serve --host=0.0.0.0 --force_polling'"

Now, the whole thing can be run as

jekyll

How To Create New GitHub Pages

1. Start the Docker container and go to /home/jekyll/doc-root as described above.

2. Generate a new jekyll site

   jekyll new ~/doc-root
   

3. Create a file called Gemfile with the following content:

   source 'https://rubygems.org'
   gem 'github-pages'
   

4. Update

   sudo bundle update
   

5. Add the following line to the end of the generated _config.yml to stop Jekyll including the Gemfile in it’s site.

   exclude: ['Gemfile','Gemfile.lock']
   

6. Serve your project, as described above

Building the Docker Image from Source

1. Make sure Docker is installed.

2. Clone fstab/docker-jekyll from GitHub.

   git clone https://github.com/fstab/docker-jekyll.git
   

3. Build the docker image

   cd docker-jekyll
   docker build -t="fstab/jekyll" .