Tutorial: make a website with Samizdat and Hugo

So, let’s build a site with Samizdat. Yes, Samizdat already lets you do that! Now, it will not be an e-commerce website, with customer login, big databases and the like. No, no, no, no! For that, you will still need to go through the usual boring route. Here, we will build a simple static website, like a blog. These are just like files in a folder that you have in your local computer. In fact, most modern browsers let you serve a site that way, directly from disk.

To help us in our journey, we will use a nifty little tool called Hugo, a static website generator (actually, one of the most popular ones). So, if you don’t have Hugo yet, go get Hugo now and then come back here! Hugo, when you boil it down to the basics, is a program that takes a bunch of Markdown files and builds all the pages of your blog from them, adding style and structure along the way. The result is, unfortunately, just a folder full of HTML files.

To create an actual website out of this, you would upload this file to someone and this someone would run a program that distributes your HTML pages to the whole world via a protocol, called HTTP. This is the usual way we do it nowadays, at least. With SAMIZDAT, things are different. You just export your files to your local Samizdat client and the Samizdat network does the rest for you. Of course, there is no magic trick here. If nobody is actively waiting for your files and you just shut down your computer, your content will be utterly unavailable. But this is a story for another time; we are getting way ahead of ourselves here!

First, the basics.

Installing Samizdat

Before we can publish anything, we need a Samizdat node running on the local machine and the samizdat CLI to drive it. The friendly path on macOS and Linux is:

brew install tokahuke/samizdat/samizdat
sudo samizdat-up install node

The first command installs the samizdat and samizdat-up binaries. The second one uses samizdat-up to install samizdat-node as a system service (systemd on Linux, launchd on macOS), so the node comes up on boot and stays out of your way. Once that finishes, you can hit http://localhost:4510/ in a browser and see your node’s local landing page; if you do, you are ready to keep going.

Setting up a new project

Create a new folder in your computer in your favorite spot. Call it singalong_blog. Then, use your preferred command line interface and navigate to that folder. We are now ready to start.

First, let’s create a new Hugo project in this folder. That can be accomplished by the following command:

hugo new site .

If you now list the contents of the folder, you will see that some new files and subfolders appeared. This is the structure of a fresh new, clean slate Hugo project.

Now, for the Samizdat part. Just as we have created a Hugo project, we need to create a Samizdat project on top of that:

samizdat init

This creates two important new files: Samizdat.toml and .Samizdat.priv (this second file starts with a dot, so it’s “hidden”. You might not see it without ls -a on Linux or Mac). We will spend more time on these files later on. You will also be greeted by the following perturbing message:

NOTE: Your private key for this project is 

        jWb7KO8J_tIdOwSgV2AYIl90zma3QreB-Lo3aDR3rjk
        

Store it somewhere safe! (you were warned)

As it states, this is the private key for your project. It is stored in .Samizdat.priv if you don’t want to store it “somewhere safe” right away. However, it is the secret that will be used to deploy your content to Samizdat. Lose the key and you will not be able to update your website ever again. It will be frozen in its final state from the time you lose your keys. And no, there is no “recover password” button for you to click in desperation. It’s just gone. So please, by all means, store it somewhere safe (a password manager is a good candidate).

Adding some content

Hugo deserves a tutorial on its own and indeed there is one readily available with much more detail that I can provide here. Since the objective of this tutorial is not to create a beautiful new Hugo site, let’s do it the quick-and-dirty way, skipping all the fancy bells and whistles and keeping to the bare minimum.

First, we need to get a theme for Hugo to work. There are plenty of flashy and fancy themes out there, but we will use Archie for our project. To get Archie, just run the following code:

cd themes
git clone https://github.com/athul/archie.git

Then, we need to configure Hugo’s config.toml. Just substitute whatever is there with this:

baseURL = '/'
languageCode = 'en-us'
title = 'My New Hugo Site'
theme = "archie"

Now, we are ready to actually add some content. In hugo, content goes into the content folder. Let’s create a blog post, then! Copy the following (rather terse) blog to content/posts/my-post.md:

---
title: Sample post
description: My first post
date: 2024-10-01
---

We all love dear leader [Pooh][1]! May his pot be ever full of "hunny".

[1]: https://en.wikipedia.org/wiki/Censorship_of_Winnie-the-Pooh_in_China

To see that everything is working as expected, run hugo serve and check if you see a barebones homepage with a link to our post.

Interactive build with samizdat watch

Samizdat can deploy your content in your local client for you to play around before committing your content to the network. As seen above, Hugo also has such capability with hugo serve, but it will serve via vanilla HTTP; it has no knowledge of all this Samizdat thingamajig. Since we need to know how our content will work as part of the Samizdat network (which is ever so slightly different from vanilla HTTP), it’s no good to us. Therefore, we need to use the subcommand samizdat watch.

This subcommand runs continuously waiting for changes in the project folder and, when it finds one, triggers a build command that will create a new version of the website. The source folder for the rendered pages as well as the build command are configured in Samizdat.toml, in the [build] section. Since Hugo by default outputs all pages and files to a folder called public, our [build] section should look something like this:

[build]

# the folder that contains all the data for the website
base = "public"
# the build command
run = "rm -rf public && hugo"

You may go ahead and substitute the default [build] section that was created by samizdat init and copy the one above in its place.

While we are looking at Samizdat.toml: at the top of the file you will see [series] and [debug] blocks, each with a nickname key. That key is the node-local label your CLI uses to find the series on your own node; it has no meaning to anyone else on the network. What the network actually keys off is the public-key underneath it. If you have older docs or an older sample project that uses name = "..." instead of nickname = "...", just rename the key; that is the only change.

Publishing

With the build section wired up and samizdat watch happy, there are three commands you will use over and over for the rest of the project:

• samizdat watch rebuilds and republishes to the [debug] series every time a file changes. This is the develop-test loop. Editions on the debug series are not announced to the rest of the network, so drafts do not leak out, but you can still open them in your browser at the debug series’ own series-<base32-key>.localhost:4510 subdomain; the samizdat commit output prints the URL for you.
• samizdat commit does the same thing as watch but one-shot: build once, publish one debug edition, exit. Useful in scripts and CI.
• samizdat commit --release is the real publish. It builds, then signs and announces a fresh edition on the public [series]. This one is irreversible: there is no “unrelease” button, and any node that has already subscribed will pick the new edition up the next time its hub broadcasts your announcement. Triple-check before running it.

A typical Hugo session looks like: kick off samizdat watch, leave it running in one terminal, edit posts in your editor, hit save, see the node automatically pick the rebuild up. When the site looks good, kill watch and run samizdat commit --release once.