1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
---
title: Building a Static Site with Hugo and Docker
tags: posts
toc: true
---
This will be a quick walkthrough of how to create a static site using Hugo, and use Nginx to serve it.
**Prerequisites**
| **Skill** | **Description** |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Basic Terminal Usage** | Familiarity with navigating directories and running basic commands in a terminal. |
| **Git** | Ability to initialize a Git repository, commit changes, and interact with remote repositories. |
| **Markdown** | Knowledge of writing basic content in Markdown format (used for posts). |
| **Docker Basics** | Understanding of Docker commands for building images and running containers. |
| **HTML/CSS Basics** | General awareness of HTML and CSS for customising static site content.<br> |
| Go | Go should be installed on your system to use Hugo with the `go install` method. Alternatively, you can download Hugo binaries directly or use a package manager. |
# Step 1: Installing Hugo
Hugo is a static site generator, meaning it builds HTML, CSS, and JavaScript that doesn't need a backend server, since the website's content is static.
You can install Hugo in multiple ways. If you already have Go installed, you can use
```shell
go install github.com/gohugoio/hugo@latest
```
Alternatively, you can install Hugo following the [official install guide](https://gohugo.io/installation/)>
# Step 2: Creating a New Hugo Site
To create a new Hugo site, run:
```shell
hugo new site website
```
This creates a new folder called `website` with the basic structure of a Hugo site.
# Step 3: Setting Up a Theme
By default, Hugo doesn't ship with any themes installed, so its likely you'll want to add one. A list of pre-made themes exist [here](https://themes.gohugo.io/), which saves you from having to create one from scratch. Typically, this involves using a Git submodule to manage the theme:
```shell
cd website
git init
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
```
A Git submodule is a way to link a separate repository (the theme) into your project without copying it directly. This keeps the theme up-to-date and lets you manage it separately from your main website's content.
To use the theme, add it to your `config.toml` file:
```shell
echo 'theme = ["PaperMod"]' >> hugo.toml
```
Alternatively, you could manually download the theme and place it in the `themes` folder, but using submodules allows for easier updates.
# Step 4: Personalising Your Site
Open `config.toml` in your favorite code editor (e.g., VS Code), and change the `title` line to peronsalise your site's name:
```toml
title = "<insert name>'s blog"
```
This will update the title of your site, which you’ll see when we generate the site in a moment.
# Step 5: Creating a New Post
To create a new post, run the following command:
```shell
hugo new content content/posts/my-first-post.md
```
This will create a new file in the `content/posts` directory, named `my-first-post.md`. When you open it, you’ll see:
```markdown
+++
title = 'My First Post'
date = 2024-09-08T15:44:30+01:00
draft = true
+++
```
The block of text wrapped in `+++` is called "front matter" and acts as metadata for your post. It won't be visible in your generated website, the actual content of your post goes below this.
Now, you can edit the file to include your first post:
```markdown
+++
title = 'My First Post'
date = 2024-09-08T15:44:30+01:00
draft = true
+++
## Welcome!
This is my first post on my new site. It's written in markdown and utilises hugo for generating html which browsers understand and can parse.
Visit the [Hugo](https://gohugo.io) website!
```
# Step 6: Previewing Your Website
To preview your website locally, run the following command:
```shell
hugo server --buildDrafts
```
This will start a local server, and you can view your site by visiting `http://localhost:1313` in your browser.
# Step 7: Publishing the Website
Once you're ready to publish, update your post by changing `draft = true` to `draft = false` (or just delete the `draft` property) and run:
```shell
hugo
```
This will build your site and place the generated files in the `public` folder. This folder contains all the HTML, CSS, and JavaScript that make up your static site.
From here you can deploy it following [Hugo's own guide](https://gohugo.io/categories/hosting-and-deployment/. However, most of these options involve using someone else's compute, and our goal here is self hosting.
# Step 8: Dockerising your Site
Now that you have a static site in the `public` folder, let's create a Docker image that will serve your site using Nginx, a lightweight web server. While you could install Nginx directly on a server and follow [this guide](https://gohugo.io/hosting-and-deployment/deployment-with-rclone/) to deploy your site, using Docker offers several advantages. Containers provide a reproducible, isolated environment that makes it easy to package, run, and deploy your site across different systems. So, let's use Docker to handle serving your site instead.
Create a `Dockerfile` with the following content
```dockerfile
FROM nginx:1.27.1
COPY public /usr/share/nginx/html
```
This tells Docker to use the official Nginx image and copy the files from your `public` folder (which Hugo generated) into the default location that Nginx serves from.
# Step 9: Building and Running the Docker Image
To proceed, you'll need a container registry. We'll use Docker hub for this example (you'll need an account) but you can use whatever container registry you have access to.
To build your Docker image, run:
```shell
docker build . -t <dockerusername>website:0.0.1
```
Here:
- `-t <dockerusername>website:0.0.1` tags the image with a name (`<dockerusername/website`) and a version (`0.0.1`), which will be important later when you want to publish it.
- the `.` tells Docker to build the image from the current directory (which contains your `Dockerfile` and `public` folder).
Now that you have the Docker image locally, you can run it using
```shell
docker run -p 8080:80 <dockerusername>website:0.0.1
```
Here, `-p 8080:80` maps port 8080 on your local machine to port 80 in the Docker container, where Nginx serves the content.
Now, open a browser and go to `http://localhost:8080`. You should see your static site served by Nginx!
But your server is not your local machine (potentially), so you need a method of getting the image from your local machine, to your server. We can use container registries as an intermediary.
1. First login to Docker Hub:
```shell
docker login
```
2. Push your image to Docker Hub, by default this image will be public.
```shell
`docker push <dockerusername>website:0.0.1
```
3. SSH into the server
```shell
ssh user@server-ip
```
4. Pull the Image (we don't need to login since the image is public):
```shell
docker <dockerusername>website:0.0.1
```
5. Run the Docker Image
```shell
docker run -d -p 80:80 <dockerusername>website:0.0.1
```
- `-d` runs the container in detached mode (in the background).
- `-p 80:80` maps port 80 of the container (where Nginx is running) to port 80 on the server, making the website accessible via the server's IP address in a browser.
You will be able to access the website by visiting `http://server-ip:80`
# Conclusion
Congratulations on creating and running your first static website with Hugo and Docker!
|
