diff options
| -rw-r--r-- | content/posts/switching-to-hugo-one/index.md | 55 | ||||
| -rw-r--r-- | content/posts/switching-to-hugo-two/index.md | 144 |
2 files changed, 199 insertions, 0 deletions
diff --git a/content/posts/switching-to-hugo-one/index.md b/content/posts/switching-to-hugo-one/index.md new file mode 100644 index 0000000..c01fa7b --- /dev/null +++ b/content/posts/switching-to-hugo-one/index.md @@ -0,0 +1,55 @@ ++++ +title = 'Switching To Hugo: Part One' +description = 'The reasons why I made the switch to Hugo.' +date = '2024-12-18T07:22:35-05:00' +draft = false ++++ + +*This post is part one in a two-part series on switching my website to +[Hugo](https://gohugo.io). It covers my reasoning behind making the switch. For +the technical details on hosting my website, read +[part two](/posts/switching-to-hugo-two/).* + +# A Re-Introduction +Hello friends, and welcome [back] to my blog! It has been quite some time since +my last post, and I thought I'd take a moment to catch everyone up to speed on +the changes I've made since then. + +## A "new" website. +For those reading via RSS, you will notice little to no change. However, if you +point your browser to https://tdback.net, things will look noticeably +different. + +Some may recall that my old website employed the use of the +[TiddlyWiki](https://tiddlywiki.com), a wonderful piece of software that allows +you to create a non-linear notebook for organizing and sharing complex +information. The downside to using a TiddlyWiki as my primary blogging platform +was the need to do almost everything in the browser. As someone who spends a +majority of their time editing text inside [neovim](https://neovim.io), I found +myself sorely missing my beloved [vim motions](https://vim.rtorr.com/) and the +ability to quickly move around my system using tools such as `tmux` or `fzf`. +In short: I missed my terminal. + +When researching static site generators, I stumbled across the ever so popular +[Hugo](https://gohugo.io). I immediately found it quite compelling: writing an +entry to my blog would be nothing more than editing a markdown file, and I +could write scripts to easily generate and deploy my site to a web server. Hugo +also comes with a built-in RSS feed generator, meaning that I didn't have to +[write one myself](https://old.tdback.net/#Hacking%20on%20RSS) (although I +quite enjoyed doing so). + +While I've traditionally thrown my site's index.html file onto GitHub Pages +and/or Codeberg Pages, as a hobbyist self-hoster I'd be doing an injustice by +not hosting the server on my own hardware. While I would encourage others to +take advantage of free static site hosting services such as +[Codeberg Pages](https://codeberg.page/), I've found that I quite enjoy the +responsiblities, challenges, and learning opportunities associated with +self-hosting. + +## Closing Thoughts +So far my experience with Hugo has been great! After just a few hours I had a +working site, RSS feed, and an established workflow for writing. If you're +interested in the technical details of how I host my website, read onwards to +[part two](/posts/switching-to-hugo-two/). + +Happy hacking! diff --git a/content/posts/switching-to-hugo-two/index.md b/content/posts/switching-to-hugo-two/index.md new file mode 100644 index 0000000..2b95f51 --- /dev/null +++ b/content/posts/switching-to-hugo-two/index.md @@ -0,0 +1,144 @@ ++++ +title = 'Switching To Hugo: Part Two' +description = 'The technical details of hosting my website.' +date = '2024-12-18T07:31:05-05:00' +draft = false ++++ + +*This post is part two in a two-part series on switching my website to +[Hugo](https://gohugo.io). It covers the technical details of hosting my +website. For an explanation as to why I made the switch, read +[part one](/posts/switching-to-hugo-one/).* + +# Hosting my website +My website is hosted on [caddy](https://caddyserver.com), a popular HTTPS +server and reverse proxy. Caddy automatically obtains and renews TLS +certificates for my domains, which makes TLS certificate management a breeze. +The caddy server runs on one of my home servers, which itself runs NixOS. + +## Configuring a web server on NixOS +[NixOS](https://nixos.org) allows for reproducible and declarative system +configurations, which makes the process of configuring and deploying a web +server quite trivial. One benefit of running my website on NixOS - aside from +the fact that NixOS is my distribution of choice - is that I can copy the +configuration down to any of my NixOS systems and have it work exactly the +same, regardless of the server it's running on. This alleviates the headache of +dependency management and reduces setup times down to just +`nixos-rebuild switch`, should I have the need to move my website to different +hardware. The [nix flake for my system +configurations](https://codeberg.org/tdback/nix-config) is tracked in a remote +repository with `git`, making configuration changes a single `git pull` away. + +The following module defined in `modules/services/proxy/default.nix` enables +the caddy service using the `caddy` package found in +[nixpkgs](https://search.nixos.org/packages?channel=24.11&query=caddy), +and opens up both TCP ports 80 and 443 to accept inbound HTTP/S traffic. +```nix +{ pkgs, ... }: +{ + services.caddy = { + enable = true; + package = pkgs.caddy; + }; + + networking.firewall.allowTCPPorts = [ 80 443 ]; +} +``` + +Then, in a separate module defined in `modules/services/web/default.nix`, I've +created a caddy virtual host entry for my domain name. By pairing the +`file_server` and `root` directives together in caddy, I can spin up a web +server and host the content found in `/var/www/tdback.net/` on the NixOS +server. I've also enabled both gzip and zstd support for compressing web server +responses. + +```nix +{ ... }: +{ + services.caddy.virtualHosts = { + "tdback.net".extraConfig = '' + root * /var/www/tdback.net/ + encode zstd gzip + file_server + ''; + }; +} +``` + +The server is made publicly accessible using [IPv6rs](https://ipv6.rs), which +is a wonderful service I plan to cover in future blog posts. A few DNS host A +and AAAA records are required to properly resolve queries for +https://tdback.net to my web server's IPv6 address (including requests made to +the server using IPv4!) but that's pretty much it in regards to the server +configuration. + +## Writing and managing content +The following is a nix flake I've written to create a development environment +on my desktop for managing the content and generation of my website. + +```nix +{ + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + flake-utils.url = "github:numtide/flake-utils"; + }; + + outputs = { ... }@inputs: + inputs.flake-utils.lib.eachDefaultSystem (system: + let + pkgs = import inputs.nixpkgs { inherit system; }; + in + { + devShells.default = pkgs.mkShell { + buildInputs = with pkgs; [ + hugo + ]; + + shellHook = '' + SITE="$HOME/projects/tdback.net" + + new-post() { + hugo new "posts/$1/index.md" + $EDITOR "$SITE/content/posts/$1/index.md" + } + + del-post() { + POST="$SITE/content/posts/$1" + [ -d $POST ] && rm -r $POST + } + ''; + }; + }); +} +``` + +When I run the command `nix develop` in my terminal, nix automatically creates +a new shell environment, pulls down the `hugo` command from the specific +revision of nixpkgs found in `flake.lock`, and defines the functions specified +in the `shellHook` attribute. + +By storing this flake and my website's source code in a git repository, I can +clone the repo down to an entirely separate machine - for instance my laptop - +and have an entirely reproducible shell environment for working on my website. + +I also have the added bonus of being able to completely blow away the temporary +shell environment when I exit out of the terminal or type `C-d` (the same as +`exit`). This means that `hugo` and any functions or environment variables +defined in the `shellHook` attribute are *only available when I'm in the +temporary shell environment*, thus reducing the clutter of programs, their +dependencies, environment variables, and function definitions. + +## Deployment of the site +When I make a change to the website, the entire site can be regenerated and +deployed to the NixOS server by running the following one-liner: + +```bash +hugo && rsync -avz --delete public/ hive:/var/www/tdback.net/ +``` + +I've placed this command in a shell script to make deployments as simple as +typing `./deploy.sh`. This results in near-zero downtime between changes: a +simple refresh of the page on a client's device will load the newest version of +the site. + +Happy hacking! |