Deploying Jekyll on Hop3¶

This guide deploys with the build-on-server strategy — Hop3 runs the generator on each deploy. For the concepts and the alternative (build your site at the source and deploy the assets), see the Static Sites overview.

This guide walks you through deploying a Jekyll static site on Hop3. Jekyll is a simple, blog-aware static site generator, powering GitHub Pages.

Prerequisites¶

Before you begin, ensure you have:

A Hop3 server - Follow the Installation Guide
The Hop3 CLI - Installed on your local machine
Ruby 3.0+ - Install via your package manager
Jekyll - Install with gem install jekyll bundler
Git - For version control and deployment

Installing Ruby and Jekyll¶

# macOS (Homebrew)
brew install ruby
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
gem install jekyll bundler

# Ubuntu/Debian
sudo apt install ruby ruby-dev build-essential
gem install jekyll bundler

# Verify installation
jekyll -v

Verify your local setup:

ruby -v

jekyll -v 2>&1 || echo "Jekyll version check"

Step 1: Install Jekyll and Create Site¶

Install Jekyll and Bundler if not already installed:

gem install jekyll bundler --no-document 2>&1 | tail -5 || echo "Jekyll installation completed"

Add gem binary path to PATH and verify Jekyll is available:

export PATH="$(ruby -e 'puts Gem.user_dir')/bin:$PATH" && jekyll -v

Create a new Jekyll site:

export PATH="$(ruby -e 'puts Gem.user_dir')/bin:$PATH" && jekyll new hop3-tuto-jekyll

New jekyll site installed

Install dependencies:

bundle install

Bundle complete!

Step 2: Configure the Site¶

Update _config.yml:

title: My Jekyll Site
description: A Jekyll site deployed on Hop3
baseurl: ""
url: "https://hop3-tuto-jekyll.example.com"

# Build settings
markdown: kramdown
theme: minima

# Exclude from build
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor

# Plugins
plugins:
  - jekyll-feed
  - jekyll-seo-tag

Step 3: Create Content¶

Update the home page:

---
layout: home
title: Welcome to Hop3!
---

Your Jekyll site is running on Hop3.

Jekyll is a simple, blog-aware static site generator perfect for personal projects, documentation, and blogs.

Create an about page:

---
layout: page
title: About
permalink: /about/
---

## About This Site

This Jekyll site demonstrates static site deployment on Hop3.

### Features

- **Simple** - Write in Markdown
- **Blog-aware** - Built-in support for posts
- **Customizable** - Liquid templates and themes

Create a blog post:

---
layout: post
title: "Hello World"
date: 2024-01-01 12:00:00 -0000
categories: blog
---

Welcome to our Jekyll site on Hop3!

## Getting Started

Create new posts in the `_posts` directory:

_posts/YYYY-MM-DD-title.markdown

Jekyll will automatically process them into your site.

Step 4: Build and Test¶

Build the site:

bundle exec jekyll build

done in

Verify the build:

ls -la _site/

index.html

Test locally:

bundle exec jekyll serve &
APP_PID=$!
sleep 5
curl -s http://localhost:4000/ | head -5 || echo "Test completed"
kill "$APP_PID" 2>/dev/null || true

html

Step 5: Create Deployment Configuration¶

# Pre-build: Install gems and build site
prebuild: bundle install && bundle exec jekyll build

# Serve static files
web: npx serve _site -l $PORT

[metadata]
id = "hop3-tuto-jekyll"
version = "1.0.0"
title = "Hop3 Tutorial - Jekyll"

[build]
before-build = ["bundle install", "bundle exec jekyll build"]
packages = ["ruby", "ruby-dev", "nodejs", "npm"]

[run]
start = "npx serve _site -l $PORT"

[port]
web = 3000

[healthcheck]
path = "/"
timeout = 30
interval = 60

Deploy to Hop3¶

The following steps require a Hop3 server.

Initialize (First Time Only)¶

hop3 init --ssh root@your-server.example.com

Deploy¶

Deploy the application (first deployment creates the app):

hop3 deploy hop3-tuto-jekyll

deployed successfully

Set Hostname¶

Configure the hostname for nginx proxy:

hop3 config set --app hop3-tuto-jekyll HOST_NAME=hop3-tuto-jekyll.$HOP3_TEST_DOMAIN

Apply Configuration¶

Redeploy to apply the hostname configuration:

hop3 deploy hop3-tuto-jekyll

deployed successfully

Verify Deployment¶

hop3 app status --app hop3-tuto-jekyll

hop3-tuto-jekyll

curl -s http://hop3-tuto-jekyll.$HOP3_TEST_DOMAIN/ | head -10

html

Managing Your Application¶

# Restart the application
hop3 app restart --app hop3-tuto-jekyll

# View logs
hop3 app logs --app hop3-tuto-jekyll

# View/set environment variables
hop3 config show --app hop3-tuto-jekyll
hop3 config set --app hop3-tuto-jekyll NEW_VAR=value

# Scale workers
hop3 ps scale --app hop3-tuto-jekyll web=2

Advanced Configuration¶

Custom Theme¶

# Use a gem-based theme
bundle add just-the-docs

# Or use remote theme (GitHub Pages compatible)
# In _config.yml:
remote_theme: pmarsceill/just-the-docs

Collections¶

# _config.yml
collections:
  docs:
    output: true
    permalink: /docs/:path/

Pagination¶

# _config.yml
plugins:
  - jekyll-paginate

paginate: 10
paginate_path: "/blog/page:num/"

Drafts¶

# Create drafts in _drafts/
# Build with drafts:
bundle exec jekyll build --drafts

Multilingual¶

# _config.yml
defaults:
  - scope:
      path: ""
      type: "pages"
    values:
      lang: "en"

Adding Search (Lunr.js)¶

# _config.yml
plugins:
  - jekyll-lunr-js-search

Troubleshooting¶

Gem Errors¶

Update bundler:

gem update bundler
bundle update

Build Failures¶

Check Ruby version:

ruby -v
# May need: rbenv install 3.2.0

Missing Posts¶

Ensure date in filename matches frontmatter.

Example hop3.toml¶

[metadata]
id = "hop3-tuto-jekyll"
version = "1.0.0"
title = "My Jekyll Site"

[build]
before-build = ["bundle install", "JEKYLL_ENV=production bundle exec jekyll build"]
packages = ["ruby", "ruby-dev", "nodejs", "npm"]

[run]
start = "npx serve _site -l $PORT -s"

[port]
web = 3000

[healthcheck]
path = "/"

Complete Procfile¶

prebuild: bundle install && JEKYLL_ENV=production bundle exec jekyll build
web: npx serve _site -l $PORT -s