README.md

What could be more helpful than a guide more interested in a party trick than solving its stated purpose? Probably any other guide right? Our ’trick’ is that this README.md is the same guide used to create the site that you are now reading. In the same manner, this repository also contains this file and describes how it was built. Alright. Maybe it isn’t that cool of a trick but I bet if you didn’t think about it too much you’d think so. We are showcasing static webpages. More percisely a static site generator.

• 1. Introduction
• 2. Prerequisites
•   a. domain
•   b. webhost
•   c. tools
• 3. Repository Setup
•   a. DNS
•   b. repo
•   c. clone
• 4. Hugo
•   a. term
•   a. winget
•   a. powershell
•   a. open
•   a. init
• 5. Web Server
•   a. NginX
•   b. map webroot
• 6. Public Key Infrastructure
•   a. putty
•   b. keygen
•   c. pebbleguy.com
•   d. pageant-start
•   e. pageant-key
• 7. Rclone
•   a. install
•   b. config
•   b. deploy

Introduction

Why are we doing this? Static pages are what webservers were built for. Dynamic pages are largely tools for the developer. Our world is often a weird broken mess of wonderful things. There is a project, squid, that can magically increase one’s internet speed. The project has been around for nearly 30 years and it isn’t magic, they just recognize that most the Internet is thoughtlessly dynamically generated. A static page is what browsers and servers are designed to handle and they struggle when pages are complicated black boxes¹. I am being a little harsh, it isn’t that pages are slapped together thoughtlessly, I mean to say that given infinite ’thought’ resource only what needed be dynamic would be.

This guide was primarily written to support someone with a Windows computer. Things may look and feel complex due to a bunch of tools, screenshots, button clicks and stuff but if you look at the Debian guide one can see we are’t actually accomplishing that much. We can also see that goals of this guide could be completed in a number of different environments. There are several tools that fill in where Windows lacks features or where a solid Microsoft application is not yet developed. These tools are pre-compiled for us and provided by their authors to Windows users at-large. This guide would not be possible without their contributions. I say this to clear up inevitable misunderstandings caused by us gluing softwares together and the shortcomings that we will witness.

The guide tends to be a little on the verbose side, both becuase I lack clarity, also because I hope the additional details are useful. As a warning, when you fall off a cliff the guide can’t catch you, it’s just going to watch your inevitible tumble down the mountainside. I suppose what mean is one should expect a few scrapes and bruises, expect frustrations and mistakes.

Prerequisites

We will be installing and maintaining a website therefore we need a domain². You will already need to have registered a domain for your use, this is not something this guide covers. You should prioritize the DNS instructions early due to the inherent delays in DNS propagation. You will also need access to Dan’s server pebbleguy.com. Pebbleguy.com will serve as a location to store our files and it will host our website. Websites are forever changing it makes sense that a requirement would be that we need a place edit our site, we won’t directly solve that problem but at times we will make an effort and will need both git and an interactive developer environment. These three things are really all that we need, each might hide difficulties, but nothing we cannot handle.

The Debian guide shows us a high level what we wish to accomplish with this guide, but we will need a few extra things. We are going to assume that the Windows user already has git setup and they know how to use it. They are going to need to connect to a remote server because Windows lacks several low-level API calls required by many reliable servers³. The requirement to a remote server means one needs to be careful and run some commands on the local Windows host and some using SecureShell (SSH) on a remote host. In addition files need to be synced between the local and remote side which means we need more tools and configs.
The installation of Hugo is the tiniest bit more complex⁴.

To follow this guide we adhere to not storing easily exploitable private keys, especially in a hostile environment like our target operating system. We need several tools to support Microsoft’s lack of priorities in this arena. We will be encrypting⁵ our private keys to protect pebbleguy.com. We will need access to Public Key Infrastructure (PKI) tools like those provided by PuTTY. Lastly we will need access to a syncronization tool, we picked Rclone as a solution for the Windows environment.

A Debian guide shows the road ahead

# Debian version of static site using Hugo
# --
: "you will need to add a DNS record for the kyleguy.rome7.com with your domain registrar"
# PART 1: install hugo and setup NginX configs for our webserver -----------------------------
sudo apt install hugo;
git clone https://git.pebbleguy.com/Dan/pebbleguy.com;
cd pebbleguy.com/scripts && ./certbot-wrapper.sh -h kyleguy.rome7.com -u kyle;
# PART 2: Create the site --------------------------------------------------------------------
cd /mnt/external/projects && mkdir kyleguy && cd kyleguy && git init && touch README.md
hugo new site web && cd web
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo "theme = 'ananke'" >> hugo.toml
sudo ln -s /mnt/external/projects/kyleguy/web/public/ /mnt/external/websites/kyleguy.rome7.com
# PART 3: Commit the website and push the repository to git.pebbleguy.com --------------------
git add --all && git commit -m'added a static site with hugo'
git remote add origin http://git.pebbleguy.com/kyle/kyleguy.git
git push -u origin master

What we see is that the user made sure that they had a DNS record for kyleguy.rome7.com then installed hugo. They pulled a copy of the pebbleguy.com repository so that they could execute the certbot-wrapper.sh to setup a webserver with a certificate signed by a certificate authority. They then setup a webroot and added a theme to their static site. Lastly they committed their site contained in a new git repository to git.pebbleguy.com.

Repository Setup

Configure the your domain registrar’s DNS

This assumes you are using the DNS provided by your domain registrar. Some common registrars are Cloudflare, SquareSpace, Wix, GoDaddy, Gandi, Namecheap, and others. FYI, I listed some bad and some good ones, not a review just blasting.

Not necessarily the first thing that needs to be accomplished, but if it is done early time can be saved while the DNS provider tries to spread the word out to the internet about your domain. Add a record for the domain name. In this example we add kyleguy.rome7.com, you only add a record for the subdomain part, kyleguy. You are the decision maker for what domain points to this site. My site will be hosted on pebbleguy.com so I use a CNAME so that when people go to my site they will know where my site is located. I did not want a site at rome7.com so I am creating a subdomain:

Create a git repository

Login to your account on git.pebbleguy.com. Click the add repository button:

Then fill out the form. We will use some predefined options to template our gitignore file and have Gogs initialize the repository for us.

This is what the mostly empty repository looks like if you were successful:

Get a copy of the repository on your computer

Open powershell or cmd:

You will clone the repository to your desktop, type these commands into the powershell terminal. The output should match closely with the example. You will want to replace the clone url with your own repository.

cd Desktop
# https://git.pebbleguy.com/{{your_gogs_account_name}}/{{repository_name}}
git clone https://git.pebbleguy.com/kyle/kyleguy

With the repository cloned to your desktop successfully, you should be able to use the Windows file explorer to view the files:

Install Hugo

Hugo is our static site generator. We will install it on a local Windows computer.

First up is to install Hugo using the windows package manager, winget.

Open a terminal

Download and install hugo

winget install Hugo.Hugo.Extended

We will need the steps from the repository setup portion of the guide completed before we continue.

This next bit will fail, but we document it here in case you run into it.

Wow cool, we have a copy of the kyleguy repository on our windows computer. We can initilize a hugo static site.

Windows is really cool they have a feature where they print red text until you close and reopen the terminal:

Actually this is a good break, because we cannot use Windows Powershell we need Powershell. Yeh. I cannot fix that. Pretty wild. There is a difference. We will jump back here, but we need to install Powershell first.

Install Powershell

Open up that terminal, then use winget to install powershell.

Launch Powershell

We launch powershell a little differently:

Initilize a static page using hugo

Let us initilize the files needed for our website:

cd Desktop/kyleguy
hugo new site web
cd web
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo "theme = 'ananke'" >> hugo.toml
hugo server

If that worked it will look something like this:

In addition there will be a webserver on our Windows computer. I think hugo will serve the site http://localhost:1313/. This feature is nice and allows us to see our website while we work on it:

some final steps We should probably add our site to the repository. And that website is pretty basic so one should follow the hugo tutorials to upgrade the page. All the files are in Desktop/kyleguy/web if you’ve been following closely. Use a terminal for git commands. Maybe edit the .gitignore file to include some folders using our deep knowledge of hugo:

# Hugo
/web/public/
/web/resources/_gen/
/web/assets/jsconfig.json
/web/hugo_stats.json
/web/hugo.exe
/web/hugo.darwin
/web/hugo.linux
/web/.hugo_build.lock

Then add our site and commit:

git add *
git commit -m'added a hugo site'
git push

A place called home, or maybe webroot

Webroot is jargon that we should try to use when talking about websites. It refers to a directory⁶ that is arbitrarily choosen and then named webroot.

Our webroot is going to be /mnt/external/websites/kyleguy.rome7.com. We are going to store files in an adjacent directory⁷, /mnt/external/projects/kyleguy/web/public, further explained when we do the site setup.

You are going to need a domain, either buy one or be a person whom already has a domain. We are going to host our site on pebbleguy.com using the NginX (“engine x”) web server. We will create a site configuration file with SSL using a tool, certbot-wapper.sh⁸.

Run certbot-wrapper.sh:

Login to your account on pebbleguy.com using Secure Shell (SSH) or ask Kyle, Chris, Daniel, or Emma for help. If you are one of those people, hello! Download the pebbleguy.com repository so you have access to the script and run certbot-wrapper.sh to have it create the NginX config file for your site:

git clone https://git.pebbleguy.com/Dan/pebbleguy.com
cd pebbleguy.com/scripts
./certbot-wrapper.sh -h kyleguy.rome7.com -u kyle

You can skip the next bit to map webroot. We just explain some of the patterns we follow on pebbleguy.com

This should create a configuration file either on the external disk or primary disk depending on if pebbleguy.com is in Read-Only or Read-Write mode. More info on that here. The locations are either /mnt/external/live-server-configs/for-nginx/sites-enabled/kyleguy-web.conf or /etc/nginx/sites-enabled/kyleguy-web.conf.

Keep those file locations in mind for later.

When I ran certbot-wrapper the system was in Read-Write mode so my config was created /etc/nginx/sites-enabled/kyleguy-web.conf:

server {
        server_name kyleguy.rome7.com;
        # listen 80;
        listen 443 ssl;
        index index.php;
        root /mnt/external/websites/kyleguy.rome7.com/;

        location / {
            # first attempt to serve request as file, then as directory, then fall back to displaying a 404.
            try_files $uri $uri/ =404;
        }

        # reverse proxy for initial certbot http challenge (we have certbot listen on 888)
        # include /etc/nginx/includes/certbot-web-plugin.conf;

        # include php by default
        include /etc/nginx/includes/php-location-directives.conf;

        ssl_certificate /mnt/external/live-server-configs/letsencrypt/live/kyleguy.rome7.com/fullchain.pem;
        ssl_certificate_key /mnt/external/live-server-configs/letsencrypt/live/kyleguy.rome7.com/privkey.pem;
        # include /etc/nginx/snippets/ssl-params.conf;
}

Now we need to create a directory to store our site. You’ll notice in the generated config file it has some defaults choosen for us, root /mnt/external/websites/kyleguy.rome7.com/;. It hasn’t actually done any of the work it is meant only to bootstrap a config file and retrieve SSL certificates for https. If you use your SSH connected terminal to navigate to the external drive you will see a projects directory:

cd /mnt/external
ls

will show:

username@pebbleguy:/mnt/external $ cd /mnt/external
username@pebbleguy:/mnt/external $ ls
gogs  live-server-configs  lost+found  projects  websites

You will put your site repository into the projects directory. You will also notice a websites directory. You could put your website there, but you’d get caught in an organizational nightmare. Instead we will put a sort of shortcut into the websites directory that points to the actual website directory that is contained in our repository. This way we don’t ever need to come back to this terminal on pebbleguy.com to mess around with our files ever again, probably.

Map webroot

username@pebbleguy:/mnt/external $ sudo ln -s /mnt/external/projects/kyleguy/web/public/ /mnt/external/websites/kyleguy.rome7.com
username@pebbleguy:/mnt/external $ ls /mnt/external/websites
emma-kac  gogs-webhooks  KingsAndChaos  kyleguy.rome7.com  shootGame  www.pebbleguy.com

Public Key Infrastructure

Windows does not have ssh-keygen, install it or a replacement:

Install PuTTY by Simon Tatham. Besides the SSH Terminal PuTTY program there is also a ssh key generator program called PuTTYgen.

Launch PuTTYgen and generate a key

One can generate any number of ssh-keys⁹, RSA, ECDSA, and ED25519 are all good options. If you select the EdDSA radio button you can follow along, but feel free to try one of the other key types I mentioned.

You then click genrate and move your mouse around a bit in the Key window to add a little more noise that what would normally be provided by Windows’ entropy pool.

Once the key generates, add a comment and a passphrase. You may use one of the passwords that you normally give to Microsoft, your bank, and Amazon. You aren’t securing anything super important. You are just trying to obscure access like you normally would with your financial details. Is that a tongue in my cheek? Heh.

The last thing to do is save the private key somewhere. I just put it on my Desktop. It is encrypted it isn’t going to be useful to anybody without my passphrase.

Copy the public key to pebbleguy.com

In the above screenshot you can see the public key in the PuTTYgen window. I will copy my key to pebbleguy.com and you will copy yours. You may copy the public key to your clipboard then paste it into your users’ authorized keys¹⁰ on pebbleguy.com.

To copy your public key¹¹, connect to pebbleguy.com and run the below command (make sure to substitue your public key).

echo 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGYtvZuiyun9DQe/6xrxby0iQeLy+jE1JKrpgRrHKbrT windows computer rclone key for kyleguy' |tee -a ~/.ssh/authorized_keys

If you used ssh-keygen to generate a key there should be a companion tool, ssh-copy-id that can be used to help install the public key on a remote server.

Add a Pageant shortcut to Windows startup

The Rclone software that we will use to synchronize our website files does not support decryption of private keys. They do however support requesting an external program to decrypt a key, unfortunatley not the Windows Credential Store ¹². Luckly though, the author of PuTTY also wrote a minimal keystore¹³ called Pageant.

We could also use Gpg4win which was funded by Bundesamt für Sicherheit in der Informationstechnik (Germany’s Federal Office for Information Security). I would have recommended this path but I didn’t have time to explore it fully.

The Pageant software is bundled with the PuTTY installer so once you install PuTTY we can setup Pageant to load when Windows loads.

If you are using ssh-keygen you should also have access to ssh-agent which can be configured to aid Rclone with encrypted keys. GNU’s GPG-agent would do the same thing but I’m not sure what would happen if Rclone made a request.

Tell Pageant about our key

Using the shortcut we just created, we will provide Pageant a way to find our key.

The Windows properties dialog window has a tab, Shortcut with a taget property that you will set to a value like this:

"C:\Program Files\PuTTY\pageant.exe" --encrypted C:\Users\valued-customer\Desktop\windows-rclone-key-for-kyleguy.ppk

The --encrypted flag that tells pageant that the key is encrypted and to not prompt for the user to enter a passphrase until it is used for the first time. This is an stops it from immediately prompting for the passphrase regardless of you using the key. When pageant launches it will put a task manager GUI shortcut in the taskbar. One can view what keys pageant knows about. Later Rclone will be able to ask pageant to authenticate ourselves with pebbleguy.com.

Rclone

Install Rclone

Windows does not have any good generic file synchronization tools. Nick Craig-Wood wrote a synchronization tool focused on commercial cloud storage products and his team ported it to Windows. I’ve never used it but Rclone seems well liked and well supported. Compiled released binaries can be had using the Windows package manager winget.

winget install Rclone.Rclone

---

Add an Rclone config for kyleguy

We can tell Rclone about our website and a scheme to update the webserver with changes made to our local static site by providing it configuration directives. Using a Windows terminal, we can issue this Rclone command to generate a config file. Additional configuration documentation is available online. This will make it easier to provide all the details to Rclone every time it is envoked.

By default this will put the config file into your Windows AppData path, C:\Users\valued-customer\AppData\Roaming\rclone\. This is fine, we could also store the config somewhere else like the repository. I’ll include both incase one seems better. Just don’t get clever and store your private key in the repository. This config has few little security implications, in mine I leak just my pebbleguy.com username, jb6113. As stated earlier we are not leaving unencrypted keys on Windows so we explicitly avoid the directive telling Rclone about our key: key_file "C:\Users\valued-customer\Desktop\windows-rclone-key-for-kyleguy.pem". This won’t work anyways as our key if formatted as a .ppk so the Rclone wouldn’t be able to read it as-is. Instead we tell Rclone to use an ssh-agent, this is set to true by default but we are going to explicitly set it.

Default path:

rclone config create kyleguy sftp host "pebbleguy.com" user "jb6113" key_use_agent "true"

Copy config to our Hugo static site project repository rclone.conf:

cp 'C:\Users\valued-customer\AppData\Roaming\rclone\rclone.conf' 'C:\Users\valued-customer\Desktop\kyleguy\'

Hugo Rclone Deploy

When we are happy with the results of our work on the local development computer, we can deploy the site to kyleguy.rome7.com using the following command snippet:

cd Desktop\kyleguy
rclone sync --config rclone.conf web\public\ kyleguy:/mnt/external/projects/kyleguy/web/public/

The first time we do this Pageant will prompt us to provide the passphrase for our encrypted private key:

Just in-case you get a permission denied

This is just because your user is not allowed to write files to the target location. You’ll log into pebbleguy.com and use ls -lathr on the directory you are trying to copy into and look at the permissions. Right now it is out-of-scope to explain users and permissions. I expect that with so many users “helping” eachother out that we should all be familiar with the side effects of what happens when we accidentally forget about permissions. In general all the admin users have been added to a group, www-data. By default files created by a user are owned by that user. This is the root cause of these accidents but is a sane method for file creation. We should learn to be cognizant of the environment we are in and not expect that anyone but ourselves are able to know what our intentions were.