Installing Jekyll on Alpine Linux and serving the static site with Nginx

Jul 4, 2023

This article will guide you on hosting a static site on an Alpine Linux distro. Jekyll will generate the site, and Nginx will serve it. My goal when starting this project was to have a fully functioning static site hosted on my home server. Resource usage is the most essential part of this project.

My home server is not the most powerful, so I need the hosting container to be as light as possible. Glad to say that I achieved the goal. Here’s my resource usage with the site up and running:

Resource usage, barely any CPU usage and very low memory usage.

Installing the required software

Let’s start with the process. I will assume that you have a bare Alpine Linux 3.18 install. It can be on Proxmox or bare metal; it doesn’t matter. I run this on a Proxmox LXC.

Note: I’m running everything as root. This is usually a bad idea. Feel free to adjust this and run it as your user instead.

First, you would want to update your Alpine Linux by running the following:

apk update

Followed by:

apk upgrade

These commands will update your repository and upgrade your installed packages to the latest ones.

Next, we will want to install the software required to run Jekyll. To do that, run this command:

apk add nano nginx jekyll alpine-sdk

Explanation of the packages:

nano - this is my preferred text editor. You can use the built-in vi if you want.
nginx - this is the webserver that will serve the static site generated by Jekyll.
jekyll - our main jekyll package.
alpine-sdk - this package is a meta-packages essential to compile software.

Nginx setup

Before going further into Jekyll installation, we should ensure that our web server is running correctly and able to server requests. Run this command to enable Nginx daemon:

rc-update add nginx default

Then start nginx:

rc-service nginx start

By now, you should be able to enter your device IP into your browser, but Nginx will show a 404 page:

Nginx 404

The next step would be to update the Nginx settings. First, backup the default setting by running this command:

mv /etc/nginx/nginx.conf /etc/nginx/nginx.conf.orig

Then, edit the setting by running:

nano /etc/nginx/nginx.conf

And add the text below:

user                            root;
worker_processes                auto; # it will be determinate automatically by the number of core

error_log                       /var/log/nginx/error.log warn;
#pid                             /var/run/nginx/nginx.pid; # it permit you to use /etc/init.d/nginx reload|restart|stop|start

events {
    worker_connections          1024;
}

http {
    include                     /etc/nginx/mime.types;
    default_type                application/octet-stream;
    sendfile                    on;
    access_log                  /var/log/nginx/access.log;
    keepalive_timeout           3000;
    server {
        listen                  80;
        root                    /var/www/public;
        index                   index.html index.htm;
        server_name             localhost;
        client_max_body_size    32m;
        error_page              500 502 503 504  /50x.html;
        location : /50x.html {
              root              /var/lib/nginx/html;
        }
    }
}

Now restart Nginx:

rc-service nginx restart

If you use the rules above, Nginx will run as root and serve files in /var/www/public/. We can test this by creating a simple HTML file:

mkdir /var/www/public && nano /var/www/public/index.html

Add the following code:

<!DOCTYPE html>
<html lang:"en">
<head>
    <meta charset:"utf-8" />
    <title>HTML5</title>
</head>
<body>
    Server is online
</body>
</html>

Try accessing the IP again, and you’ll see this:

Nginx working

Jekyll setup

Now we are at the last steps of this guide. First, create your new Jekyll site using the following command:

jekyll new /var/www/staging

This command will install Jekyll in this /var/www/staging. You can install Jekyll directly to your Nginx doc root and point Nginx to serve from _site folder inside Jekyll, but I like it like this so that I can preview the changes I made before pushing the site to live.

Run the following command to run the Jekyll site. You will need to change the IP using your IP:

jekyll serve --source "/var/www/staging" --destination "/var/www/staging/_site" --host 10.10.10.120 watch

Your Jekyll site should now be accessible by accessing yourIP:4000:

Jekyll working

You can make changes here that won’t affect the actual live site. Once you are ready to push to live, run the following commands:

rm -rf /var/www/public/*
jekyll build --source "/var/www/staging" --destination "/var/www/public"

That’s it! Now Nginx is serving the static site built by Jekyll. I hope that helps!