Jekyll

Lightweight Alpine-based container for building and serving Jekyll static sites with live reload support.

Verify this image

Every build ships a Sigstore-signed SBOM and a full Trivy scan — verify them yourself, no login required:

gh attestation verify oci://ghcr.io/oorabona/jekyll:latest --owner oorabona

Full walkthrough (SBOM payload, Trivy findings, multi-arch manifest inspection, upstream dependency tracking) → https://oorabona.github.io/docker-containers/verify-images/

Quick Start

Docker Run

# Serve a site with live reload
docker run --rm -it \
  -v "$(pwd):/site" \
  -p 4000:4000 \
  -p 35729:35729 \
  ghcr.io/oorabona/jekyll:latest

# Build only (no server)
docker run --rm \
  -v "$(pwd):/site" \
  ghcr.io/oorabona/jekyll:latest \
  build

# Build to custom destination
docker run --rm \
  -v "$(pwd):/site" \
  ghcr.io/oorabona/jekyll:latest \
  build --destination /site/public

Docker Compose

services:
  jekyll:
    image: ghcr.io/oorabona/jekyll:latest
    ports:
      - "4000:4000"
      - "35729:35729"
    volumes:
      - ./site:/site
    command: ["serve", "--host", "0.0.0.0", "--livereload", "--force_polling"]

Then run:

docker compose up

Site available at: http://localhost:4000

The Compose profile runs with uid/gid 1000 by default, matching the image’s jekyll user. To keep bind-mounted files owned by your host account, pass your numeric identity explicitly:

LOCAL_UID="$(id -u)" LOCAL_GID="$(id -g)" docker compose up

With rootless Podman, container uids are remapped, so uid 1000 in the container is not your host account and cannot write the bind mount (Permission denied @ dir_s_mkdir - /site/.jekyll-cache). Map your host identity into the container instead:

podman run --rm --userns=keep-id -v "$(pwd):/site" ghcr.io/oorabona/jekyll:latest build

Features

• Ruby 3.3 on Alpine Linux (minimal footprint)
• Jekyll 4.4.1 with live reload
• Bundler for dependency management
• Node.js for JavaScript processing
• Pre-installed plugins:
  • jekyll-feed - RSS/Atom feed generation
  • jekyll-seo-tag - SEO optimization meta tags
  • jekyll-sitemap - XML sitemap generation
• WebRick server included
• Git support for themes and plugins

Build Arguments

All dependency versions are pinned for reproducible builds:

Ports

Volumes

Mount your Jekyll site directory to /site:

-v "$(pwd):/site"

Directory Structure

your-site/
├── _config.yml          # Jekyll configuration
├── _posts/              # Blog posts
├── _layouts/            # HTML templates
├── _includes/           # Reusable components
├── assets/              # CSS, JS, images
├── Gemfile              # Additional gem dependencies
└── _site/               # Generated output (auto-created)

Using a Gemfile

The container does not run bundle install. For gems the image does not ship, see Adding Custom Dependencies.

Security

Volume Permissions

The image runs as the non-root jekyll user (uid/gid 1000), and /site is writable by that user. Its HOME and Ruby/Bundler cache locations use /tmp, which is writable even when Docker runs the image with an arbitrary numeric uid that has no passwd entry. For a bind mount, use your host uid/gid so generated files remain owned by your account:

# Run as the host user
docker run --user "$(id -u):$(id -g)" \
  -v "$(pwd):/site" \
  ghcr.io/oorabona/jekyll:latest build

Production Deployment

For serving Jekyll sites in production:

1. Build static files locally:

   docker run --rm -v "$(pwd):/site" ghcr.io/oorabona/jekyll:latest build
   

2. Serve with a dedicated web server: Use nginx, Apache, or a CDN to serve the _site/ directory. The Jekyll container is intended for development only.

Network Security

• Bind to 127.0.0.1 for local-only access:

  -p 127.0.0.1:4000:4000
  

• Never expose port 4000 to the public internet
• Use environment-specific _config.yml files to prevent sensitive data leaks

Dependencies

All Ruby gem versions are pinned and monitored for updates:

Adding Custom Dependencies

The image installs its gems at build time and runs as a non-root user, so it does not install a site’s Gemfile. To add gems, extend the image:

FROM ghcr.io/oorabona/jekyll:latest
USER root
RUN gem install jekyll-theme-cayman jekyll-redirect-from jemoji
USER jekyll

Architecture

jekyll/
├── Dockerfile           # Alpine-based build
├── config.yaml          # Dependency versions
├── version.sh           # Upstream version checker
├── docker-compose.yml   # Local development setup
└── README.md            # This file

Build Process

The Dockerfile uses a single-stage build:

1. Start from ruby:{RUBY_VERSION}-alpine{ALPINE_VERSION}
2. Install build dependencies (build-base, git, nodejs)
3. Install Jekyll and plugins at pinned versions
4. Remove build dependencies to reduce image size
5. Set working directory to /site
6. Configure default command: serve --host 0.0.0.0 --livereload

Building Locally

# Build with default versions
./make build jekyll

# Build with specific Jekyll version
./make build jekyll 4.4.1

# Build with custom arguments
docker build \
  --build-arg JEKYLL_VERSION=4.4.0 \
  --build-arg RUBY_VERSION=3.2 \
  -t jekyll:custom .

Version Management

# Check current version
cd jekyll && ./version.sh

# Check latest upstream version
cd jekyll && ./version.sh latest

# JSON output for automation
cd jekyll && ./version.sh --json

Links

• Jekyll Documentation: https://jekyllrb.com/docs/
• Docker Hub: https://hub.docker.com/r/oorabona/jekyll
• GitHub Container Registry: https://ghcr.io/oorabona/jekyll
• Source Repository: https://github.com/oorabona/docker-containers
• Issue Tracker: https://github.com/oorabona/docker-containers/issues