This is part 3 of a 3 part series. You can find the other parts here:
- create your site using hugo
- deploy and host your page with now and setup your own domain
- use github and now to automatically deploy everything on push
Table of Contents
For this section I’ll assume you’ll have the following setup:
After this part you’ll be able to push your code into a github repository and let
now do all the deployment work for you.
At the end of it you’ll have a repository up on github and your page will be automagically deployed when you push changed files! No worries if that sounds a bit intimidating, I’ll be here to guide you along the way!
Creating a github repo
Since the scope of this post is not “how to use GitHub”, I’ll keep this section short and sweet.
For this step you basically have two options:
- use the official
hubcommand line tool
- navigate the web interface
If you wanna go with
hub you can read about it here.
It’s basically GitHub on the command line and a neat tool.
I can highly recommend it.
On the other hand, if you prefer the web interface you can find everything in the official docs from GitHub. They’re very thorough and should answer all your questions.
Now go, create a repository. 😉
now integration on github
Now that you have a GitHub repository it’s time to create a link between it and your
To achieve that we need to first link your GitHub account.
Here is a link to the docs from
Nevertheless I’m gonna give you super quick bullet point rundown:
- go to your
- look for a “GitHub Integration” section
- press the “Install Now for GitHub” button
- Login to GitHub, accept the prompt
That’s it, easy right? With the basic stuff out of the way we can get this part started! 🎉
now v1 or v2?
Shortly after I built this page
now announced v2 of their service, which revolves around builders.
What we need is a static deployment: we run hugo once and use the resulting files as they are.
now offers a static builder which - when you take a look at the docs - actually uses hugo as an example.
Nevertheless in this guide I’ll go with
now v1 with a Dockerfile, it’s what I use for deploying this page after all.
It’s bit more involved - you’ll have to write a Dockerfile - but I think it’s a nice learning experience.
Nevertheless if you would rather use a v2 deployment, then go ahead! No hard feelings.
To Docker or not to Docker?
So, you might have heard of Docker but maybe you never used it.
In a nutshell Docker is a generalized approach to package software with all it’s dependencies.
To do this you write a Dockerfile.
A Dockerfile is basically a recipe which tells Docker how to package whatever you’re trying to package.
The output of a Dockerfile (evaluated with
docker build) is an image.
While I obviously can’t go into the nitty gritty details on the terminology here or how Docker works, there are lots of great guides out there explaining it way better than I ever could. If you’re interested, this official guide is a really good starting point.
For now, all you need to know is this: we create Dockerfile which tells Docker how to build our image. Let’s jump right in and look at the Dockerfile which builds this page:
Doesn’t look too scary (I hope).
In short, it installs hugo, downloads the theme, builds the page, and then does something … odd.
FROM scratch line tells Docker to, well, start the resulting image from scratch.
Into this fresh image we copy the built website from the previous steps.
The end result is an image which only contains the built site.
No hugo installed, no theme downloaded, nothing.
In Docker-speech this is called a multi-stage build.
Why you may ask? It makes the image very small since it only contains the files it needs to. If your build requires any secrets (which this one does not) it also protects you from leaking those secrets by accident. So while a multi-stage build is not strictly necessary, it is good practice.
That’s it. Feel free to use the Dockerfile from above and adjust it to your needs.
With that done we have completed the first step to full automation! 🎉
now know which repositories are relevant?
For that you write a
I could bore you to death about all the things you can configure here.
But I won’t.
Instead I’ll show you the
now.json for this page:
Ridiculously small, right?
Let’s go over each property:
alias: you might have guessed it, this is the domain
nowshould alias the deployed version to
name: the name which appears in your
nowdeployments and web interface, no magic here
type: what kind of deployment is this? In this case it’s
nowshould just serve the files as they are
version: what kind of
nowversion do we wanna use?
So, how come
now knows how to build my page?
This is a bit of magic on
when you have a
static deployment and a
now (correctly) assumes that the image contains your final page.
The only thing you need to do is put the relevant files in a
/public folder in your docker image.
See here the docs for details on this.
All this in combination leads to
now basically doing this:
- fetch the files from the repo
- detect the
- deploy the contents of the image’s
- alias the deployment to
Bonus: This also works locally!
(It will skip the
alias step though, so you can test things safely!)
To try it out you can just create your own version of the above
now.json and simply run:
This will do steps 1-3 and give you a deployment you can peek at. 🙂 Neat, huh?
If you then like what you see you can just run:
$ now alias
now will use the
alias from your
And that’s it!
You’ll only need to push everything onto
master in the repository created earlier.
After that it will work automagically.
now will deploy any changes to
master and alias it directly.
Other branches will get ignored, so you can safely use them for iterations on your posts.
What are you waiting for?
Create a page and push to
How do you think I published this blog post? 😉