<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
    <channel>
        <title>Posts on d0cuments</title>
        <link>https://blog.klercke.com/posts/</link>
        <description>Recent content in Posts on d0cuments</description>
        <generator>Hugo -- gohugo.io</generator>
        <language>en</language>
        <lastBuildDate>Tue, 24 Feb 2026 16:21:14 -0500</lastBuildDate>
        <atom:link href="https://blog.klercke.com/posts/index.xml" rel="self" type="application/rss+xml" />
        
        <item>
            <title>Securing My Digital Identity With YubiKeys and GnuPG</title>
            <link>https://blog.klercke.com/posts/2024-07-21-yubikey-setup/</link>
            <pubDate>Sun, 21 Jul 2024 16:22:05 -0400</pubDate>
            
            <guid>https://blog.klercke.com/posts/2024-07-21-yubikey-setup/</guid>
            <description>&lt;p&gt;
  &lt;figure&gt;
    &lt;img src=&#34;001.png&#34; alt=&#34;A meme depicting a dog using a computer. The meme reads &amp;ldquo;On the internet, nobody knows you&amp;rsquo;re a dog. Nobody.&amp;rdquo;&#34;&gt;
    &lt;figcaption style=&#34;text-align: center;&#34;&gt;...and that&amp;#39;s sort of a problem.&lt;/figcaption&gt;
  &lt;/figure&gt;



&lt;/p&gt;
&lt;p&gt;&lt;em&gt;Note: This post took me nearly two months to complete.
On two separate occasions while working on this, I updated the Windows partition on my PC.
On both occasions, the Windows update broke my Linux partition.
I have not yet been able to recover from the second of these incidents and I am in the middle of migrating to NixOS anyway.
In the interest of finally getting this blog post out, I have opted to finish writing this post in WSL2 on my Windows machine.&lt;/em&gt;&lt;/p&gt;</description>
            <content type="html"><![CDATA[<p>
  <figure>
    <img src="001.png" alt="A meme depicting a dog using a computer. The meme reads &ldquo;On the internet, nobody knows you&rsquo;re a dog. Nobody.&rdquo;">
    <figcaption style="text-align: center;">...and that&#39;s sort of a problem.</figcaption>
  </figure>



</p>
<p><em>Note: This post took me nearly two months to complete.
On two separate occasions while working on this, I updated the Windows partition on my PC.
On both occasions, the Windows update broke my Linux partition.
I have not yet been able to recover from the second of these incidents and I am in the middle of migrating to NixOS anyway.
In the interest of finally getting this blog post out, I have opted to finish writing this post in WSL2 on my Windows machine.</em></p>
<h2 id="part-z3r0-background">Part z3r0: Background</h2>
<p>When you interact with someone on the internet, how do you know they are who they say they are?
Even if you can trust that someone is who they say they are, how do you know that there isn&rsquo;t some third party listening in on your conversation?
The answer to these questions is digital signatures and encryption.</p>
<p>While there are many applications offering ways to send an &ldquo;encrypted&rdquo; message to another user, many of these applications require users to trust encryption keys generated by the app.
Contrasting this, BYOK/BYOE (Bring Your Own Keys/Bring Your Own Encryption) is a cloud computing concept that can be summarized as letting users generate and use their own encryption keys.
While this typically the process of encrypting enterprise data on-prem and then uploading the encrypted data to a cloud provider, I think the BYOK model can (and should!) be successfully implemented by individuals in their daily lives.
Specifically, GPG keys are quite easy to introduce into your daily life (or just sensitive communications) if you are just a little bit technical and solve both the authentication and encryption problems.</p>
<p>Side note on the term &ldquo;GPG Keys&rdquo;:
I use the terms &ldquo;GPG&rdquo; and &ldquo;PGP&rdquo; interchangeably.
If you want to know the difference, <a href="https://unix.stackexchange.com/questions/31996/how-are-the-gpg-usage-flags-defined-in-the-key-details-listing">this StackExchange thread</a> has more detail than I can/care to cover.
While GPG and PGP are different, this post is specifically referring to keys generated by the GNU Privacy Guard tool, so I will usually refer to them as &ldquo;GPG keys&rdquo;.</p>
<p>Another benefit of using GPG keys for &ldquo;DIY&rdquo; encryption is that a message encrypted with a GPG key is also implicitly signed by that key, meaning that a GPG-encrypted message can only be read by whomever holds the keys it is encrypted for (ideally, the message&rsquo;s intended recipients) and it can be trivially verified that the message was signed by a given key.
When I say &ldquo;DIY&rdquo; encryption, I am referring to the small-scale end-user approach to BYOK: manually encrypting a message through GPG and then sending the cyphertext block over whichever channel you choose.
I&rsquo;ve done this for a number of years, from encrypting sensitive data before sending it to a friend of colleague, to automatically attaching my public key and a signed copy of every email I send to the original message, to more advanced (and less applicable for the average person) purposes, like <a href="https://klercke.com/.well-known/security.txt">signing my site&rsquo;s security.txt</a>.</p>
<p>For most of these purposes, I have used my primary GPG key, which has been available on <a href="https://klercke.com/pgp-key.txt">my site</a> for as long as I can remember.
That key is set to never expire, but it&rsquo;s time to retire it for a few different reasons:</p>
<ol>
<li>
<p><strong>I no longer have access to the private key.</strong>
I have not had access to the private key since this keypair was generated.
I stored the private key on my YubiKey, which lets me use the key to perform GPG operations such as signing and encryption, but the private keyfile itself was put onto an encrypted flash drive, which I can no longer get into.
I have known this was going to become a problem for a while, but it has become a bigger issue lately as I have more or less stopped using the primary email address attached to that keypair and have since started using a few emails which are not attached to the keypair.
Since I can&rsquo;t edit the key anymore, I have no way to make these changes.</p>
</li>
<li>
<p><strong>My YubiKey is starting to die.</strong>
I&rsquo;m not at all surprised that this is happening.
I&rsquo;ve had this YubiKey for 4 or 5 years now, carrying it in my pocket every day.
It&rsquo;s pretty surprising that it&rsquo;s held up this long, to be honest.
Currently, it&rsquo;s in a state where I can connect it to one of my computers and read information such as the serial number, but I can only sometimes use the private key stored on it.
Combining this with reason #1 means that my private key is effectively lost (or will be soon).</p>
</li>
<li>
<p><strong>I want to go through the process of generating a new key.</strong>
I was still very new to the GPG ecosystem when I created my &ldquo;primary&rdquo; key a few years ago, and was also nowhere near as familiar as I am today with a many cybersecurity principals.
While I don&rsquo;t think my private keys were ever exposed, I think there&rsquo;s a fun opportunity to generate my new keys under extra-hardened conditions so I can rest assured that my private key was not compromised.
More importantly, I can earn the nerd credits of being able to say that my keys were generated on an air-gapped machine and would never touch a machine that had ever been or would ever be networked.</p>
</li>
</ol>
<p>That all leads us to this post.
I&rsquo;ve documented how I generated my new GPG keypair, what I&rsquo;m using it for, and <a href="https://blog.klercke.com/posts/2024-06-02-blog-setup/#why-documentation-fails">most importantly</a>, why I made the decisions that I made.</p>
<p>I&rsquo;m basing my setup off of <a href="https://github.com/drduh/YubiKey-Guide">drduh&rsquo;s excellent guide</a>, which I would highly recommend reading.
I used this guide for generating my keys a few years ago and again for generating my new keys in this post.
The guide goes into great detail and explains many steps that I was struggling to find documentation for.</p>
<h2 id="part-0n3-key-generation-environment">Part 0n3: Key Generation Environment</h2>
<p>The last time I went through this process, I disconnected my daily-use system from the network, went through the key generation process and then removed the private keys from my machine before reconnecting to the network.
While this is already more paranoid than I need to be, this sort of paranoia is fun, so let&rsquo;s take it a few steps further.</p>
<p>My first thought for a key generation environment was a Docker container that I would remove when I was done using it.
This would be simple to set up and I could even write scripts to automate much of the process, but that also means any malware on my system could theoretically also execute commands in the Docker container, stealing my keys.
Additionally, my understanding is that while files in a Docker container are not directly accessible by the host OS, they are still written to the disk in a way that could theoretically be read back by another actor.
Finally, I didn&rsquo;t want to mess around with having to pass in USB devices, both the YubiKeys and the flash drive that will hold my private keys, into a Docker container and wasn&rsquo;t sure how to do this securely anyway.
For all of these reasons, I decided to throw out the Docker container idea.</p>
<p>My second thought was to use one of my spare Raspberry Pis.
I would install an OS, maybe Arch ARM if I was feeling spicy, connect to the network to install the required packages, then disconnect from the network.
Once I was done with the system, I could just wipe the SD card (or even destroy it since they are so cheap).
This method is actually how the drduh guide suggests going about key generation.
The only thing that kept me from going through this process is that I honestly don&rsquo;t have anywhere to set up a keyboard, monitor, and mouse other than at my desk.
Since I wanted to retain use of my desktop PC, both for writing this post and so that I didn&rsquo;t have to go through the entire key setup process in one sitting, I decided to find another method.</p>
<p>Next, I decided I would boot into a <a href="https://tails.net/">Tails</a> live environment on one of my laptops, a ThinkPad T530 for those curious, and generate the keys there.
I disconnected the SSD that normally lives in the laptop, booted into Tails, and enabled airplane mode (though, enabling airplane mode isn&rsquo;t necessary since I can simply just not connect to any wireless networks).
Since Tails already includes GPG, I was ready to start generating keys.
Luckily though, I got to that point and then decided to call it a night since it was getting late.
I say this was lucky because then next day, I decided to actually review the drduh guide for the first time since deciding to start this project.
I noticed the guide now includes instructions for building a NixOS live image that includes all the software necessary for following the setup guide.
This was <em>perfect</em>.
I had been meaning to give NixOS a try, but even with zero Nix experience, it was trivially easy to build the ISO.
Within a few minutes, I had my trusty ThiccPad booted into the NixOS environment, which even has an offline copy of the drduh guide right on the desktop.
All of the necessary software was pre-installed and all of the instructions in the &ldquo;Prepare GnuPG&rdquo; section of the guide were already completed.
I would definitely recommend using this NixOS image if you want an easy way to set up your key in an airgapped environment.</p>
<p>Unfortunately, the one security concession I had to make is that this ThinkPad is not <a href="https://www.coreboot.org/">corebooted</a>/<a href="https://libreboot.org/">Librebooted</a> (yet).
I considered trying to libreboot the laptop before going through this guide, but the lack of specific instructions for the T530 scared me.
I do think I will try to get my hands on a ThinkPad X220/X230 at some point, though, which I will libreboot and use as my &ldquo;high security&rdquo; machine.
I have some other fun ideas for the X220/X230 project, so there will definitely be a few posts about those if I do get my hands on one.</p>
<p>
  <figure>
    <img src="002.png" alt="A picture showing a ThinkPad T530 booted into a NixOS live image with the Xfce4 desktop. There is a terminal open with the output of the uname -a command">
    <figcaption style="text-align: center;">GPG keyring, meet IRL keyring</figcaption>
  </figure>



</p>
<h2 id="part-7w0-defining-variables">Part 7w0: Defining Variables</h2>
<p>Before we can actually generate the keys, there&rsquo;s some info we need to know, decisions we need to make, and passphrases we need to generate.
I booted up my ephemeral NixOS system, confirmed that all of the &ldquo;Prepare GnuPG&rdquo; steps were already completed, and I was ready to rock.</p>
<h3 id="identity">Identity</h3>
<p>Since this is replacing my every-day personal key, I will use my real name and email for the identity:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-console" data-lang="console"><span style="display:flex;"><span>IDENTITY=&#34;Konnor Klercke &lt;kⅼеrсkе@рrоtоոⅿаіⅼ.соⅿ&gt;&#34;
</span></span></code></pre></div><p><strong>NOTE: Anytime an email address appears in this post, it will obfuscated using <a href="https://obfuscator.uo1.net/">this tool</a> to hopefully prevent bots from adding me to spam lists.
If you try to copy-paste these addresses to email me, I will not receive your message.</strong></p>
<p>I do also plan on creating a separate key for my &ldquo;d0c&rdquo; identity and my work identity, but I only have two spare YubiKeys at this point and will be using both to create two copies of my personal identity.
It&rsquo;s a good idea to keep your identities separated by role, much as you would want to keep your personal email separate from your work email or your standard domain account separate from your domain admin account.
Once a few more YubiKeys enter my budget, I will be following this exact same process to generate new keys for ⅾ0с@z3r0ⅾ4у.ⅾеⅴ and my work identity.</p>
<h3 id="key">Key</h3>
<p>The drduh guide recommends a key type of rsa4096.
Admittedly, I am a novice when it comes to cryptography, but I thought I had my mind up about the type of key I was going to be generating.
Initially, I was planning on completely disregarding this advice and generating an ed25519 key instead due to the tiny size of these keys and the myriad backup options this gives me.
Unfortunately, however, a quick bit of research taught me why this was a bad idea:</p>
<p>Firstly, GPG does not have any sort of key negotiation system.
If I sign a PGP message with ed25519 key and your GPG agent doesn&rsquo;t support ed25519 keys, there&rsquo;s no way for it to &ldquo;fall back&rdquo; to an RSA key.
This means many people and systems would not be able to verify my signatures.
RSA is much more common and is supported by pretty much any system.</p>
<p>Second, it turns out plenty of services don&rsquo;t support ed25519 SSH keys yet, which is quite disappointing.
Notably, I tried to use my ed25519 public key for the admin account in a Linux VM in Azure recently and was met with an error that Azure does not yet support ed25519 keys.
I expect that this will become less of an issue in the future, but I need to be able to use my SSH key everywhere, or it sort of defeats the point.</p>
<p>Third, rsa4096 is the maximum key size supported by GnuPG.
Note that the <a href="https://www.gnupg.org/faq/gnupg-faq.html#sec-11-4">GnuPG FAQ</a> does encourage the use of ECC keys (such as ed25519) rather than rsa3072 or rsa4096 if you need more security than rsa2048 offers, but for the reasons I already mentioned, this isn&rsquo;t really an option.
The large key size doesn&rsquo;t matter much to me since the public key will fit on my YubiKey regardless.
The computational overhead also doesn&rsquo;t matter much to me.
I&rsquo;ve been using rsa4096 keys for years and I have never thought that operations took too long.
I&rsquo;m using my keys a few times a day, not thousands of times per minute.</p>
<p>With all of that out of the way, I can define my key type, using the guide&rsquo;s recommended rsa4096:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-console" data-lang="console"><span style="display:flex;"><span>KEY_TYPE=&#34;rsa4096&#34;
</span></span></code></pre></div><h3 id="expiration">Expiration</h3>
<p>I have traditionally generated non-expiring keys but I have changed my mind on this.
I now believe that regular key rotations promote good key hygiene.
In my professional life, I generally make most keys last 1 year since there is usually an entire team of people that can keep up on key rotation reminders.
Since I will be using this key for myself, I chose to go with a roughly 2 year expiration time, which is conveniently also what the guide recommends.</p>
<p>I&rsquo;m setting the key to expire on June 1st 2026, just under 2 years from when I actually generated it:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-console" data-lang="console"><span style="display:flex;"><span>EXPIRATION=&#34;2026-06-01&#34;
</span></span></code></pre></div><p>I set multiple reminders in my calendar to renew my subkeys before they expire.</p>
<h3 id="passphrase">Passphrase</h3>
<p>The guide provides a handy script to generate a 30-character random password, but it also recommends <a href="https://diceware.rempe.us/#eff">Diceware</a> as another option for generating a passphrase.
Since each Diceware word is a 5-digit number, a 6-word Diceware phrase can be also be encoded in 30 characters, which are all numbers 1-6.
In my mind, Diceware provides additional security for a number of reasons:</p>
<ol>
<li>
<p>Diceware can be generated 100% offline on actual dice.
The Diceware lookup site is a static HTML site which is included in the NixOS image I am using.
These facts combined mean that I can use a truly random analog random number generator to generate my &ldquo;seed phrase&rdquo;, then convert that into an actual passphrase 100% offline.</p>
</li>
<li>
<p>Since my paper backups can be a stream of 30 digits, which then have to be converted into my actual passphrase, it is less likely that someone could find themselves in possession of my paper backups and gain access to my private key.
In my mind, this is better than directly writing my passphrase on a piece of paper.</p>
</li>
<li>
<p>It gives me another use for all of these damn D&amp;D dice I bought.</p>
</li>
</ol>
<p>Speaking of paper backups, the 30 character passphrase length is convenient because the guide provides a <a href="https://raw.githubusercontent.com/drduh/YubiKey-Guide/master/passphrase.html">handy template</a> which can be printed out for making paper backups of your passphrase.</p>
<p>
  <figure>
    <img src="003.png" alt="A screenshot of a very simple webpage with a matrix for entering a date, a key ID, a serial number, an admin pin, a user pin, and a 30 digit passphrase">
    <figcaption style="text-align: center;">I have printed multiple copies of this backup and stored them in secure locations</figcaption>
  </figure>



</p>
<p>This makes it super easy to back up your certify key.
As the guide mentions, it&rsquo;s okay to have this certify key be complex and not something you can necessarily remember since this will be pretty much only be used for managing subkeys.</p>
<p>Once I go through the somewhat tedious process of generating my Diceware passphrase and backing up its numerical representation, I can define the passphrase variable:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-console" data-lang="console"><span style="display:flex;"><span>CERTIFY_PASS=&#34;MY-SECRET-DICEWARE-CERTIFY-PASSPHRASE&#34;
</span></span></code></pre></div><p>It&rsquo;s also important to note, I added additional characters to the passphrase that I did NOT write down.
I am certain that I will remember these characters, adding an additional layer of security on top of the paper backups.
Before continuing, I also tested a &ldquo;restore&rdquo; by converting my numerical backup back to a passphrase and confirming it matched the one I had generated.</p>
<h2 id="part-7hr33-key-generation">Part 7hr33: Key Generation</h2>
<p>As Allah Gold said in Backstroke of the West, &ldquo;<a href="https://www.youtube.com/watch?v=yaGI4oItZS0">game time started</a>&rdquo;.
I have all of my variables defined and now I can start generating my keys.
No matter how many encryption keys I generate, it&rsquo;s always fun.
It makes me think of my childhood days of pretending to be a spy.
Maybe Spy Gear would still be around if they sold GPG to kids.</p>
<p>The guide once again provides all the commands needed for this step.
Conveniently, it also provides a command to display your certify key&rsquo;s ID and fingerprint, right-aligned so that you can confirm they match:</p>
<p>
  <figure>
    <img src="004.png" alt="A screenshot of shell commands defining KEYD and KEYFP variables, which represent the ID and fingerprint of our public key. The value of each variable is printed right-aligned, demonstrating that the Key ID is equal to the last 16 characters of the Key FP">
    <figcaption style="text-align: center;">Code snippets like this are one of the best parts of the drduh guide</figcaption>
  </figure>



</p>
<p>Once we have generated the certify key and set $KEYID and $KEYFP, we can generate this subkeys.
This process does actually take a few seconds on my poor old ThinkPad, but in a few seconds, we have all of our keys and can view them with <code>gpg -K</code>.
After verifying the keys, we will export backups of all keys, including the master/certify key, the subkeys, and the public key.
This brings us to a side quest:</p>
<h3 id="sidequest-setting-up-encrypted-storage">Sidequest: Setting Up Encrypted Storage</h3>
<p>In the beginning of this post, I mentioned that I no longer had access to the encrypted drive that held my old private keys.
For a while, I was under the impression that I had simply forgotten the passphrase to this drive, but I recently found out that I had actually let the drive&rsquo;s internal battery die.
I believe this effectively performed a cryptographic erase on the drive and &ldquo;secured&rdquo; my data so well that even I could no longer access it.</p>
<p>The drive in question was an Apricorn Aegis Secure Key 3 NXC.
It seems to be just about the best hardware encryption you can get on a flash drive and was somewhat reasonably priced (I paid under $100 for my 16GB model).
As I am finding out, though, this is certainly designed more government/enterprise use than solo tech nerd use.
It is not very user-friendly to configure.
I made sure that I remember my admin AND user PINs this time and created a recurring calendar event to remind myself to charge the Secure Key every month.</p>
<p>After setting new PINs, I quickly created a quick GPT partition on the drive and created an ext4 filesystem on it.
Last time I went through this process, I created an encrypted LUKS partition to store the private keys on but looking back, this is just another passphrase to lose.
The drive is already hardware encrypted so I don&rsquo;t see the point in adding software encryption as well.</p>
<p>With that out of the way, we can get back to following the guide.</p>
<h3 id="key-backups">Key Backups</h3>
<p>I&rsquo;ve already made a paper backup of our certify passphrase (and I&rsquo;m going to do my best to memorize it), but I also have to back up the private keys, otherwise that passphrase does me no good once I inevitably lose my YubiKeys or they break again.
As the guide suggests, I exported all of the keys and move the entire $GNUPGHOME folder to the encrypted flash drive.
If you&rsquo;re looking to do something similar, I would suggest doing as the guide suggests and just creating a LUKS partition on a standard flash drive.
A non-FIPS 140-2 Level 3 flash drive will be MUCH cheaper.
If I didn&rsquo;t already have the Secure Key, I would be making multiple backups on commodity flash drives (and likely still will!).</p>
<p>I also created a <a href="https://www.jabberwocky.com/software/paperkey/">paperkey</a> backup of my keyring and exported it to my encrypted flash drive.
I am holding off on printing this until I can figure out a secure way to do so, but I wanted to go ahead and generate the paperkey file while I had my environment configured.
There&rsquo;s instructions for this pending merge into the guide, but I went ahead and ran this command to export the entire keyring:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-console" data-lang="console"><span style="display:flex;"><span>gpg --batch --pinentry-mode=loopback --passphrase &#34;$CERTIFY_PASS&#34; \
</span></span><span style="display:flex;"><span>    --export-secret-keys &#34;$KEYID&#34; | gpg --dearmor | 
</span></span><span style="display:flex;"><span>    paperkey &gt; /mnt/usb/gnupg/$KEYID.paperkey.txt
</span></span></code></pre></div><p>This process isn&rsquo;t perfect yet, though, and there a few caveats that you should be aware of if you&rsquo;re intending to use paperkey.
I would check out <a href="https://github.com/drduh/YubiKey-Guide/pull/433">this PR</a> for the most up-to date info as this discussion is still going on as I write this post, but the main issue is that the paperkey file is quite large (over 20KB!).
This can be problematic if you are intending on exporting the keys to a QR code, which have a maximum data size of 3KB.
There are a few workarounds listed in the PR, but I don&rsquo;t love any of them.
Since I don&rsquo;t have a &ldquo;secure&rdquo; way to print yet anyway, I&rsquo;m not going to worry about this yet.
<strong>If you can think of a good way to print out sensitive data while ensuring it is not cached on the printer or ever sent over the network, please do let me know!</strong></p>
<p>After creating my paperkey backup, I removed my encrypted drive and exported my public key onto a separate USB drive so that I could copy it over to a networked computer:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-console" data-lang="console"><span style="display:flex;"><span>sudo mount /dev/sdc1 /mnt/usb
</span></span><span style="display:flex;"><span>sudo cp $GNUPGHOME/$KEYID-$(date +%F).asc /mnt/usb
</span></span><span style="display:flex;"><span>sudo umount /mnt/usb
</span></span></code></pre></div><h2 id="part-f0ur-yubikey-setup">Part f0ur: YubiKey Setup</h2>
<p>It&rsquo;s finally time to copy the digital keys over to the physical keys.
Once again, following the guide, I set an $ADMIN_PIN and a $USER_PIN value and copied them over to both of my YubiKeys.
I set the identity to my previously defined $IDENTITY.</p>
<p>Once I started copying keys over, though, I ran into issues.
I accidentally knocked my live USB drive out of the laptop, so I had to reboot the system.
This acted as a sort of impromptu disaster recovery test as I had to recover my certify passphrase and YubiKey PINs.</p>
<p>Once I got that sorted, the all-in-one gpg command to copy the signature key provided by the guide did not work for me.
Whenever I ran it, I got <code>GPG: KEYTOCARD FAILED: Invalid time</code>.
I tried to make sure the time in my live environment was set correctly, but that didn&rsquo;t fix the issue.
After a few other failed attempts, I tried to manually run <code>gpg --edit-key</code> and copy the key over.
This worked with no issue, though I think I had to enter the YubiKey admin PIN twice (I was not able to recreate the issue so I can&rsquo;t be certain).
The other subkeys copied over without issue.</p>
<p>Once this was done, I verified all of the keys copied over correctly.
Since the keytocard command deletes the private keys off of your local machine, I restored my backed up $GPNUPGHOME folder and repeated the copy process for the second YubiKey.
I also couldn&rsquo;t use the all-in-one copy commands for this YubiKey since it actually still had old keys saved on it, so I once again manually ran keytocard.</p>
<p>Once this was done, I could connect the YubiKeys to my desktop and confirm that they showed the keys were being read properly, which was a very exciting milestone!</p>
<p>
  <figure>
    <img src="005.png" alt="&ldquo;A screenshot of the output of the gpg &ndash;card-status command on my desktop&rdquo;">
    <figcaption style="text-align: center;">We aren&#39;t quite done, but seeing my keys show up on a /real/ computer felt great</figcaption>
  </figure>



</p>
<p>Now, I just had to import the public key I exported at the end of part three and connect my YubiKey.
I was able to verify that I could access the subkeys, but the certify key is offline (as is intended).
I opened Kleopatra and testing signing and verifying some messages to confirm that everything is working.
Now we can finally put these keys to use.</p>
<h2 id="part-f1v3-using-the-keys">Part f1v3: Using the Keys</h2>
<p>Now that we have the keys, it&rsquo;s time to put them to use.
The drduh guide goes over using the YubiKeys for SSH authentication and signing git commits, but I already have that set up on most of my systems, so I&rsquo;ll skip that for now.
The main things I am interested in securing right now are communications.</p>
<p>I have my pgp keys stored in a number of places, all of which need to be updated.
Luckily, in most of these places, I just link to <a href="https://klercke.com/pgp-key.txt">https://klercke.com/pgp-key.txt</a>, so I just need to update it there.
Since my website lives in a <a href="https://github.com/klercke/klercke.com">GitHub repo</a>, I just have to update the pgp-key.txt file in that repo.
I also updated the <a href="https://klercke.com/.well-known/security.txt">security.txt</a> file and signed it with my new key.</p>
<p>
  <figure>
    <img src="006.png" alt="&ldquo;A screenshot of klercke.com. The website appears to be a unix-style terminal with the command &ldquo;cat security.txt&rdquo; typed out. The contents of this file are displayed in the terminal.">
    <figcaption style="text-align: center;">Bigger updates to this site coming soon</figcaption>
  </figure>



</p>
<p>Now that I have my key uploaded to my website, I added the download URL to both of my YubiKeys (along with some other metadata):</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-console" data-lang="console"><span style="display:flex;"><span>gpg --card-edit
</span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span>gpg/card&gt; admin
</span></span><span style="display:flex;"><span>Admin commands are allowed
</span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span>gpg/card&gt; name
</span></span><span style="display:flex;"><span>Cardholder&#39;s surname: Klercke
</span></span><span style="display:flex;"><span>Cardholder&#39;s given name: Konnor
</span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span>gpg/card&gt; url
</span></span><span style="display:flex;"><span>URL to retrieve public key: https://klercke.com/pgp-key.txt
</span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span>gpg/card&gt; lang
</span></span><span style="display:flex;"><span>Language preferences: en
</span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">
</span></span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010"></span>gpg/card&gt; quit
</span></span></code></pre></div><p>Now, when I connect the YubiKey to a computer, I can quickly download the public key from that URL (not that the URL is that hard for me to remember).</p>
<h3 id="future-plans">Future plans</h3>
<p>That just about wraps up my key renewal process, but I will be using these keys in future projects.
I have a post coming up about enabling more private access to my website, which will feature another use of my GPG keys.
Of course, my public key and email address are both available, so if you would like to send me an encrypted message, feel free!</p>
<p>Once I follow this process again to generate keys for my d0c_z3r0d4y identity, I will enable GPG signing for all of my outgoing emails in Thunderbird.</p>
]]></content>
        </item>
        
        <item>
            <title>Blog as Code: Building an Open, Self-Hosted Blog</title>
            <link>https://blog.klercke.com/posts/2024-06-02-blog-setup/</link>
            <pubDate>Sun, 02 Jun 2024 19:51:26 -0400</pubDate>
            
            <guid>https://blog.klercke.com/posts/2024-06-02-blog-setup/</guid>
            <description>&lt;p&gt;
  &lt;figure&gt;
    &lt;img src=&#34;001.png&#34; alt=&#34;A screenshot of the blog.klercke.com homepage&#34;&gt;
    &lt;figcaption style=&#34;text-align: center;&#34;&gt;This should look familiar&lt;/figcaption&gt;
  &lt;/figure&gt;



&lt;/p&gt;
&lt;h2 id=&#34;part-z3r0-background&#34;&gt;Part z3r0: Background&lt;/h2&gt;
&lt;p&gt;I am terrible at writing things down.
I couldn&amp;rsquo;t tell you the number of times I started working on project only to shelve it for a few months and be totally lost when I get back to it.
As my homelab has grown in complexity, peaking at over 30 virtual servers, this has become a huge hurdle for managing my network.
While I have been paring down the number of servers I&amp;rsquo;m running lately, I have rediscovered a few different methods I&amp;rsquo;ve used to try to document my projects in the past.&lt;/p&gt;</description>
            <content type="html"><![CDATA[<p>
  <figure>
    <img src="001.png" alt="A screenshot of the blog.klercke.com homepage">
    <figcaption style="text-align: center;">This should look familiar</figcaption>
  </figure>



</p>
<h2 id="part-z3r0-background">Part z3r0: Background</h2>
<p>I am terrible at writing things down.
I couldn&rsquo;t tell you the number of times I started working on project only to shelve it for a few months and be totally lost when I get back to it.
As my homelab has grown in complexity, peaking at over 30 virtual servers, this has become a huge hurdle for managing my network.
While I have been paring down the number of servers I&rsquo;m running lately, I have rediscovered a few different methods I&rsquo;ve used to try to document my projects in the past.</p>
<h3 id="my-past-attempts-at-documentation">My Past Attempts at Documentation</h3>
<p>
  <figure>
    <img src="002.png" alt="A screenshot of an Obsidian canvas with notes representing individual server components and connections indicating which components depend on each other">
    <figcaption style="text-align: center;">An example of my Obsidian notes on a server that does not even exist yet</figcaption>
  </figure>



</p>
<p>I had an old <a href="https://www.mediawiki.org/wiki/MediaWiki">MediaWiki</a> server running with a single (now decommissioned) server documented in it (ironically, the MediaWiki server itself was <em>not</em> documented).
My &ldquo;homelab&rdquo; <a href="https://obsidian.md/">Obsidian</a> vault has excruciatingly detailed plans for a server that I have not yet built, but exactly 0 documentation of servers that actually existed at any point.
I&rsquo;ve also looked at <a href="https://netboxlabs.com/">NetBox</a> and <a href="https://hudu.com/">Hudu</a>.
While I definitely want to check out NetBox in the future, it isn&rsquo;t the right tool to solve this problem.
I&rsquo;ve used very similar software to Hudu at work, but I usually find myself ignoring the information stored within it and going straight to the source for answers.
This prompted me to think about <em>why</em> I could never stick with documenting my network and projects.</p>
<p>While trying to answer this question, I noticed that is is not exclusive to me.
At work, I sometimes find myself complaining about lacking documentation for servers built by others, but often forget to document servers that I build.
More often than not, before I check our documentation for information on a server, I will just remote into the server itself and try to gather the information myself.
After analyzing my thoughts each time I find myself doing this, I have identified a few reasons behind it:</p>
<h3 id="why-documentation-fails">Why Documentation Fails</h3>
<ol>
<li>
<p><strong>The documentation is untrustworthy.</strong></p>
<p>I&rsquo;m sure that my coworkers are (mostly) entering correct information when they create new documentation, but much of this information can change over the lifetime of a server.
Most of our customers do not have strict IT policies, so the IP of a server can change (hopefully on purpose and not because it had a DHCP address), additional roles/applications can be installed, the server can be physically moved or migrated to a new host, etc.
This raises a few questions for me; namely, &ldquo;is there a better way to document this?&rdquo; and &ldquo;should we even be documenting this?&rdquo;.</p>
<p>To answer the first question: almost certainly.
Information such as hostnames, IP addresses, OS versions, and even installed packages and roles can be automatically collected fairly easily.
Any credentials will be stored in a password manager or secret server of some sort.
In a strong <a href="https://blog.klercke.com/tags/iac">Infrastructure as Code</a> environment, much of this information is &ldquo;self-documenting&rdquo; and can easily be found in the code written to create the infrastructure.
Barring that, it takes under a minute to manually check this information if you have access to the server (though it is helpful to be able to access it if the server is offline).
The second questions leads me into my second reason why I believe these documentation systems have not worked for me.</p>
</li>
<li>
<p><strong>We are documenting the wrong information.</strong></p>
<p>To design a better system for documentation, it&rsquo;s important to think of the reason the documentation system exists needs to exist in the first place.
As already mentioned, documenting IP addresses and installed applications isn&rsquo;t the problem I&rsquo;m trying to solve.
So what is?
The thing I find myself asking most often when I&rsquo;m searching through documentation is &ldquo;what the hell was the guy who deployed this thinking?!&rdquo;
Even with servers/services I deployed myself, the problem I struggle with the most is getting into the mindset that I was in when I deployed it.
Remembering why I made certain decisions helps me remember other decisions I made.</p>
</li>
<li>
<p><strong>The documentation doesn&rsquo;t exist.</strong></p>
<p>The final point in this vicious cycle of un-documentation is that oftentimes, documentation never exists in the first place.
I believe this is partially due to simple forgetfulness.
At work, writing documentation is part of our project plans but can often get overlooked due to the many other &ldquo;more important&rdquo; tasks that need to be completed.
In my home network, writing documentation is hardly on the top of my priority list.
I want to deploy this cool new service and start playing with it immediately (or go do something entirely different).
Rarely does the thought of documentation ever cross my mind.
I also believe my previous points contribute to this point, and this point contributes to the others.
We don&rsquo;t think to update the documentation because we don&rsquo;t use the documentation and we don&rsquo;t use the documentation because we don&rsquo;t think to update it.</p>
</li>
</ol>
<h3 id="why-a-blog">Why a Blog</h3>
<p>So what does this have to do with a blog?
For my (personal) purposes, a blog fixes these issues.
My blog isn&rsquo;t going to document things like private IPs of servers, but rather my methodology for deploying services and my thought process behind each project.
I&rsquo;m also more motivated to write documentation in the form of a blog post than I am a wiki entry since blog posts can be &ldquo;enjoyed&rdquo; by others.
I&rsquo;m a firm believer that <strong>information should be free</strong>, so I want to share my thoughts with anyone who cares to read them.</p>
<p>Side note: Since I mentioned work quite a bit in my reasoning above, I should clarify that I do not think companies should abandon their current documentation in favor of blogs.
Proper documentation is always going to be much faster to scan for information that a blog post that has a story to tell.
I have heard of companies that have internal developer blogs <em>in addition</em> to documentation platforms and my understanding is that they are usually received quite well.
I think this is one way that corporate environments differ from homelabs.</p>
<h2 id="part-0n3-infrastructure">Part 0n3: Infrastructure</h2>
<p>With that little manifesto out of the way, let&rsquo;s get into the technical aspects of my blog, starting with the infrastructure that it runs on.</p>
<h3 id="the-server">The Server</h3>
<p>
  <figure>
    <img src="003.png" alt="A screenshot of the Linode/Akami cloud manager showing a Linode named &ldquo;asgard&rdquo;">
    <figcaption style="text-align: center;">My gateway drug into the worlds of Linux and cloud computing</figcaption>
  </figure>



</p>
<p>Despite having a collection of perfectly good servers running at home, I decided to deploy my blog to one of my <a href="https://www.linode.com/lp/refer/?r=fca3e57ade14bb3371ad530f882e3283e18bd68b">Linodes</a>.
Please note that this is link is my personal referral link.
Signing up for Linode with this link will give you a $100 credit that is good for 60 days and will give me a $25 credit.
More information can be found <a href="https://www.linode.com/referral-program/">here</a>.</p>
<p>Since a statically rendered blog is a relatively lightweight application, I don&rsquo;t need the horsepower of my on-prem servers to run it.
Hosting in a VPS also allows me to have high uptime for my blog without having to worry about making my site unavailable during a power outage or server maintenance.
Of course, on-prem servers do also carry security implications, so not having my blog potentially expose any part of my home network to attack is a plus as well.
Currently, the blog is running on my long-time Linode named &ldquo;asgard&rdquo;, which is running Arch Linux (btw) and hosts a few other web services that my friends and I use.</p>
<p>As a quick sidebar on asgard, it has gone through a few iterations since I first purchased it back in 2016.
I originally set it up based on the <a href="https://www.youtube.com/watch?v=SlEQ6GGIyBc">Level1Linux &ldquo;Your Linux Server&rdquo; Series</a>.
Watching this video 8 years ago is probably one of the most important things to happen to me as I don&rsquo;t think I would be in the IT field today without it.
The server has been wiped a few times since then, but it still serves as somewhat of a time capsule for me.
A lot of things on that server are not configured the way I would do them today.
While I have swapped out some packages and hardened the server as time has gone on, I do think it&rsquo;s about time to rebuild asgard once again.
I have some exciting ideas for this next iteration, which will almost certainly be the subject of a future blog post.</p>
<p>To quickly touch on DNS, I use <a href="https://njal.la/">Njalla</a> as my DNS registrar for pretty much everything.
Obviously, I am not using it to remain &ldquo;anonymous&rdquo;, but I appreciate their commitments to privacy and don&rsquo;t mind paying a little extra to support them.
Also, I highly recommend checking out <a href="https://njal.la/blog/">their blog</a>.</p>
<h3 id="the-software">The Software</h3>
<h4 id="github">GitHub</h4>
<p>The source files for the blog are all hosted on <a href="https://github.com/klercke/blog.klercke.com">GitHub</a>.
When I push a commit, GitHub Actions renders the Markdown files that I wrote into HTML and pushes them to asgard (more on that later), where they are visible to anyone on the internet.
Each blog post has a comment section provided by <a href="https://utteranc.es/">Utterances</a>.
Each new post gets a GitHub issue created automatically and comments on those issues are shown as comments on the post (more on this later as well).</p>
<h4 id="hugo">Hugo</h4>
<p>The blog is built using <a href="https://gohugo.io/">Hugo</a>.
I tried a few different static site generators, but I was extremely picky.
I knew I wanted my source files to be written in Markdown, I wanted to have strong control of the site&rsquo;s appearance, and I wanted at least some control over the organization my source files.
I was also 100% set on using a site generator that would allow me to check the site into Git in a way that makes it easy to browse without rendering.
Of course, it should go without saying, but I was only going to use a site generator if it was open source.
This led me to try two static site generators: Jekyll, which I had used once for a past project, and Hugo.</p>
<p>Ultimately, I settled on Hugo due to it being slightly easier to use (in my opinion) and incredibly fast.
At the time of writing, the entire site builds in 50-100ms on my mid-tier desktop.
The entire deployment process from my commit hitting GitHub to the content being visible on the site takes about 5 seconds.</p>
<p>For my Hugo theme, I&rsquo;m using <a href="https://github.com/rhazdon/hugo-theme-hello-friend-ng">hello-friend-ng</a>.
I have made one <a href="https://github.com/rhazdon/hugo-theme-hello-friend-ng/compare/master...klercke:hugo-theme-hello-friend-ng:master">extremely minor tweak</a> in order to get the RSS icon to appear on my homepage, but I plan on customizing the theme more in the future.
I tried at least a dozen themes and hello-friend-ng was by far my favorite.
I initially planned to use <a href="https://github.com/526avijitgupta/gokarna">Gokarna</a>, but found that I slightly preferred hello-friend-ng after playing around with the plugins and features of each.</p>
<h4 id="caddy">Caddy</h4>
<p>Once the blog is rendered, it is served to users by <a href="https://caddyserver.com/">Caddy</a>.
I have used Apache as a web server and Nginx (which is totally pronounced &ldquo;EN-jinx&rdquo;, not &ldquo;EN-gin-ex&rdquo;, by the way) as a reverse proxy for years, but swapped to Caddy this year.
Caddy has made everything so much simpler to host.
The entire configuration for this site is only a few lines:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-JSON" data-lang="JSON"><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">blog.klercke.com</span> {
</span></span><span style="display:flex;"><span>    <span style="color:#960050;background-color:#1e0010">root</span> <span style="color:#960050;background-color:#1e0010">*</span> <span style="color:#960050;background-color:#1e0010">/srv/http/blog.klercke.com/public</span>
</span></span><span style="display:flex;"><span>    <span style="color:#960050;background-color:#1e0010">file_server</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>    <span style="color:#960050;background-color:#1e0010">@plausible</span> <span style="color:#960050;background-color:#1e0010">path</span> <span style="color:#960050;background-color:#1e0010">/js/script.js</span> <span style="color:#960050;background-color:#1e0010">/api/event</span>
</span></span><span style="display:flex;"><span>    <span style="color:#960050;background-color:#1e0010">handle</span> <span style="color:#960050;background-color:#1e0010">@plausible</span> <span style="color:#960050;background-color:#1e0010">{</span>
</span></span><span style="display:flex;"><span>        <span style="color:#960050;background-color:#1e0010">rewrite</span> <span style="color:#960050;background-color:#1e0010">/js/script.js</span> <span style="color:#960050;background-color:#1e0010">/js/script.js</span>
</span></span><span style="display:flex;"><span>        <span style="color:#960050;background-color:#1e0010">reverse_proxy</span> <span style="color:#960050;background-color:#1e0010">https:</span><span style="color:#75715e">//plausible.io {
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span>            <span style="color:#960050;background-color:#1e0010">header_up</span> <span style="color:#960050;background-color:#1e0010">Host</span> <span style="color:#960050;background-color:#1e0010">{http.reverse_proxy.upstream.hostport</span>}
</span></span><span style="display:flex;"><span>        <span style="color:#960050;background-color:#1e0010">}</span>
</span></span><span style="display:flex;"><span>    <span style="color:#960050;background-color:#1e0010">}</span>	
</span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">}</span>
</span></span></code></pre></div><p>The majority of this block is actually for proxying Plausible, my analytics tool (another &ldquo;more on this later&rdquo; item), through my own domain.
If I didn&rsquo;t want to take this step, the configuration would extremely simple:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-JSON" data-lang="JSON"><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">blog.klercke.com</span> {
</span></span><span style="display:flex;"><span>    <span style="color:#960050;background-color:#1e0010">root</span> <span style="color:#960050;background-color:#1e0010">*</span> <span style="color:#960050;background-color:#1e0010">/srv/http/blog.klercke.com/public</span>
</span></span><span style="display:flex;"><span>    <span style="color:#960050;background-color:#1e0010">file_server</span>
</span></span><span style="display:flex;"><span>}
</span></span></code></pre></div><p>Caddy handles redirecting HTTP traffic to HTTPS automatically and even automatically generates Let&rsquo;s Encrypt TLS certificates, which is a huge time saver.
Caddy is an incredible piece of software that I cannot recommend enough.</p>
<h2 id="part-7w0-features-and-plugins">Part 7w0: Features and Plugins</h2>
<h3 id="commit-links">Commit Links</h3>
<p>
  <figure>
    <img src="004.png" alt="A screenshot of the footer of a post. The footer shows the time the post was created, the time of the most recent update to that post, and the commit ID for the most recent commit that affected that post. The commit ID is underlined, implying that it is a hyperlink.">
    <figcaption style="text-align: center;">The footer from my test post</figcaption>
  </figure>



</p>
<p>As part of my &ldquo;<a href="https://www.process.st/radical-transparency/">radical transparency</a>&rdquo; mission with my blog, I want it to be obvious to users that the site is a Git repository that can be cloned and modified if desired.
To accomplish this, I&rsquo;m using hello-friend-ng&rsquo;s built-in commit linking feature.
In the [params] section of my hugo.toml, I specified the link to my GitHub repo and Hugo takes care of the rest.
As soon as a page is committed, a link to the commit that modified it will be added to the bottom.
Since the blog is deployed to the server by GitHub actions, each page will necessarily have a commit associated with it.</p>
<h3 id="comments">Comments</h3>
<p>
  <figure>
    <img src="005.png" alt="A screenshot of an example post titled &ldquo;Test Post&rdquo; with a comment section visually resembling a GitHub issue. There is one comment by klercke, the owner of the site, reading &ldquo;test comment on the test post&rdquo;">
    <figcaption style="text-align: center;">An insightful comment on an insightful post</figcaption>
  </figure>



</p>
<p>One of the benefits of my whole blog being stored in a GitHub repo is that we can use GitHub issues as a commenting system.
Since one of my goals for the blog was for it to be fully browsable without visiting the site itself, all of the site content can be viewed in the GitHub repo, so it only makes sense for the comments to be on GitHub as well.
I wish that the comments were more &ldquo;portable&rdquo; so that they were stored in the repo itself and could be read offline, but I can live without this due to the simplicity that GitHub issues and Utterances offer.
Hello-friend-ng has native support for Utterances, so I just had to add the Utterances bot to my GitHub repo and add a few lines to the [params] section of my hugo.toml:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-TOML" data-lang="TOML"><span style="display:flex;"><span>  <span style="color:#75715e"># Utteranc.es (comments)</span>
</span></span><span style="display:flex;"><span>  [<span style="color:#a6e22e">params</span>.<span style="color:#a6e22e">utterances</span>]
</span></span><span style="display:flex;"><span>    <span style="color:#75715e"># Comments repo</span>
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">repository</span> = <span style="color:#e6db74">&#34;klercke/blog.klercke.com&#34;</span>
</span></span><span style="display:flex;"><span>    
</span></span><span style="display:flex;"><span>    <span style="color:#75715e"># Comments issue label</span>
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">label</span>      = <span style="color:#e6db74">&#34;Comment&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#   Blog Post &lt;-&gt; Issue mapping. This parameter is optional. Possible values are:</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - pathname</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - url</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - title</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - og:title</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - issue number</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - specific term</span>
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">issueTerm</span>  = <span style="color:#e6db74">&#34;og:title&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#   Theme used: possible values are:</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - github-light</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - github-dark</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - preferred-color-scheme</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - github-dark-orange</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - icy-dark</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - dark-blue</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - photon-dark</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - boxy-light</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#      - gruvbox-dark</span>
</span></span><span style="display:flex;"><span>    <span style="color:#75715e">#</span>
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">theme</span>      = <span style="color:#e6db74">&#34;preferred-color-scheme&#34;</span>
</span></span></code></pre></div><p>Users can comment directly on the post by signing in with GitHub or they can comment directly on the issue on github.com.</p>
<h3 id="analytics">Analytics</h3>
<p>
  <figure>
    <img src="006.png" alt="A screenshot of the Plausible Analytics dashboard for this blog">
    <figcaption style="text-align: center;">My Plausible dashboard after some brief testing. My friend in California shows up as two unique visitors despite visiting the site twice from the same device a little over 24 hours apart. I have excluded my IP from Plausible&#39;s platform after visiting once so I do not skew the numbers</figcaption>
  </figure>



</p>
<p>Of all the decisions I made regarding this blog, this was by far the most difficult.
I hate tracking and spyware as much as the next guy (and probably far more), so I was initially very against any sort of analytics on my site.
I don&rsquo;t want to contribute to the surveillance economy, but I do want the basic information that will allow me to track how well my blog is performing and ideally write better content.
Hello-friend-ng has support for <a href="https://plausible.io/">Plausible Analytics</a> built in, so I tried it out when I started building this blog in March.
After my trial expired, I decided that I felt &ldquo;dirty&rdquo; using any sort of analytics platform, and removed Plausible from my site.
After more deliberation over the past three months, though, I decided that the data I get from an analytics platform, even a basic one, will be necessary for achieving my long-term goals with this blog and keeping myself motivated to keep posting.
Since the theme has Plausible support built in, I decided to look deeper into Plausible&rsquo;s offering.
It was trivially easy to add Plausible to my site once my account was configured:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-TOML" data-lang="TOML"><span style="display:flex;"><span>  <span style="color:#75715e"># Plausible.io analytics</span>
</span></span><span style="display:flex;"><span>  <span style="color:#a6e22e">plausibleDataDomain</span> = <span style="color:#e6db74">&#39;blog.klercke.com&#39;</span>
</span></span><span style="display:flex;"><span>  <span style="color:#a6e22e">plausibleScriptSource</span> = <span style="color:#e6db74">&#39;https://blog.klercke.com/js/script.js&#39;</span>
</span></span></code></pre></div><p>After demoing Plausible again, I have decided to add it back to my site for the time being.
It&rsquo;s open source, lightweight (the script that gets loaded when you visit the blog is under 1KB), and self-hostable.
They claim to have no investors and not sell any user data.
Their <a href="https://plausible.io/data-policy">data policy</a> specifies exactly what they collect, which is not much.
I can&rsquo;t even view the IP address of users who visit my site.
I am currently using their SaaS offering, but I do have plans to move to their self-hosted &ldquo;community edition&rdquo; once I move the blog to its own Linode.</p>
<p>Many adblockers, including uBlock Origin, which I use, do block Plausible by default, so I have proxied Plausible&rsquo;s analytics script through my own server as seen in my Caddy configuration above, hiding its true URL from most adblockers.
<strong>If you wish to block or opt-out of analytics on my site, please add &ldquo;<a href="https://blog.klercke.com/js/script.js%22">https://blog.klercke.com/js/script.js"</a> to your adblocker&rsquo;s blocklist.</strong></p>
<p>For now, in the interest of transparency, I have made my <a href="https://plausible.io/blog.klercke.com/">Plausible dashboard</a> publicly available.
Once I move to Plausible CE, I will likely have the dashboard embedded on this site.
Currently, uBlock Origin blocks the embed from Plausible&rsquo;s site (understandably).</p>
<p>I am open to feedback regarding analytics.
If you have any opinions you would like to share, please do reach out (perhaps using the comment section on this page :)).</p>
<h2 id="part-7hr33-workflows">Part 7hr33: Workflows</h2>
<h3 id="writing">Writing</h3>
<p>
  <figure>
    <img src="007.png" alt="A screenshot of an i3 desktop on an ultrawide display. On the left side, the source file for this article is open in Neovim with a small terminal showing the output of the &ldquo;hugo serve -D&rdquo; command. On the right side, the Hugo-served development site is open in Firefox. There are three additional tabs open in Firefox: The GitHub repository for this blog, the live, production version of this blog, and the Plausible Analytics dashboard for this blog">
    <figcaption style="text-align: center;">My development environment (with my Polybar cropped out because it is really ugly right now)</figcaption>
  </figure>



</p>
<p>I am very particular about my workspace when I am writing (whether it be prose or code), so having my particular flavor of writing workflow was one of my end goals with my blogging setup.
As you can see in the screenshot above, I write my blog posts in Neovim on my Linux desktop (<a href="https://endeavouros.com/">EndeavourOS</a>, specifically).
My <a href="https://github.com/klercke/nvim">Neovim config</a> is set up to be multipurpose, but I do have a few customizations for writing Markdown files.
One of the most important customizations is the &ldquo;Date&rdquo; command I added.
Hugo will generate the timestamp for a file when it is created, but since I spend days or weeks (or months) writing posts, this timestamp is not accurate to the actual publication time.
When I am done with a post, I can clear out the &ldquo;date&rdquo; field in the frontmatter and run the Date command in Neovim, which will populate the current date.</p>
<p>The window on the bottom left is a terminal running the &ldquo;hugo serve -D&rdquo; command, which is an incredible feature of Hugo.
It starts a local web server and compiles the entire site (including drafts due to the -D flag), making it available at localhost:1313.
While running, hugo serve will also watch for changes to any files in the site and automatically re-compile them and refresh the page.
This means that whenever I save my source file in my Vim window (<em>Vimdow</em>, if you will), the changes are immediately reflected in the Firefox preview on the right half of my screen.
Since Hugo can compile a page in a few milliseconds, this preview updates basically as soon as I save the source file, making it easy to see what the post is going to look like.</p>
<p>On the right half of the screen, I have Firefox.
Since I have an ultrawide monitor, splitting it in half still gives me plenty of room for a comfortable size editor alongside a browser taking up half the screen.
Most of the time while I&rsquo;m writing, I have Firefox open to the preview version of the post I&rsquo;m working on.
I usually also have a few other tabs open: the GitHub repo for this blog so I can monitor the status of the GitHub Actions workflow that builds and deploys the site (I promise we&rsquo;re getting there), the production version of the site to make sure the new posts show up right, and Plausible because I keep checking the dashboard to see if anyone has visited my blog that still has no posts.
I also use Firefox for quick research while writing.
For example, quickly fact checking something or getting a link for a topic that might be lesser-known or need further clarification so that I can link it in the article.</p>
<p>Occasionally, I will also need to open a terminal to reference a file or SSH into a server.
In this case, I will usually go to another i3 workspace that has a terminal open or quickly open a terminal on the bottom right of the screen and close it when I&rsquo;m done.</p>
<h3 id="file-management-and-text-organization">File Management and Text Organization</h3>
<p>Each post lives in a folder named in the format &ldquo;YYYY-MM-DD-post-title&rdquo;.
The date is the post&rsquo;s publication date in <a href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO 8601</a> format (objectively the best format for computing) so that sorting the posts alphabetically will sort them by publication date.
Inside each post folder is a file called &ldquo;index.md&rdquo;, which is the actual text content of the post before it is rendered into HTML.</p>
<p>Each post&rsquo;s folder also includes all images used in that post.
The images are named numerically, starting with 001.png as the first image and incrementing as you continue further down the post.
I try to rename the images to be in the same order as they appear, but I may mislabel a few as I move content around in the post.</p>
<p>Within the source files themselves, I try to keep my formatting consistent for ease of reading.
I put a newline before and after each header, code block, or image and try to put descriptive alt text and a caption on each image.
If the image caption is already sufficiently descriptive, I may omit alt text as a screen reader will also read the caption.
Each sentence goes on its own line.
This is a holdover from my days of writing hundreds of lines of LaTeX every day, but comes in extremely handy when writing in (Neo)vim, since any operation on a line is an operation a sentence.
For example, &ldquo;dd&rdquo; normally cuts a line, but in my case, it will cut an entire sentence, which makes re-arranging content lightning-fast.
Unless I need to use Firefox for quick research, I can write and publish an entire article without ever touching my mouse.</p>
<p>Since each post is wholly contained in a post folder and each post folder contains exactly one post, I can commit individual posts with &ldquo;git add ./content/posts/[post folder]&rdquo; and avoid committing any unfinished posts to GitHub (though even if I did, unfinished posts are marked as drafts so they still wouldn&rsquo;t show up on the production website).
If you&rsquo;d like to check any of this out, please do visit the blog&rsquo;s repo on GitHub and poke around in the file structure.</p>
<h3 id="deployment">Deployment</h3>
<p><strong>This is one of my favorite parts of my blogging setup.</strong>
Since the entire blog is stored in a Git repo and can be built with a single command, it is easy to automatically publish articles without ever having to touch the server that is hosting the blog.</p>
<p>When I finish an article, I just have to unmark it as a draft by removing &ldquo;draft: true&rdquo; from the frontmatter, commit the article folder, and then push the commit to GitHub.
Once the commit hits GitHub, GitHub Actions takes over and clones the repo, builds the site, and then uses rsync to sync the new (or updated) files to the production server.
From my perspective, pushing to GitHub is pushing to blog.klercke.com.
I am somewhat familiar with Azure DevOps and GitLab, but I had never used GitHub Actions before, so my workflow is based on <a href="https://swharden.com/blog/2022-03-20-github-actions-hugo/">Scott W Harden&rsquo;s excellent article</a>.
I made some tweaks to his configuration in order to support all of the features of my site and to clear warnings about outdated Actions that were generated by checkoutv3, but the majority of the configuration is based on his.
At the time of writing, my workflow looks like this, but the live version can always be found <a href="https://github.com/klercke/blog.klercke.com/blob/main/.github/workflows/blog.yml">here</a>:</p>
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-YAML" data-lang="YAML"><span style="display:flex;"><span><span style="color:#75715e"># Based on https://swharden.com/blog/2022-03-20-github-actions-hugo/</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">name</span>: <span style="color:#ae81ff">Build &amp; Push to Site</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">on</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">workflow_dispatch</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">push</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">branches</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">main</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">jobs</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">deploy</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">name</span>: <span style="color:#ae81ff">Build and Deploy</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">runs-on</span>: <span style="color:#ae81ff">ubuntu-latest</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">steps</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#f92672">name</span>: <span style="color:#ae81ff">🛒 Checkout</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">uses</span>: <span style="color:#ae81ff">actions/checkout@v4</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">with</span>:
</span></span><span style="display:flex;"><span>          <span style="color:#f92672">submodules</span>: <span style="color:#e6db74">&#39;recursive&#39;</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#f92672">name</span>: <span style="color:#ae81ff">✨ Setup Hugo</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">env</span>:
</span></span><span style="display:flex;"><span>          <span style="color:#f92672">HUGO_VERSION</span>: <span style="color:#ae81ff">0.126.2</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">run</span>: |<span style="color:#e6db74">
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">          mkdir ~/hugo
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">          cd ~/hugo
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">          curl -L &#34;https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.tar.gz&#34; --output hugo.tar.gz
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">          tar -xvzf hugo.tar.gz
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">          sudo mv hugo /usr/local/bin </span>
</span></span><span style="display:flex;"><span>      - <span style="color:#f92672">name</span>: <span style="color:#ae81ff">🛠️ Build</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">run</span>: <span style="color:#ae81ff">hugo</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#f92672">name</span>: <span style="color:#ae81ff">🔐 Create Key File</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">run</span>: <span style="color:#ae81ff">install -m 600 -D /dev/null ~/.ssh/id_rsa</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#f92672">name</span>: <span style="color:#ae81ff">🔑 Populate Key</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">run</span>: <span style="color:#ae81ff">echo &#34;${{ secrets.PRIVATE_SSH_KEY }}&#34; &gt; ~/.ssh/id_rsa</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#f92672">name</span>: <span style="color:#ae81ff">🔐 Load Host Keys</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">run</span>: <span style="color:#ae81ff">echo &#34;${{ secrets.KNOWN_HOSTS }}&#34; &gt; ~/.ssh/known_hosts</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#f92672">name</span>: <span style="color:#ae81ff">🚀 Upload</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">run</span>: <span style="color:#ae81ff">rsync --archive --delete --stats -e &#39;ssh&#39; public/ ${{ secrets.REMOTE_DEST }}:/srv/http/blog.klercke.com/public</span>
</span></span></code></pre></div><h2 id="part-f0ur-conclusion">Part f0ur: Conclusion</h2>
<h3 id="reflection">Reflection</h3>
<p>I am beyond excited to publish this article as my first blog post this evening.
I&rsquo;ve been working on this blog on and off for the past three months and I have a number of posts that I am excited to publish in various states varying from &ldquo;an idea&rdquo; to &ldquo;almost ready to publish&rdquo;, but I wanted to get the site to a state that I am happy with before publishing and publicizing anything.</p>
<p>I&rsquo;ll be writing more about this soon, but the idea of infrastructure as code, is extremely interesting to me and is a bit of a fixation of mine right now.
Not to spoil any upcoming content, but IaC is going to be a big focus of at least one series that I have in the works.
I am extremely satisfied with how well IaC concepts were able to be applied to my blog.
Since all of the content of the blog is stored in a repository that anyone can clone, it would be extremely difficult for me to lose this content; it&rsquo;s all backed up on GitHub.
If I somehow lost my Linode and my desktop at the same time, I would be able to clone the Git repo on any machine and run a local copy of my blog or even share it out to the internet with a quick DNS change.</p>
<p>The editing workflow is also perfect for me, being quite satisfying.
I am usually pretty terrible at keeping with habits, especially time-intensive ones.
Since this blog post alone has taken me the better part of this weekend to write, it&rsquo;s important for me to enjoy the writing process to stay motivated.
Just as a nice pen and notebook keep me motivated to practice writing by hand, I am already looking forward to finishing and publishing my next post.</p>
<h3 id="feedback">Feedback</h3>
<p>One thing that was drilled into me as a scout is the phrase &ldquo;feedback is a gift&rdquo; (it truly is).
I welcome any (constructive) feedback, positive or negative on this blog.
Feel free to use to the Utterances comments below or reach out to me directly using any of the contact methods on <a href="https://blog.klercke.com/">my homepage</a>.
While this platform is primarily meant to be documentation for myself, almost like a journal, I do also want it to be entertaining and/or helpful for others.
My goal while writing this article was not to make a tutorial, but to explain my mindset and reasoning as I built the blog while maintaining important technical details.
I&rsquo;d really like to know if you think there&rsquo;s anything I missed or, more likely, details that I shouldn&rsquo;t have included.</p>
<p>More posts coming soon :)</p>
]]></content>
        </item>
        
    </channel>
</rss>
