existing git repo with a Hugo site
For this post I will be using the Hugo example site for demo purposes.
When deploying a static website on the modern web there are many requirements that may restrict the number of choices we have. The reason I chose Gitlab and Cloudflare is because it is one of two ways (as of 03/23/2018) that I know off that satisfies these requirements.
- custom domain
for example chrisostrouchov.com
- ssl certificate
must have an ssl certificate for the custom domain
- continuous delivery (CD)
upon a git commit I expect my updated blog to be deployed
- private git repo
it would be nice to have private repo for the development while having a public static site
- content delivery network (CDN)
ensures that the site is served to a client as fast as possible
everything for deployment must be free
Gitlab is really the only option as of now that provides a private git repo, continuous delivery, and is free. Personally I love gitlab and for a while I even self hosted it on Kubernetes. It cannot be understated how fast Gitlab has grown and their CD/Continuous Integration(CI) platform is unmatched. Github satisfies continuous delivery and is free but only for public git repos.
Cloudflare and Netlify are the two options that satisfy ssl certificate, content delivery network, and custom domain. Note that if you self hosted your custom domain you still would not get the benefits of a CDN and would need to use a provider such as Cloudflare. Cloudflare provides many other additional features such as HTTP/2 push, rate limiting, free DDoS protection which are beneficial no matter where you are hosting your site. I would advise people trying to learn proper development practices to not use Netlify. Netlify is a great services and is definitely easier to setup than Cloudflare but it hides the standard deployment process. If you would like to setup a static site instead with Netlify I would recommend this getting started guide.
Now that I have talked about the reasoning behind the services that we will use lets get to deploying a static website! All of the code can be found in a gitlab repo here.
First we will need to create a gitlab account and push our git repo to
gitlab. Gitlab provides documentation on how to get this done. We will
next be taking advantage of Gitlab's CD/CI pipeline. Our usage of
CD/CI will be very limited but know that much more complex pipelines
with dependencies can be constructed. Gitlab checks for a file
.gitlab-ci.yml in the root of the git repo and executes the build
steps provided. One of the features that Gitlab provides is static
website hosting with a default path of
<username>.gitlab.io/<repo>/. Gitlab brands this as
much of the same features as Github pages.
variables: GIT_SUBMODULE_STRATEGY: "recursive" pages: image: "registry.gitlab.com/pages/hugo:0.32.3" # from gitlab pages repo script: - "hugo" artifacts: paths: - "public/" only: - "master"
We only have one step in this build pipeline. The step is named
pages which is required for Gitlab to know that a static site should
be given for the repo. Gitlab uses runners based on a docker image for
each build step. For this build step we are using the docker image
registry.gitlab.com/pages/hugo:0.32.3. The docker images will run
hugo command. The
hugo command by default builds the site and
puts all static files in the
public directory. Conveniently Gitlab
pages requires an archived
public directory to serve the static
site. When you have pushed the
.gitlab-ci.yml to your master branch
on Gitlab you should see a blue icon indicating that it is building
your site. If you have included themes via git submodules (the
recommended hugo way) then you need to include the
After the simple pipeline has completed you will hopefully see the blue icon change to a green checkmark. You can check the site that will be exposed by looking at the build artifact created and downloading it.
Now that we have a simple website deployed we need to use Cloudflare to setup the CDN and TLS. These next steps follow these directions from Gitlab. Some steps were not well documented an I will to clarify.
create a Cloudflare account
point your nameservers for your domain to cloudflare. My example ones are listed bellow.
Once you have completed these steps you can continue to follow the guide. At this point you will have a custom domain for your hugo site!