Deploy Your Personal Web-Page With Hugo, Cloudflare and GitHub 100% For Free

This article describes how to deploy a static site.

We would use Infrastructure as Code (IaC) approach to describe site changes and deploy them automatically with Cloudflare Pages.

If you are not familiar with one of the tools, don't worry, all steps are described in the details.

You can use this article as a guide for your own static site for 10 minutes and 100% free.

Table of Content

Description
Pre-requirements
Tips
Quick Start
Useful links
Conclusion

For a quick start, you can jump to the “Quick Start” section.

Description

The site will be hosted on Cloudflare Pages, and the domain name will be managed by you. The site will be built using the Hugo framework. The whole process will be automated using Cloudflare pages. We will use GitHub as a source of truth for our site.

So we describe an infrastructure as code and deploy it automatically; it's a little different from the site constructor approach, there is no user interface (UI) for site management, but it's more flexible and powerful.

Just follow these 5 steps, and you will have your own personal site for free.

Initialize your site
Choose a theme for your site
Commit the changes to your repository on GitHub
Assign your site to your project on Cloudflare Pages
Enjoy your site

To update your site, you just need to commit changes to your repository on GitHub. Then Cloudflare Pages will automatically rebuild your site.

Pre-requirements

GitHub account.

If you don't have one, you can create it here, it's free.
Cloudflare account.

If you don't have one, you can create it here, it's free.
Domain name. This step is optional.

If you don't have a domain name, you can use a free subdomain from Cloudflare. It's up to you. Your free subdomain will look like this: yourname.pages.dev.

TIPS

TIP 1

If you would like to make a similar page to my kazakov.xyz, just grab my repo in 3 steps:

Fork my repo kksudo/kazakov.xyz
Update content on your new site. Please, see the repo structure. You need to update 2 files:
1. ./config.toml - Edit the links to your social networks or remove unused ones. For the main pic, I use Gravatar, but you can use this setting avatarurl = "images/avatar.jpg". To read more about Hugo config.toml, please read here.
2. about.md - Add a few words about yourself.
Follow to step “#4 Cloudflare Pages”

TIP 2

To verify your changes, run docker run --rm -it -v $(pwd):/src -w /src -p 1313:1313 klakegg/hugo:alpine server -D and open http://localhost:1313/

TIP 3

You can add a new page by docker run --rm -it -v $(pwd):/src -w /src klakegg/hugo:alpine new <SECTIONNAME>/<FILENAME>.<FORMAT>.

TIP 4

To exclude unnecessary dynamic files, update your .gitignore

Quick Start

Step 1. Initialize Your Site

For our site, we will use the Hugo framework. We will use some steps from the Hugo quick start guide to initialize our site. So, to start it, we need to install a Hugo binary on your machine, but I prefer a docker to keep my OS clean.

Let's create a root structure for your site hugo new site business-card:

docker run --rm -it -v $(pwd):/src -w /src klakegg/hugo:alpine new site business-card

Docker options:

--rm - remove the container after exit

-it - interactive mode

-v $(pwd):/src - mount the current directory to /src directory in the container

-w /src - set the working directory to /src in the container

klakegg/hugo:alpine - latest docker image with Hugo, based on the Alpine Linux

Tip for a ~~smart~~ lazy person like me:

Check this step in my repository kksudo/kazakov.xyz

Step 2. Chose a Theme for Your Site

To find a theme for our site, we will use an official Hugo hub.

There are a lot of themes; you can choose any of them. But my favorite option is to discover it via GitHub. Because you can filter repositories by stars, forks, maintaining, etc. For example, here is a simple filter.

So, let's start with the Coder theme with more than 2k+ starts on GitHub.

Move to the root directory of your site.
```
cd business-card
```
Initialize an empty Git repository in the current directory. Skip it if your site already has a Git repository.
```
git init -b main # Initialize the local directory as a Git repository.
```
Clone the Coder theme into the themes directory, and add it to your project as a Git submodule.
```
git submodule add https://github.com/luizdepra/hugo-coder themes/hugo-coder
```
Update the site configuration file ./config.toml, indicating to use hugo-coder theme. Also, we should add some settings for this theme. Grab these settings from my config.toml file.

You can find more information about the theme settings here.

Note: If you would like to use a simple theme, without any settings, you can use the Ananke theme. It's a default theme for Hugo, quick start URL.

Tip for a ~~smart~~ lazy person like me:

You could grab this step from my repository kksudo/kazakov.xyz
To verify changes, run docker run --rm -it -v $(pwd):/src -w /src -p 1313:1313 klakegg/hugo:alpine server -D and open http://localhost:1313/

Step 3. Commit the Changes to Your GitHub Repository

Let's add some content, and change the default site settings before the first commit.

Add an About page

docker run --rm -it -v $(pwd):/src -w /src klakegg/hugo:alpine new about.md

Add some markdown to the body of the post, but do not change the draft value, code content/about.md

---
title: "About"
date: 2023-04-11T21:14:37Z
draft: true
---

I'm a member of "I want to know everything" and "I'm happy to share what I've already learned" groups.
DevOps with love.

Update ./config.toml as described in the hugo-coder theme page. Let's add some menu settings for the About page. Or grab these settings from my config.toml file, and then edit.

Push our changes to GitHub origin.

git add -A . # Adds the files in the local repository and stages them for commit
git commit -m "First commit" # commit all the files in your project

git remote add origin [email protected]:<owner>/<repo-name>.git
git push -u origin main

Note: Read more about GitHub quick start here

Tip for a ~~smart~~ lazy person like me: grab this step from my repository kksudo/kazakov.xyz

Step 4. Assign Your Site to Your Project on Cloudflare Pages

Create an account on Cloudflare, and log in to your account.
Create a new project on Cloudflare Pages, and connect to your GitHub repository.
1. Connect Cloudflare to your GitHub repository.
2. Install Cloudflare Pages.
3. Grand permissions Cloudflare integration in GitHub.
Setting up Cloudflare settings for the Hugo site
1. Chose a Hugo framework
2. Add a variable to use on the latest Hugo version, HUGO_VERSION=0.111.3
  
  TIP: If you would like to revert Cloudflare permissions for your repo, you should go to https://github.com/settings/installations and change settings for Cloudflare Pages.
So, after Cloudflare will be assigned, deployment will be triggered. And after it, Cloudflare started deployment of your site.

By default, Cloudflare will build and deploy all your branches and generate a unique URL for each branch; the main URL will be also available for your default branch.

So, Cloudflare shows you a lot of details about your build and deployment process.

Step 5. Enjoy Your Site

Open https://yourname.pages.dev and enjoy :)

Tip for a smart lazy person like me:

Sorry, no tips :)

Disclaimer, Why Did I Choose This Set of Tools?

Why Hugo?

Hugo it's the world’s fastest framework for building websites with more than 66 000 stars on GitHub. It's very easy to use, pretty fast, open-source, and has a lot of features. You can find more information about Hugo on the official website.

Why GitHub?

GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere. You can find more information about GitHub on the official website.

Why Cloudflare?

Firstly, I will explain why, I didn't choose GitHub Pages. The last time I tried to use GitHub Pages, I faced some incipient problems. Also, I chose Cloudflare Pages because this provider is network focused.

I know Cloudflare as a network infrastructure and security company. I really like their products, like DNS, CDN, Firewall, etc. But I didn't know that they have a product for hosting static sites. I was surprised when I found out about it.

So, I decided to use network focused provider for hosting static sites.

Conclusion

I hope this article was useful for you. If you have any questions, feel free to ask me in the comments. I will be happy to help you.

Also, feel free to connect with me kazakov.xyz.

P.S.:

For this flow, we could use a lot of other approaches, services, and tools; in the section above, I described why I sue these techs.

For example, you can use GitHub pages instead of Cloudflare Pages, and use another static site generator instead of Hugo.

#contest-tags