How to Start a Website the Hard Way

So you want to build your website and all the other tutorials haven’t caught your attention? Well then, let’s do this!

The plan

I’ll be showing you how to create a simple, static website built with Hugo, that will be served from our own* webserver living somewhere on the Internet. The site contents will be stored on GitHub and we’ll be using GitHub Actions to build and deploy our site onto the server.

* This is a bit of an overstatement. We’ll rent a VPS from some provider, we’re not going to actually build a server and connect it to the Internet.

What we’ll need?

Disclaimer: there are simpler setups to do this! You could just serve your site on GitHub pages with a custom domain but that’s not how I roll. I want to have the option to serve dynamic content from my own server or move my whole site to a different server if need be. If that sounds unnecessary to you, find something simpler.

So let’s start with a list of stuff we’ll need:

A server
A domain
A GitHub repo
Some tools
1. Ansible
2. Hugo

Step 1: setting up the repo

Let’s start where all good projects should start: with a repo.

Note: I’ll be going with a terminal-heavy approach, but if you feel better in graphical environments, feel free to use your preferred tools

Go to GitHub and create a repository named yourdomain.com.

Now go to your terminal and type:

mkdir ~/yourdomain.com
cd ~/yourdomain.com
echo "# yourdomain.com" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin [email protected]:username/yourdomain.com.git
git push -u origin main

Step 2: The most basic Hugo site

If you have a repo ready, let’s fill it with some content.

First install Hugo and make sure it’s running. You should get some variation of this in your commandline:

$ hugo version
hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended linux/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio

Now run the following commands:

hugo new site ./site
mkdir site/layouts/_default
cat <<'EOL' >> site/layouts/_default/list.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>My Website</title>
  </head>
  <body>
    <main>
        <h1>Welcome to My Website</h1>
        <h2>{{ .Title }}</h2>
        {{ .Content }}
        <ul>
           {{ range .Pages }}
           <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
           {{ end }}
        </ul>
    </main>
  </body>
</html>
EOL
cat <<'EOL' >> site/layouts/_default/single.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>My Website</title>
  </head>
  <body>
    <main>
        <h1>Welcome to My Website</h1>  
        <h2>{{ .Title }}</h2>
        {{ .Content }}
    </main>
  </body>
</html>
EOL
hugo new -s site _index.md
sed -i 's/draft: true/draft: false/; s/title: ""/title: "My homepage"/' site/content/_index.md
echo "My content" >> site/content/_index.md
hugo new -s site/ posts/first-post.md
sed -i 's/draft: true/draft: false/;' site/content/posts/first-post.md
echo "My first post!" >> site/content/posts/first-post.md

Now we can run a hugo server and see the seed of our website.

hugo serve -s site/ -d ../www

Hugo should provide you with a link to localhost server and you should be able to navigate from the homepage to your posts page and to your first post.

Before we commit anything to git check the contents of your directory.

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        site/
        www/

Wait… www? This directory was created by the hugo serve command, it contains our built static website. We should ignore it as far as version control goes, so let’s.

echo "www/" >> .gitignore

You should also probably edit your site config file, i.e. site/config.toml and then we can commit our new website to git.

git commit -a -m "Hugo site scaffolding"

Step 3: Setting up a server

NOTE: This article is under construction

Additional resources

Even for a simple static website, there is quite a lot going on here. I highly recommend reading up on some of the tools we’re using here.

Hugo

Hugo is higly opinionated and not intuitive. I recommend picking up Brian P. Hogan’s Build Websites with Hugo. It’s an short, step by step introduction to the tool.

Ansible

Managing servers is hard and there are way too many tools to do it. I like Ansible because it’s just a level above shell scripts and it requires only ssh to be running on the server side.

Jeff Geerling has an awesome series on YouTube on this topic. Alternatively, if you prefer books, buy Ansible for Devops by Jeff. Mostly the same content, different form.

Web design

HTML and CSS are here to stay, better get used to them. To make your site look better consider learning a little bit about them. Personally I would recommend this website building course on Udemy, but there are plenty other resources out there.

Linux administration

Whatever I know about administering Linux i learned from Using and Administering Linux books. Easy to follow, step-by-step, comprehensive explanations. Highly recommend.