Getting my blog version-controlled and automating deployment
Today, I’m going to be setting up git for my Hugo blog. (This Blog!) Other than allowing me to track the changes I make to my blog, using github allows me to eventually set up an automated deployment system.
I must admit, adding GitHub functionality to my blog came after I actually got it set up and working.
I had already set up my Hugo folder (in my home directory) on my webserver using their Quickstart Guide. I’d then symlinked my hugo publishing folder to the
/var/www/html folder on my server.
This meant that I could ssh into my webserver, create a new post, then run
hugo to add the new content straight into my page.
Now, this is all well and good, but developing this wasy seems a little bit… manual. What i want to be able to do is create/edit the files I want, commit the changes and push them. I wanted my webserver to handle the rest of the deployment.
Well, in the words of Ian Malcolm:
Using git hooks to deploy a Hugo blog
Automated Deployment Process
As far as I’m aware, the process for a successful deployment is:
- Edit blog markdown on Laptop/Desktop/etc.
Check layout/deployment locally using
-Dpart of the command tells Hugo to include pages still in draft.
If happy, push commit to GitHub (to update the origin).
Push commit to your remote repository.
On the remote repository, Github hooks then evaluate what you’ve just pushed. If it’s newer than the code the repo currently has, it will deploy the code to a folder of your choice.
The remote repository then uses
$ hugo -d </path/to/site/html/folder>
to build the publishable html, thus updating the blog.
There is A LOT of information on how to run git-hook-powered Hugo builds out there. However, there doesn’t seem to be many guides for those of us who are git-challenged/haven’t had enough caffeine yet.
After some hefty reading, I was going to have to use a git function called bare repos. This, along with making my webserver a remote git repository and some git-hook-fu.
Looking at my current setup, I had:
/home/sean/sean-blog as my Hugo blog folder.
/var/www/html was symlinked to
For my specific use case, I would be using my server as both the GitHub remote repository AND the hosting webserver.
So, what did I do to make it work?
I had to make my Hugo project a git project.
This was fairly easy, as I was able to follow the amazing tutorial by Karl Broman. The one change I did make, was to create a
.gitignore file containing the
$ echo public > sean-blog/.gitignore
I did this because I didn’t want my generated html files to be pushed to GitHub, or my remote repository.
Once I had made my Hugo site into a github repository and uploaded it for safekeeping, it was time to move on.
Prepare a folder for the remote repository
First of all, I moved my Hugo folder somewhere I wasn’t going to delete it by accident.
$ cp -r ~/sean-blog ~/sean-blog.dev
I then created a bare repository, using the settings of my existing blog repo.
$ git clone --bare sean-blog.dev sean-blog
I chose to use
sean-blog in my home folder, as my specific installation of Hugo didn’t like touching files outside of my home directory.
And that’s how I prepared my server to become a GitHub remote repository!
Set up the GitHub post-receive hook
Next, I had to tell my newly minted repository what to do when it was pushed new data. To do this, I had to create an executable file inside the
hooks folder in our bare repo.
$ nano ~/sean-blog/hooks/post-receive
I then borrowed the good code from Lemi Orhan Ergin and adapted it for my own purposes.
#!/bin/bash target_branch="master" working_tree="build" while read oldrev newrev refname do branch=$(git rev-parse --symbolic --abbrev-ref $refname) if [ -n "$branch" ] && [ "$target_branch" == "$branch" ]; then GIT_WORK_TREE=$working_tree git checkout $target_branch -f NOW=$(date +"%Y%m%d-%H%M") git tag release_$NOW $target_branch echo " /===============================" echo " | DEPLOYMENT COMPLETED" echo " | Target branch: $target_branch" echo " | Target folder: $working_tree" echo " | Tag name : release_$NOW" echo " \==============================" fi done /snap/bin/hugo -s /home/sean/sean-blog/build -d /home/sean/sean-blog/build/publish
If you’re thinking (like me) “That looks complicated, I don’t want to read through all that”, you’re right. The three points to note are:
target_branch="master" #If you push anything other than the master branch, this script won't fire.
working_tree="build" #Place all pushed files into a folder called build. In our case ~/sean-blog/build
/snap/bin/hugo -s /home/sean/sean-blog/build -d /home/sean/sean-blog/build/publish #Run hugo using the build directory as a source and the build/publish folder as a destination
Your remote repository is ready to go!
Add a symlink from your published folder to your web directory
This is by far the easiest bit! I just ran:
$ ln -s /home/sean/sean-blog/build/publish /var/www/html
As soon as your repository is pushed code, your site will update.
Pushing the code
The final step is to set up your development device’s git capability.
On your dev device, you should clone your blog repo. I’ll assume you know how to do that part.
Next, you sun the following command to add your remote repository. I use the repository name production, purely for workflow aesthetics.
$ git remote add production ssh://sean@my-server:/~/sean-blog
Now that I’ve added my production repo, I can go ahead and push to it.
$ git push production master
You should get an output in your terminal similar to:
Counting objects: 11, done. Delta compression using up to 4 threads. Compressing objects: 100% (9/9), done. Writing objects: 100% (11/11), 4.14 KiB | 4.14 MiB/s, done. Total 11 (delta 3), reused 0 (delta 0) remote: Already on 'master' remote: /=============================== remote: | DEPLOYMENT COMPLETED remote: | Target branch: master remote: | Target folder: build remote: | Tag name : release_20190124-1619 remote: \============================== remote: Building sites … remote: | EN remote: +------------------+----+ remote: Pages | 20 remote: Paginator pages | 0 remote: Non-page files | 0 remote: Static files | 3 remote: Processed images | 0 remote: Aliases | 9 remote: Sitemaps | 1 remote: Cleaned | 0 remote: remote: Total in 25 ms To ssh://sean@my-server:/~/sean-blog 30915cf..a299f04 master -> master
If you’ve been following through with me, you should be able to visit your web server and see your Hugo blog!
Congrats on getting through it, hopefully this will serve as a useful guide for others (and for me when I inevitably forget how I did it before).
Remember, whenever you add new pages, or make changes, you should run:
$ git add . $ git commit -m "Commit notes" $ git push origin master $ git push production master