Jekyll is a static site generator designed for fast, flexible, and highly customizable website development. It’s particularly popular among developers and tech-savvy users for its simplicity, markdown-based workflow, and seamless integration with version control systems like Git. Self-hosting Jekyll gives you full control over your site’s code and data, allowing for advanced customization and enhanced security. In this guide, we’ll walk you through deploying, configuring, and managing Jekyll, covering installation, reverse proxy setup, logging, backups, updates, and leveraging advanced features.
Installing Jekyll
📦 Docker/Docker Compose Setup
Dockerizing Jekyll provides an isolated, reproducible environment. Below is a docker-compose.yml tailored for Jekyll:
version: '3.8'
services:
jekyll:
image: jekyll/jekyll
container_name: jekyll
ports:
- "4000:4000"
volumes:
- ./site:/srv/jekyll # Mount your Jekyll site directory
working_dir: /srv/jekyll
command: jekyll serve --watch --host 0.0.0.0
restart: unless-stopped
Save this file in your project directory and run the following command to start Jekyll:
docker-compose up -d
This will serve your Jekyll site at http://<your-server-ip>:4000.
🚀 Manual Installation
To manually install Jekyll on a Linux server, follow these steps:
sudo apt update
sudo apt install -y ruby-full build-essential zlib1g-dev
## Configure Ruby gem environment
echo '# Install Ruby Gems to ~/.gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/.gems"' >> ~/.bashrc
echo 'export PATH="$HOME/.gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
## Install Jekyll
gem install jekyll bundler
## Create a new Jekyll site
jekyll new my-site
cd my-site
## Serve the site locally
jekyll serve --host 0.0.0.0
This will start your Jekyll site on port 4000.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
To serve Jekyll with Nginx as a reverse proxy, create an Nginx server block:
server {
listen 80;
server_name example.com;
location / {
proxy_pass http://localhost:4000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
Save this configuration to /etc/nginx/sites-available/jekyll and link it to sites-enabled:
sudo ln -s /etc/nginx/sites-available/jekyll /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure your Jekyll site with Let's Encrypt:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com
Test the SSL setup:
sudo certbot renew --dry-run
🛠️ Testing and Reloading Nginx
After making changes, validate and reload Nginx:
sudo nginx -t
sudo systemctl reload nginx
Logging and Debugging Jekyll
🗃️ Enabling Debug Logs
Enable debug logs by appending the --verbose flag when serving Jekyll:
jekyll serve --verbose
For Docker users, modify the command in docker-compose.yml:
command: jekyll serve --verbose --host 0.0.0.0
📄 Viewing Logs
For manual installs, logs will appear in the terminal where jekyll serve is running. For Docker containers, view logs with:
docker logs jekyll
🛠️ Troubleshooting Common Issues
-
Port Conflict: Ensure no other service is using port
4000. -
Build Errors: Review logs for missing dependencies or liquid template errors.
-
Nginx Misconfiguration: Check Nginx logs at
/var/log/nginx/error.log.
📤 Exporting Logs
To forward logs to an ELK stack, use Docker's logging driver:
docker run --log-driver=gelf --log-opt gelf-address=udp://<elk-server-ip>:12201 jekyll/jekyll
Backup and Restore
🗂️ File-Based Backups
Backup your Jekyll site directory:
tar -czvf jekyll-backup.tar.gz /path/to/your/site
Restore with:
tar -xzvf jekyll-backup.tar.gz -C /path/to/restore/location
🔄 Database Backups
Jekyll doesn’t use a database by default, so a file-based strategy is sufficient unless you’ve integrated third-party tools requiring data storage.
📅 Automated Backup Scripts
Create a cron job to automate backups:
crontab -e
Add the following line to back up daily at midnight:
0 0 * * * tar -czvf /path/to/backups/jekyll-$(date +\%F).tar.gz /path/to/your/site
Updating and Upgrading Jekyll
⬆️ Updating Docker Images
Pull the latest Jekyll Docker image and redeploy:
docker-compose down
docker-compose pull jekyll
docker-compose up -d
🛠️ Manual Updates
For manual installations, update Jekyll with:
gem update jekyll
🔍 Checking for Updates
Check the currently installed version:
jekyll -v
Verify the latest version in Jekyll’s GitHub repository.
Leveraging Jekyll’s Unique Features
🔧 Enabling APIs
Jekyll supports custom APIs through plugins. Install a plugin in your Gemfile:
gem 'jekyll-plugin-name'
Run bundle install and configure the plugin in _config.yml.
🌟 Advanced Configurations
Customize your _config.yml file for advanced features like collections, permalinks, and plugins. Example for collections:
collections:
tutorials:
output: true
Add content to _tutorials and build:
jekyll build
Wrapping Up
This guide provided a comprehensive walkthrough for deploying, configuring, and managing a self-hosted Jekyll instance. From installation and reverse proxy setups to logging, backups, and leveraging unique features, you now have the tools to control and scale your Jekyll environment. Start implementing these steps today to harness Jekyll’s flexibility and power for your next website project!
