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
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="Home for a73x" />
<meta name="author" content="a73x" />
<meta name="viewport"
content="user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, width=device-width" />
<title>a73x</title>
<link rel="stylesheet" href="/static/styles.css">
<link rel="stylesheet" href="/static/syntax.css">
<link rel="icon" type="image/x-icon" href="/static/favicon.svg">
</head>
<body>
<main>
<div class="header">
<div class="header-title">
<h1>a73x</h1>
<sub>high effort, low reward</sub>
</div>
<nav class="nav">
<ul>
<li><a class="no-decorations" href="/">Home</a></li>
<li><a class="no-decorations" href="/posts">Posts</a></li>
<li><a class="no-decorations" href="/ethos">Ethos</a></li>
</ul>
</nav>
</div>
<hr />
<a href="/posts">← Posts</a>
<h1>Building a Static Site with Hugo and Docker</h1>
<h1 id="table-of-contents">Table of Contents</h1>
<ul>
<li>
<a href="#step-1-installing-hugo">Step 1: Installing Hugo</a></li>
<li>
<a href="#step-2-creating-a-new-hugo-site">Step 2: Creating a New Hugo Site</a></li>
<li>
<a href="#step-3-setting-up-a-theme">Step 3: Setting Up a Theme</a></li>
<li>
<a href="#step-4-personalising-your-site">Step 4: Personalising Your Site</a></li>
<li>
<a href="#step-5-creating-a-new-post">Step 5: Creating a New Post</a></li>
<li>
<a href="#step-6-previewing-your-website">Step 6: Previewing Your Website</a></li>
<li>
<a href="#step-7-publishing-the-website">Step 7: Publishing the Website</a></li>
<li>
<a href="#step-8-dockerising-your-site">Step 8: Dockerising your Site</a></li>
<li>
<a href="#step-9-building-and-running-the-docker-image">Step 9: Building and Running the Docker Image</a></li>
<li>
<a href="#conclusion">Conclusion</a></li>
</ul>
<p>This will be a quick walkthrough of how to create a static site using Hugo, and use Nginx to serve it.</p>
<p><strong>Prerequisites</strong></p>
<table>
<thead>
<tr>
<th><strong>Skill</strong></th>
<th><strong>Description</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Basic Terminal Usage</strong></td>
<td>Familiarity with navigating directories and running basic commands in a terminal.</td>
</tr>
<tr>
<td><strong>Git</strong></td>
<td>Ability to initialize a Git repository, commit changes, and interact with remote repositories.</td>
</tr>
<tr>
<td><strong>Markdown</strong></td>
<td>Knowledge of writing basic content in Markdown format (used for posts).</td>
</tr>
<tr>
<td><strong>Docker Basics</strong></td>
<td>Understanding of Docker commands for building images and running containers.</td>
</tr>
<tr>
<td><strong>HTML/CSS Basics</strong></td>
<td>General awareness of HTML and CSS for customising static site content.<!-- raw HTML omitted --></td>
</tr>
<tr>
<td>Go</td>
<td>Go should be installed on your system to use Hugo with the <code>go install</code> method. Alternatively, you can download Hugo binaries directly or use a package manager.</td>
</tr>
</tbody>
</table>
<h2 id="step-1-installing-hugo">Step 1: Installing Hugo</h2>
<p>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.</p>
<p>You can install Hugo in multiple ways. If you already have Go installed, you can use</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>go install github.com/gohugoio/hugo@latest
</code></pre><p>Alternatively, you can install Hugo following the <a href="https://gohugo.io/installation/">official install guide</a>></p>
<h2 id="step-2-creating-a-new-hugo-site">Step 2: Creating a New Hugo Site</h2>
<p>To create a new Hugo site, run:</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>hugo new site website
</code></pre><p>This creates a new folder called <code>website</code> with the basic structure of a Hugo site.</p>
<h2 id="step-3-setting-up-a-theme">Step 3: Setting Up a Theme</h2>
<p>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 <a href="https://themes.gohugo.io/">here</a>, which saves you from having to create one from scratch. Typically, this involves using a Git submodule to manage the theme:</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code><span style="color:#0aa">cd</span> website
git init
git submodule add --depth=<span style="color:#099">1</span> https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
</code></pre><p>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.</p>
<p>To use the theme, add it to your <code>config.toml</code> file:</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code><span style="color:#0aa">echo</span> <span style="color:#a50">'theme = ["PaperMod"]'</span> >> hugo.toml
</code></pre><p>Alternatively, you could manually download the theme and place it in the <code>themes</code> folder, but using submodules allows for easier updates.</p>
<h2 id="step-4-personalising-your-site">Step 4: Personalising Your Site</h2>
<p>Open <code>config.toml</code> in your favorite code editor (e.g., VS Code), and change the <code>title</code> line to peronsalise your site's name:</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>title = <span style="color:#a50">"<insert name>'s blog"</span>
</code></pre><p>This will update the title of your site, which you’ll see when we generate the site in a moment.</p>
<h2 id="step-5-creating-a-new-post">Step 5: Creating a New Post</h2>
<p>To create a new post, run the following command:</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>hugo new content content/posts/my-first-post.md
</code></pre><p>This will create a new file in the <code>content/posts</code> directory, named <code>my-first-post.md</code>. When you open it, you’ll see:</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>+++
title = 'My First Post'
date = 2024-09-08T15:44:30+01:00
draft = true
+++
</code></pre><p>The block of text wrapped in <code>+++</code> 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.</p>
<p>Now, you can edit the file to include your first post:</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>+++
title = 'My First Post'
date = 2024-09-08T15:44:30+01:00
draft = true
+++
<span style="color:#800080;font-weight:bold">## Welcome!
</span><span style="color:#800080;font-weight:bold"></span>
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 [<span style="color:#1e90ff;font-weight:bold">Hugo</span>](<span style="color:#1e90ff">https://gohugo.io</span>) website!
</code></pre><h2 id="step-6-previewing-your-website">Step 6: Previewing Your Website</h2>
<p>To preview your website locally, run the following command:</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>hugo server --buildDrafts
</code></pre><p>This will start a local server, and you can view your site by visiting <code>http://localhost:1313</code> in your browser.</p>
<h2 id="step-7-publishing-the-website">Step 7: Publishing the Website</h2>
<p>Once you're ready to publish, update your post by changing <code>draft = true</code> to <code>draft = false</code> (or just delete the <code>draft</code> property) and run:</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>hugo
</code></pre><p>This will build your site and place the generated files in the <code>public</code> folder. This folder contains all the HTML, CSS, and JavaScript that make up your static site.</p>
<p>From here you can deploy it following [Hugo's own guide](<a href="https://gohugo.io/categories/hosting-and-deployment/">https://gohugo.io/categories/hosting-and-deployment/</a>. However, most of these options involve using someone else's compute, and our goal here is self hosting.</p>
<h2 id="step-8-dockerising-your-site">Step 8: Dockerising your Site</h2>
<p>Now that you have a static site in the <code>public</code> 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 <a href="https://gohugo.io/hosting-and-deployment/deployment-with-rclone/">this guide</a> 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.</p>
<p>Create a <code>Dockerfile</code> with the following content</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code><span style="color:#00a">FROM</span><span style="color:#a50"> nginx:1.27.1</span><span style="color:#f00;background-color:#faa">
</span><span style="color:#f00;background-color:#faa"></span><span style="color:#00a">COPY</span> public /usr/share/nginx/html<span style="color:#f00;background-color:#faa">
</span></code></pre><p>This tells Docker to use the official Nginx image and copy the files from your <code>public</code> folder (which Hugo generated) into the default location that Nginx serves from.</p>
<h2 id="step-9-building-and-running-the-docker-image">Step 9: Building and Running the Docker Image</h2>
<p>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.</p>
<p>To build your Docker image, run:</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>docker build . -t <dockerusername>website:0.0.1
</code></pre><p>Here:</p>
<ul>
<li><code>-t <dockerusername>website:0.0.1</code> tags the image with a name (<code><dockerusername/website</code>) and a version (<code>0.0.1</code>), which will be important later when you want to publish it.</li>
<li>the <code>.</code> tells Docker to build the image from the current directory (which contains your <code>Dockerfile</code> and <code>public</code> folder).</li>
</ul>
<p>Now that you have the Docker image locally, you can run it using</p>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>docker run -p 8080:80 <dockerusername>website:0.0.1
</code></pre><p>Here, <code>-p 8080:80</code> maps port 8080 on your local machine to port 80 in the Docker container, where Nginx serves the content.</p>
<p>Now, open a browser and go to <code>http://localhost:8080</code>. You should see your static site served by Nginx!</p>
<p>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.</p>
<ol>
<li>First login to Docker Hub:</li>
</ol>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>docker login
</code></pre><ol start="2">
<li>Push your image to Docker Hub, by default this image will be public.</li>
</ol>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code><span style="color:#a50">`</span>docker push <dockerusername>website:0.0.1
</code></pre><ol start="3">
<li>SSH into the server</li>
</ol>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>ssh user@server-ip
</code></pre><ol start="4">
<li>Pull the Image (we don't need to login since the image is public):</li>
</ol>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>docker <dockerusername>website:0.0.1
</code></pre><ol start="5">
<li>Run the Docker Image</li>
</ol>
<pre tabindex="0" style="background-color:#f0f0f0;-moz-tab-size:4;-o-tab-size:4;tab-size:4;white-space:pre-wrap;word-break:break-word;"><code>docker run -d -p 80:80 <dockerusername>website:0.0.1
</code></pre><ul>
<li><code>-d</code> runs the container in detached mode (in the background).</li>
<li><code>-p 80:80</code> 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.</li>
</ul>
<p>You will be able to access the website by visiting <code>http://server-ip:80</code></p>
<h2 id="conclusion">Conclusion</h2>
<p>Congratulations on creating and running your first static website with Hugo and Docker!</p>
<footer>
<br />
<hr />
<br />
<p>see something you disagree with? email: <a href="mailto:[email protected]">[email protected]</a></p>
</footer>
</main>
</body>
</html>
|
