This is part 3 of a 3 part series. You can find the other parts here:

  1. create your site using hugo
  2. deploy and host your page with now and setup your own domain
  3. use github and now to automatically deploy everything on push

Table of Contents

Automate it!

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:

  1. use the official hub command line tool
  2. 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. πŸ˜‰

Setup now integration on github

Now that you have a GitHub repository it’s time to create a link between it and your now account. To achieve that we need to first link your GitHub account.

Here is a link to the docs from now. Nevertheless I’m gonna give you super quick bullet point rundown:

  1. go to your now account page
  2. look for a “GitHub Integration” section
  3. press the “Install Now for GitHub” button
  4. 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. For that 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. The 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.json

How does now know which repositories are relevant? For that you write a now.json file.

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 now should alias the deployed version to
  • name: the name which appears in your now deployments and web interface, no magic here
  • type: what kind of deployment is this? In this case it’s static because now should just serve the files as they are
  • version: what kind of now version do we wanna use?

So, how come now knows how to build my page? This is a bit of magic on now’s side: when you have a static deployment and a Dockerfile 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:

  1. fetch the files from the repo
  2. detect the Dockerfile, run docker build
  3. deploy the contents of the image’s /public folder
  4. alias the deployment to blog.saschawolf.me

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:

$ now

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

And now will use the alias from your now.json.

Push Sesame

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 master!

How do you think I published this blog post? πŸ˜‰

If you like this series you can follow me on Twitter @wolf4earth, on dev.to @wolf4earth, or subscribe to the RSS-Feed of this blog.