249 lines
8.2 KiB
Markdown
249 lines
8.2 KiB
Markdown
+++
|
|
title = "Hello World!"
|
|
summary = "Building your first blog using Hugo and Cloudflare Pages"
|
|
date = "2024-04-22"
|
|
|
|
tags = ["Hugo", "Cloudflare", "Pages", "Wrangler"]
|
|
categories = ["Tutorial"]
|
|
+++
|
|
|
|
*Hello World* is the first program a developer writes to check if their setup
|
|
is working properly.
|
|
|
|
As a kind of "Hello World" for my blog, I wanted to show how I created this
|
|
site, starting from the Static Site Generator I chose -
|
|
[Hugo](https://gohugo.io/) - and ending with showing how I hosted everything on
|
|
Cloudflare using [Pages](https://pages.cloudflare.com/).
|
|
|
|
### Disclaimer
|
|
|
|
{{< alert icon="triangle-exclamation" cardColor="#e6d237" iconColor="#1d3557"
|
|
textColor="#1d3557" >}}
|
|
Cloudflare? [**Absolutely proprietary**](https://i.imgflip.com/6kaqvc.jpg)!
|
|
{{< /alert >}}
|
|
|
|
It might seem quite paradoxical that an open-source enthusiast would host their
|
|
site on Cloudflare[^1] and even make a tutorial about it.
|
|
|
|
[^1]: [old.reddit.com - ELI5 why CloudFlare is depicted as evil, and what's
|
|
wrong with using their DNS
|
|
(1.1.1.1)](https://old.reddit.com/r/privacy/comments/d52kop/)
|
|
|
|
I just want to make clear that this is a temporary setup, suitable even for
|
|
those who can't self-host a website, for security reasons or the CGNAT[^2]
|
|
(*damned IPv4*).
|
|
|
|
[^2]: [en.wikipedia.org - Carrier-grade
|
|
NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT)
|
|
|
|
For those interested, I'm making an article about how to forward the port
|
|
through CGNAT, but for now let's continue using the damned Cloudflare.
|
|
|
|
## Creating a site with Hugo
|
|
|
|
To manage all the content on this site, I use [Hugo](https://gohugo.io/), a
|
|
static site generator that allows me to write pages and articles in a simple
|
|
markup language, like Markdown. Hugo will then take the content and a theme and
|
|
combine them, producing static HTML, CSS and JavaScript.
|
|
|
|
To get started, you need to [install
|
|
Hugo](https://github.com/gohugoio/hugo/releases/latest) and create a new
|
|
project:
|
|
|
|
```shell
|
|
hugo new site <site-name>
|
|
cd <site-name>
|
|
git init
|
|
```
|
|
|
|
If you want to view your site on a development server:
|
|
|
|
```shell
|
|
hugo server
|
|
```
|
|
|
|
Now at the URL <http://localhost:1313/>, you should see a *404: Page Not
|
|
Found*. To fix this problem, we need to install a theme.
|
|
|
|
### Choosing a theme
|
|
|
|
To get an idea of which themes we can install, we can go to the [ "Themes"
|
|
section](https://themes.gohugo.io/) of Hugo's website. We can create our own
|
|
theme from scratch if we want, there are several tutorials online about that.
|
|
|
|
For simplicity's sake, for this tutorial, I'll choose the [PaperMod
|
|
theme](https://github.com/adityatelange/hugo-PaperMod/).
|
|
|
|
To add a theme, you first need to download it as a Git submodule into the
|
|
`themes/` directory:
|
|
|
|
```shell
|
|
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/papermod
|
|
```
|
|
|
|
Then you need to specify the theme that Hugo should use in the configuration
|
|
file:
|
|
|
|
```shell
|
|
echo "theme = 'papermod'" >> hugo.toml
|
|
```
|
|
|
|
If we restart the development server, we should see a page similar to this:
|
|
|
|
|
|
|
|
Our site is finally starting to look a bit more colorful, but it's still too
|
|
plain and generic for my taste.
|
|
|
|
### Customizing the site
|
|
|
|
To make the site less generic, you need to modify the configuration files. For
|
|
example, we can change the first variables in `hugo.toml`:
|
|
|
|
```toml
|
|
baseURL = 'https://example.org/'
|
|
languageCode = 'en-us'
|
|
title = 'My New Hugo Site'
|
|
theme = 'papermod'
|
|
```
|
|
|
|
To thoroughly configure the site, you need to consult the documentation for the
|
|
chosen theme. [This is the documentation for the PaperMod
|
|
theme](https://adityatelange.github.io/hugo-PaperMod/).
|
|
|
|
Unfortunately, there is no common documentation for all themes, so you need to
|
|
take some time and read through your theme's documentation.
|
|
|
|
### Adding articles
|
|
|
|
Now our blog looks nice, but at the moment, it's a bit empty. We can fix this
|
|
by creating our first article:
|
|
|
|
```shell
|
|
hugo new content posts/<article-name>.md
|
|
```
|
|
|
|
With this command, Hugo will copy the `archetypes/default.md` file to the
|
|
`contents/posts/` path, rename it, and substitute the variables:
|
|
|
|
```toml
|
|
+++
|
|
title = 'Article Name'
|
|
date = 2024-04-22T00:00:00+02:00
|
|
draft = true
|
|
+++
|
|
```
|
|
|
|
I would like to point out the `draft = true` variable in our article's
|
|
preamble: when this is set to `true`, Hugo hides the article during
|
|
compilation, so you can compile the entire site without worrying about
|
|
displaying incomplete articles.
|
|
|
|
However, you can still display drafts when running the dev server by passing
|
|
the `--buildDrafts` argument to the `hugo server` command.
|
|
|
|
Now you can start writing your post using the [Markdown
|
|
language](https://commonmark.org/):
|
|
|
|
|
|
|
|
Once we've finished writing our articles, we can compile our blog using the
|
|
command:
|
|
|
|
```shell
|
|
hugo
|
|
```
|
|
|
|
The compiled output can be found in the `public/` directory.
|
|
|
|
## Publishing the site with Cloudflare Pages
|
|
|
|
Now that we have a statically compiled site, we can publish it on a platform
|
|
like [Cloudflare Pages](https://pages.cloudflare.com/).
|
|
|
|
There are many platforms that allow you to publish static pages, such as
|
|
[GitHub Pages](https://pages.github.com/) or [Vercel](https://vercel.com/). I
|
|
chose Cloudflare Pages simply for convenience, since I had previously
|
|
registered the "nicolabelluti.me" domain with Cloudflare to use [Cloudflare
|
|
Tunnel](https://www.cloudflare.com/products/tunnel/), which I'll discuss in a
|
|
future article[^3].
|
|
|
|
[^3]: Yes, I know that Cloudflare Tunnel is nothing more than a
|
|
[MITM](https://en.wikipedia.org/wiki/Man-in-the-middle_attack), and I'll
|
|
also discuss how to replace Cloudflare Tunnel with your own Wireguard VPN.
|
|
|
|
To create a site with Cloudflare Pages, go to the [Cloudflare
|
|
Dashboard](https://dash.cloudflare.com/) and navigate to `Workers & Pages`,
|
|
then click `Pages`.
|
|
|
|
Create a new project, give it a name, and save it without uploading any files.
|
|
|
|
|
|
|
|
If you go back to the `Workers & Pages` section in the sidebar, you should see
|
|
the new project.
|
|
|
|
If you want to add your own domain, you can do so in the `Custom domains`
|
|
section of the project. Make sure to add both the base domain and the `www.`
|
|
subdomain.
|
|
|
|
Now we are ready to publish the site! To do this, go to the `Deployments`
|
|
section and click `Upload assets`.
|
|
|
|
|
|
|
|
### Publishing the site using Wrangler
|
|
|
|
Logging into the Cloudflare Dashboard and manually updating the site every time
|
|
we need to change something can be a bit... sub-optimal.
|
|
|
|
For this reason, we can use a handy tool to automatically upload all our files
|
|
from the command line: it's called Wrangler CLI.
|
|
|
|
We can install it via `npm` with:
|
|
|
|
```shell
|
|
npm install -g wrangler
|
|
```
|
|
|
|
To use it, we'll need an API key, so Wrangler CLI can update the site on our
|
|
behalf.
|
|
|
|
To create a key, go to the "[My Profile](https://dash.cloudflare.com/profile)"
|
|
section of the Cloudflare Dashboard, then navigate to `API Tokens` > `Create
|
|
Token`, and then `Create Custom Token` at the bottom of the page.
|
|
|
|
The token should have the following parameters:
|
|
|
|
* **Name**: Call it what you like; I'll call it "blog"
|
|
* **Permissions**: `Account` > `Cloudflare Pages` > `Edit`
|
|
* **Account Resources**: `Include` > *Your account's email*
|
|
* **Client IP Address Filtering**: *optional*
|
|
* **TTL**: *optional, but I **strongly** recommend setting it*
|
|
|
|
|
|
|
|
Click `Continue to summary` > `Create Token` and save the API token.
|
|
|
|
{{< alert >}}
|
|
**Save the token in a safe place, it will be shown only this once**
|
|
{{< /alert >}}
|
|
|
|
Finally, you need to copy the account ID by returning to the [Cloudflare
|
|
Dashboard](https://dash.cloudflare.com/) and opening your domain. The account
|
|
ID can be found on the right sidebar, under the "API" section.
|
|
|
|
Now, with the API key and the account ID, we can run Wrangler with:
|
|
|
|
```shell
|
|
hugo # You need to compile the site first
|
|
|
|
export CLOUDFLARE_ACCOUNT_ID=<Your account ID>
|
|
export CLOUDFLARE_API_TOKEN=<The API token>
|
|
npx wrangler pages deploy 'public/' --project-name=<The project's name>
|
|
```
|