Developer and Contribution Guide

This page describes how to build, test, and contribute to Jekyll Docker. It explains the project's repository structure, templating engine, and build workflows.

---

Repository Directory Layout

Understanding the repository layout helps you find the correct files when making changes:

├── repos/
│   ├── jekyll/             # Base template and configuration
│   │   ├── Dockerfile      # Shared template Dockerfile
│   │   ├── opts.yml        # Base configuration, packages and gems
│   │   └── copy/           # Scripts copied into /usr/jekyll/bin/
│   ├── builder/            # Builder variant (inherits Dockerfile from base)
│   │   └── opts.yml        # Deployment packages and gems
│   └── minimal/            # Minimal variant (inherits Dockerfile from base)
│       └── opts.yml        # Stripped-down packages and gems
├── script/
│   ├── build               # Compiles and builds local images
│   ├── deploy              # Deploys images to Docker Hub
│   └── sync                # Synchronizes development files
└── opts.yml                # Global build configurations and aliases

---

Understanding the Templating Engine

Rather than maintaining multiple separate Dockerfiles, this project uses the docker-template gem. This tool processes a master template file and generates target Dockerfiles based on flavor-specific configurations.

Template Syntax in Action

In repos/jekyll/Dockerfile, you will find template blocks like this:

FROM <%= @meta.base_image %>
...
<% if @meta.packages? %>
  RUN apk --no-cache add <%= @meta.packages %>
<% end %>

When the compiler runs, it reads the properties defined in opts.yml (such as base_image and packages) and evaluates the ERB template blocks to generate a clean, final Dockerfile for each target flavor.

---

Local Development Workflows

Follow these steps to set up your environment, generate the Dockerfiles, and build your images locally.

1. Install Dependencies

Install the required build-time gems listed in the Gemfile:

bundle install

2. Compile Templates and Build Images

To compile the Dockerfiles and build your local containers, run the provided build script:

# Compile and build all variants locally
script/build

# Compile and build a specific variant tag
export DOCKER_REPO="jekyll/jekyll:latest"
script/build "$DOCKER_REPO"

This script runs the docker-template build command under the hood. It processes your configurations, generates the flavor-specific Dockerfiles, and runs a standard docker build with --squash optimization flags.

3. File Synchronization

This repository keeps its standard developer files (like linting configurations and CI scripts) synchronized with an upstream repository using the script/sync tool:

# Run the sync script to pull down shared environment updates
script/sync "ruby" "false"

The first argument defines the primary language ecosystem (ruby), while the second determines if external developer patterns are skipped.