Deploying a Jekyll blog with sourcehut
Introduction
This tutorial shows how to deploy a Jekyll blog to a GNU/Linux server with the help of builds.sr.ht
Prerequisites
- GNU/Linux Server - hosts your blog
- Jekyll blog - hosted on any
git
server provider; Sourcehut, GitHub, GitLab etc. - A builds.sr.ht account.
Public repositories
The following section details how to achieve this with a public repo.
Defining the build manifest
image: archlinux
sources:
- 'https://github.com/<username>/<repo>'
secrets:
- <secret-uuid-1>
- <secret-uuid-2>
packages:
- ruby
- nodejs-lts-fermium
tasks:
- setup: |
ruby -v
gem -v
export PATH=$(ruby -e 'puts Gem.user_dir')/bin:$PATH
gem install --user-install bundler
cd blog
sudo chown -R $(whoami) ~/.gem/*
bundle install
- build: |
cd blog
export PATH=$(ruby -e 'puts Gem.user_dir')/bin:$PATH
bundle exec jekyll build
- deploy: |
cd blog
DEPLOY_HOST=168.119.234.216
DEPLOY_USER=ken
eval `ssh-agent`
ssh-add ~/.ssh/<secret-uuid-1>
ln -s ~/.ssh/<secret-uuid-2> ~/.ssh/id_rsa.pub
scp -o StrictHostKeyChecking=no -rv _site/* [email protected]$DEPLOY_HOST:/var/www/html/blog
Although a general description of the build manifest schema can be found here, I’ll continue by detailing the Jekyll specific configuration options below.
Image
builds.sr.ht offers a ton of images to choose from. This tutorial went witharchlinux
.
image: archlinux
Sources
Specify what repo to clone. The https
schema is used to define the repo URL.
sources:
- 'https://github.com/<username>/<repo>.git'
Secrets
Public repos just need 2 uuids i.e. the deploy server key pair.
secrets:
- <secret-uuid-1>
- <secret-uuid-2>
Packages
Install any packages needed as dependencies.
packages:
- ruby
- nodejs-lts-fermium
This is the equivalent of
sudo pacman -S ruby nodejs-lts-fermium
Tasks
This YAML list contains the actual build steps.
tasks:
- setup: |
ruby -v
gem -v
export PATH=$(ruby -e 'puts Gem.user_dir')/bin:$PATH
gem install --user-install bundler
cd blog
sudo chown -R $(whoami) ~/.gem/*
bundle install
- build: |
cd blog
export PATH=$(ruby -e 'puts Gem.user_dir')/bin:$PATH
bundle exec jekyll build
- deploy: |
cd blog
DEPLOY_HOST=168.119.234.216
DEPLOY_USER=ken
eval `ssh-agent`
ssh-add ~/.ssh/<secret-uuid-1>
ln -s ~/.ssh/<secret-uuid-2> ~/.ssh/id_rsa.pub
scp -o StrictHostKeyChecking=no -rv _site/* [email protected]$DEPLOY_HOST:/var/www/html/blog
Private repositories
The following section details how to achieve this goal when a private repo is involved.
Defining the build manifest
Much like travis.yml
or circle.yml
files, manifests describe a build. The relevant build manifest is shown below.
image: archlinux
sources:
- '[email protected]:<username>/<repo>.git'
secrets:
- <secret-uuid-1>
- <secret-uuid-2>
- <secret-uuid-3>
packages:
- ruby
- nodejs-lts-fermium
tasks:
- setup: |
if [ "$(git rev-parse origin/develop)" != "$(git rev-parse HEAD)" ]; then \
complete-build; \
fi
ruby -v
gem -v
export PATH=$(ruby -e 'puts Gem.user_dir')/bin:$PATH
gem install --user-install bundler
cd blog
sudo chown -R $(whoami) ~/.gem/*
bundle install
- build: |
cd blog
export PATH=$(ruby -e 'puts Gem.user_dir')/bin:$PATH
bundle exec jekyll build
- deploy: |
cd blog
DEPLOY_HOST=156.116.53.2
DEPLOY_USER=myusername
eval `ssh-agent`
ssh-add ~/.ssh/<secret-uuid-2>
ln -s ~/.ssh/<secret-uuid-3> ~/.ssh/id_rsa.pub
scp -o StrictHostKeyChecking=no -rv _site/* [email protected]$DEPLOY_HOST:/var/www/html/blog
Sources
Specify what repo to clone. The ssh
schema is used if the repo in question is private, otherwise use the https
schema.
sources:
- '[email protected]:<username>/<repo>.git'
Secrets
A YAML list of uuid
s that point to secrets specified here. Secrets can be SSH, PGP keys or files.
secrets:
- <secret-uuid-1>
- <secret-uuid-2>
- <secret-uuid-3>
For this build however, we are only interested in SSH secrets. In addition to GitHub’s private key, we also need the deploy server’s public and private key.
The first key on the list is linked to ~/.ssh/id_rsa
. Subsequent keys can be added later in the build using ssh-add
.
Generate a key pair with ssh-keygen
. Do not use a passphrase when prompted.
ssh-keygen -t rsa
Copy the public key over to the deploy server with ssh-copy-id
ssh-copy-id -i ~/.ssh/id_rsa $DEPLOY_USER@$DEPLOY_HOST
NOTE: The private key needed for
git clone
should occupy the first slot.
Tasks
YAML list of command line instructions needed to successfully run the build.
tasks:
- setup: |
if [ "$(git rev-parse origin/develop)" != "$(git rev-parse HEAD)" ]; then \
complete-build; \
fi
ruby -v
gem -v
export PATH=$(ruby -e 'puts Gem.user_dir')/bin:$PATH
gem install --user-install bundler
cd blog
sudo chown -R $(whoami) ~/.gem/*
bundle install
- build: |
cd blog
export PATH=$(ruby -e 'puts Gem.user_dir')/bin:$PATH
bundle exec jekyll build
- deploy: |
cd blog
DEPLOY_HOST=156.116.53.2
DEPLOY_USER=myusername
eval `ssh-agent`
ssh-add ~/.ssh/<secret-uuid-2>
ln -s ~/.ssh/<secret-uuid-3> ~/.ssh/id_rsa.pub
scp -o StrictHostKeyChecking=no -rv _site/* [email protected]$DEPLOY_HOST:/var/www/html/blog
Conclusion
Sourcehut is a CI/CD tool with a different take on build systems. Although it is still an early stage project, the simplicity it offers is worth a try, especially for side projects.