Install and Configure Jekyll on Ubuntu 22.04 | Easy Setup

By Posted on

Install and Configure Jekyll on Ubuntu 22.04 | Easy Setup

This tutorial aims to guide you through the process of installing and configuring Jekyll on Ubuntu 22.04. Jekyll is a powerful static site generator that takes plain text files (Markdown, HTML, CSS, etc.) and transforms them into complete, static websites, ideal for blogs and informational sites.

Jekyll’s seamless integration with Git and GitHub workflows makes it a natural choice for developers already familiar with these tools. Being written in Ruby, you’ll encounter Ruby-specific terminology like "Gems" during the setup.

Follow the steps below to set up the Jekyll Site Generator on Ubuntu 22.04.

Before you begin, ensure you have the following prerequisites:

  • A server running Ubuntu 22.04.
  • A non-root user with sudo privileges.
  • A basic firewall configured.

If you haven’t already, you can set these up by following a guide on Initial Server Setup with Ubuntu 22.04.

1. Install Ruby For Jekyll Site Generator

As Jekyll is a Ruby-based application, Ruby needs to be installed on your Ubuntu 22.04 server.

First, update your package lists:

sudo apt update

Next, install Ruby and the necessary build tools:

sudo apt install make build-essential ruby ruby-dev

Verify the Ruby installation by checking its version:

ruby -v
**<mark>Output</mark>**
ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-linux-gnu]

2. Set up Jekyll on Ubuntu 22.04

With Ruby installed, the next step is to configure the Ruby Gems environment and then install Jekyll itself.

Configure Ruby Gems Path

You need to configure the Ruby Gems installation path to avoid permission issues and keep your system clean. Open your .bashrc file with your favorite text editor (e.g., vi, nano). Here, we use vi:

vi ~/.bashrc

Add the following lines to the end of the file:

# Install Ruby Gems to ~/.gems
export GEM_HOME=$HOME/gems
export PATH=$HOME/gems/bin:$PATH

Save the changes and close the file. Then, apply the changes to your current session:

source ~/.bashrc

Install Jekyll Site Generator

Now you can use the gem command to install Jekyll and Bundler:

gem install jekyll bundler
**<mark>Output</mark>**
Successfully installed bundler-2.4.3
Parsing documentation for bundler-2.4.3
Installing ri documentation for bundler-2.4.3
Done installing documenation for bundler after 0 seconds
28 gems installed

Configure Firewall for Jekyll

By default, Jekyll serves its site on port 4000. You need to allow traffic on this port through your firewall. Use the following command to open port 4000:

sudo ufw allow 4000

Reload the firewall to activate the new rule:

sudo ufw reload

3. Create a New Development Site with Jekyll

Now, let’s create a new Jekyll site to test the installation.

Navigate to your home directory and create a new site:

# cd ~
# jekyll new <mark>demo-site</mark>
**<mark>Output</mark>**
New jekyll site installed in /root/demo-site.

To inspect the created site’s directory structure, install the tree utility and then use it:

# sudo apt install tree
# tree <mark>demo-site</mark>
**<mark>Output</mark>**
demo-site
├── 404.html
├── about.markdown
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.markdown
└── _posts
    └── 2023-01-07-welcome-to-jekyll.markdown

1 directory, 7 files

Run Web Server with Jekyll

Jekyll can monitor the files in your site directory and automatically generate a static site whenever changes are made.

Navigate to your site directory and start the Jekyll server:

# cd ~/demo-site
# bundle add webrick
# jekyll serve --host=<mark>your-host-ip-address</mark>

Note: If you don’t specify a host, Jekyll will serve the site on localhost.

**<mark>Output</mark>**
Auto-regeneration: enabled for '/root/demo-site'
    Server address: http://ip-address:4000/
  Server running... press ctrl-c to stop.

When the above command is executed, Jekyll will use configurations and content in the directory _site.

tree ~/demo-site
**<mark>Output</mark>**
/root/demo-site
├── 404.html
├── about.markdown
├── _config.yml
├── Gemfile
├── Gemfile.lock
├── index.markdown
├── _posts
│   └── 2023-01-07-welcome-to-jekyll.markdown
└── _site
    ├── 404.html
    ├── about
    │   └── index.html
    ├── assets
    │   ├── main.css
    │   ├── main.css.map
    │   └── minima-social-icons.svg
    ├── feed.xml
    ├── index.html
    └── jekyll
        └── update
            └── 2023
                └── 01
                    └── 07
                        └── welcome-to-jekyll.html

9 directories, 15 files

You can also run the Jekyll server in the background:

jekyll serve --host=<mark>host-ip</mark> > /dev/null 2>&1 &

Access Jekyll Site

Access the site in your web browser by navigating to:

http://<mark>IP_Adrress</mark>:4000

You should see the Jekyll Welcome page.

Jekyll welcome page site
Jekyll Site Generator

Now, let’s add a new post to your Jekyll site on Ubuntu 22.04.

Create a Sample Post

Posts are stored in the _posts directory with a specific naming convention:

YEAR-MONTH-DAY-title.MARKUP

For example, to create a "Hello World" post:

vi ~/demo-site/_posts/2023-01-07-hello-world-blog.md

Add the following content to the file:

---
layout: post
title:  "Hello World!"
---

# Welcome

**Hello world**, this is my first Jekyll blog post.

I hope you like it!@OrcaCoreTeam

Save the file. Refresh your Jekyll site, and you’ll see the new post:

Jekyll Post

Click on the post to view its content:

Post Content

Conclusion

You have successfully installed and configured the Jekyll Site Generator on Ubuntu 22.04. You have also learned how to create a new site and add a sample post to it.

Enjoy building your static website!

Here are some other articles you might find helpful:

Alternative Solutions for Setting Up Jekyll on Ubuntu 22.04

While the above method is straightforward, here are two alternative approaches to consider:

1. Using Docker

Docker provides a containerized environment, simplifying the setup process and ensuring consistency across different systems.

Explanation:

Instead of directly installing Ruby and Jekyll on your host machine, you can use a pre-built Docker image that contains all the necessary dependencies. This eliminates potential conflicts with existing Ruby installations or system libraries. It also makes it easier to deploy your Jekyll site to different environments, as the Docker image encapsulates everything required to run the site.

Steps:

  1. Install Docker: If you don’t have Docker installed, follow the official Docker documentation for Ubuntu 22.04.

  2. Use a Jekyll Docker Image: There are several Jekyll Docker images available on Docker Hub. A popular one is the official jekyll/jekyll image.

  3. Run the Jekyll Container: Use the following command to run the container, mounting your Jekyll site directory to the container’s /srv/jekyll directory:

    docker run --volume="$PWD:/srv/jekyll" -p 4000:4000 jekyll/jekyll jekyll serve --host 0.0.0.0

    This command does the following:

    • --volume="$PWD:/srv/jekyll": Mounts your current directory (where your Jekyll site files are) to the /srv/jekyll directory inside the container.
    • -p 4000:4000: Maps port 4000 on your host machine to port 4000 inside the container.
    • jekyll/jekyll: Specifies the Docker image to use.
    • jekyll serve --host 0.0.0.0: Starts the Jekyll server inside the container, making it accessible from outside the container.

  4. Access Your Site: Open your web browser and navigate to http://<your-server-ip>:4000.

Benefits:

  • Isolation: Prevents conflicts with other software on your system.
  • Reproducibility: Ensures consistent behavior across different environments.
  • Simplified Deployment: Easily deploy your Jekyll site to any environment that supports Docker.

2. Using Ruby Version Manager (RVM) or rbenv

RVM and rbenv are tools that allow you to manage multiple Ruby versions on a single system. This is particularly useful if you’re working on multiple projects that require different Ruby versions.

Explanation:

Instead of using the system-wide Ruby installation, RVM or rbenv allows you to install and manage Ruby versions in isolated environments. This prevents conflicts between different projects and ensures that each project has the correct Ruby version and gem dependencies.

Steps (using RVM as an example):

  1. Install RVM: Follow the official RVM installation instructions.

    gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
curl -sSL https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm

  2. Install a Ruby Version: Install a specific Ruby version using RVM:

    rvm install 3.0.2 # or another version
rvm use 3.0.2

  3. Install Jekyll: Install Jekyll and Bundler within the RVM environment:

    gem install jekyll bundler

  4. Create and Serve Your Jekyll Site: Follow the same steps as in the original tutorial to create and serve your Jekyll site.

Benefits:

  • Ruby Version Management: Easily switch between different Ruby versions.
  • Isolated Environments: Prevents conflicts between projects.
  • Simplified Dependency Management: Ensures that each project has the correct gem dependencies.

Both of these alternative solutions offer advantages over the basic installation method, depending on your specific needs and preferences. Using Docker provides the highest level of isolation and reproducibility, while RVM/rbenv offer more flexibility in managing Ruby versions. Choose the solution that best fits your workflow and requirements.

Related posts: