In lieu of that, I’ve decided to take matters into my own hands and build a NAS.

Table of contents

• History (you can skip this one)
• Hardware
• System
• Security
  • ZFS encryption
  • Headscale
  • SSL
• Backups
• Apps
• Conclusion

History

I’ve been hosting my own music since 2024, and I moved my personal data to a hosted NextCloud on Hetzner shortly after. Cryptomator helped me end-to-end encrypt my files on the Hetzner servers, and while I would recommend this, the workflow is a bit convoluted—for example, on macOS it mounts a volume that is harder to access.

The biggest problem for me was photos—I was using iCloud photos, and even though something like Immich get’s really close to the functionality I’m interested in, it’s not automatically end-to-end encrypted.

Hardware

Let’s talk about constraints:

• No pre-built, closed-source solution (Synology, QNAP, etc.): If I do this, I’m going to do it the right way.
• Ideally SSD-only: Using HDDs is cheap (see next point), but they’re more prone to fail and wayyy slower.
• Enough power: Because I wanted to run apps like Immich or NextCloud, I needed a fast-enough processor and enough memory, at least 8 GB.
• Reasonably priced: My budget was around 700 €.

Things I considered:

• Old QNAP stations: Some of these come with SATA slots that also support SSD, but ultimately the processors of the ones I looked at were too weak.
• Framework/Intel NUC/whatever with an external NVMe/M.2 case for my storage SSDs: There aren’t a lot of external NVMe RAID cases out there that look trustworthy, plus it felt wrong to have them connected over USB; it’s probably a lot slower as well.

At this point, I felt like there was no good solution, until I found the Intel NUC NUC6i7KYK, a.k.a. Skull Canyon. It has:

• Intel Core i7 (6MB cache, up to 3.5 GHz)
• 16 GB memory (at least the one I got on eBay)
• 2 internal M.2 SSD slots

This sounded perfect, and I got it used for around 200 €, with an internal 500 GB SSD already built in, which I used to test the setup.

My plan is to then get 2× 4 TB SSDs and mirror them for maximum security. This is more than enough storage for our family for the next few years. Also have you looked at SSD prices lately? 100 €/TB is a good deal.

System

From my research, these were the three top options:

• TrueNAS Community Edition (Scale): Open-source NAS system based on ZFS, with support for many apps using Docker.
• Unraid: Closed source; supports ZFS; BTRFS and XFS; needs a license ($249 for Lifetime)
• Handrolled: Build everthing myself using Arch/NixOS w/ Docker

While Unraid looked promising, I did not want any closed-source software. I thought about hand-rolling, but since I wanted this setup to be as stable as possible and I have very little experience with ZFS, I eventually decided on TrueNAS Scale.

One annoyance with TrueNAS¹ was that the installation could not be on a drive used for data. After some research, I decided to install on an SSD in a SATA case connected via USB. Booting from an external drive is not great and should be avoided if possible, but this is a common setup for people building NAS systems using mini-computers.

One problem I encountered was that initramfs failed to find the boot pool on boot because the (external) SSD was not discovered when it tried. I solved this problem by running this on the TrueNAS shell:

midclt call system.advanced.update '{"kernel_extra_options": "rootdelay=20"}'

This pauses the boot process for 20s, giving the USB controller time to set up the SSD.

Security

Security is all about attack vectors. My setup is meant to protect against theft and automated attacks. There is room to tighten this up even more, but this is more than good enough for me.

ZFS encryption

TrueNAS supports ZFS-native encryption. You can choose to encrypt the root pool, which I did; the encryption key is stored on the system itself for auto-unlock. This is great, but it offers no protection against the whole system being stolen.

Because of this, I have a top-level dataset under tank called encrypted, which is encrypted with a password. This means the system boots, but no data (including app data) is accessible until I log in and decrypt the dataset.

For this reason, I’m also not using the built-in backup solution; I don’t want the encryption key and password to be accessible on boot. More about backups further down.

I disabled the text console without a password prompt to prevent someone with physical access to the running, decrypted system from extracting data.

Headscale

There’s no way I’m exposing this system to the public internet. This is far too dangerous, even if you know what you’re doing. I still want to be able to access all my data from on the go, so I set up Headscale, an open-source, self-hosted version of Tailscale and compatible with the Tailscale apps. With this, I can access my NAS from anywhere via a self-hosted VPN.

SSL

But what if a machine in the VPN or on my local Wi-Fi gets compromised? The attacker would be able to sniff all HTTP traffic, extract credentials, and access all my data. This is why we encrypt our HTTP traffic.

For the TrueNAS system, I forward HTTP to HTTPS and use the self-signed certificate that comes pre installed.

But most TrueNAS apps expose ports without SSL, which means we need a reverse proxy. While TrueNAS supports the option to expose ports for inter-container communication, each app gets its own Docker network, which means a reverse proxy can’t access other apps by default². To fix this, I use Dragonify (which I forked for security reasons). It connects all apps to a single network, so I can use Nginx Proxy Manager³ to serve apps with SSL on a subdomain.

I bought a domain solely for this setup and use deSEC with an account created specifically for this domain. This means when a token gets compromised, only that single domain is affected. But that token lives on the encrypted dataset, soo it’s unlikely.

Backups

Because I don’t want any encryption keys or access credentials on the system partition, I’m not using the native TrueNAS backup systems. After some research, I’ve landed on Backrest, a configuration interface for Restic.

Here’s what Filippo Valsorda has to say about Restic encryption:

“The design might not be perfect, but it’s good. Encryption is a first-class feature, the implementation looks sane and I guess the deduplication trade-off is worth it. So… I’m going to use restic for my personal backups.”

For storage, I’m using Hetzner Object Storage, mostly because it’s environmentally friendly and hosted in the EU.

Apps

We already talked about Tailscale, Dragonify, Nginx Proxy Manager, and Backrest.

Here are the apps I’m using

• Immich for photos
• NextCloud for documents
• Syncthing for more advanced sync needs⁴
• Jellyfin for music
• Miniflux for RSS feeds

Conclusion

So that’s my setup. It works really well, and I’m happy. I’ll try to edit this post in six months to give an update.

Am I missing something? Let me know: hey@arne.me

Thanks to Eric & Jan for proof-reading this post and listening to my ramblings!

When worthiness is a function of productivity, we lose the ability to pump the brakes. The idea of doing something that doesn’t add to the bottom line provokes stress and anxiety. It feels completely contrary to what we believe we want to achieve in life—we convince ourselves that downtime, like playing with our kids, hanging out with our partners, napping, tooling around in the garage, or going for a run is a waste of precious time. Why sleep when you can work?

Although I’m not a workaholic, I do see myself in some of these points.
I need to work on that.

“Like fingers pointing to the moon, other diverse disciplines from anthropology to education, behavioral economics to family counseling, similarly suggest that the skillful management of attention is the sine qua non of the good life and the key to improving virtually every aspect of your experience.” — Winifred Gallagher

Our attention is being stolen.
We’re slowly losing the ability to concentrate, not only because of TikTok, but also because we constantly have access to easy consumption. It’s digital fast food.

When I started to notice this on myself, I started with the naïve approach and deleted all time sink¹ apps like YouTube or Instagram. This worked for a day or two until I either got bored or found another reason to re-install.

Then I moved to Apple Screen Time. This works for a bit, but that “15 minutes more” button starts to become muscle memory very quickly. Even apps like one sec got deleted because they’re annoying (that’s the idea, I know).

In January 2024 I went 7 days with only my Apple Watch, leaving my iPhone at my desk at all times. It was doable, but very impractical.

None of this worked

In early 2025 I sold my Apple Watch and bought a Casio DW-5600BB-1. This had a large impact as I would no longer get buzzed on my wrist for every notification².

Then I deleted my Instagram account and the YouTube, Mastodon and Bluesky apps. Yes, a lot of my friends are on Instagram—but I mostly watched Reels anyway! I do miss Mastodon. I now use YouTube in Safari with shorts blocked. This creates enough friction for me to watch videos intentionally (most of the time). It also lets me use cool extensions like SponsorBlock and DeArrow.

And when Apple Intelligence (if you can call it that) got to Europe, I turned on the new Reduce Interruptions focus and never turned it off. This works great because it randomly lets things through, but blocks most of it.

I tried a dumb phone³, but this was way too much friction—I need a usable phone for renting a bike, getting my parcels, etc.

In March I bought a Bullet Journal and started tracking my tasks there instead of my phone. I also started journalling and tracking my habits and I love the analog lifestyle—even my running plan is analog!

The combination of all of this is working out pretty well so far: My phone is mostly boring. It doesn’t have any exciting apps. It doesn’t spark joy. Because of this, I’m spending my time a lot more intentional.

That being said, sometimes I spend a little too much time on YouTube (at least that’s longform content) and I should probably delete the Slack app to not check the work chat when I’m not at my desk.

We deserve more humane tech

I’m happy to see the first smartphone vendors start to add physical switches to their phones to disable connectivity or limit apps⁴ and maybe I’ll switch to one of them one day.

This is not a political post, but if it was, it would talk about the obscene power of big tech and the necessity to regulate and break up. It would appeal on you to rethink your investment into these services, services that are actively spying on you, services that exploit your mental health for the sake of raising shareholder value.

Now go, touch some grass⁵. 🌱

Music

• I Love You So F***ing Much by Glass Animals: One of my favorite bands, every single album is amazing. and this is no exception.
• Clancy by Twenty One Pilots: There’s artists with unique story telling and then there’s Twenty One Pilots. I really like this album.
• From Zero by Linkin Park: This sounds like Hybrid Theory reloaded—which is a good thing—and I love that they’re back.
• Older (and Wiser): This is the music you want to hear on long train rides through the country side and on long winter evenings.

Books

These links go to my reviews (no spoilers):

• Piranesi by Susanna Clarke: One of the best books I’ve ever read.
• Project Hail Mary by Andy Weir: Loved the book and told everyone about it after reading it.
• The Expanse series by James S. A. Corey: 7 books plus a few novellas. Couldn’t stop reading!
• Useful Not True by Derek Sivers: One of the books that change how you think about the world, incredible read.

Apps

• Manet: I’ve started buying my music and hosting it myself this year¹, this app makes it a joy to listen to music.
• CouchTimes: The best TV show tracker in the App Store, period. It doesn’t have feature bloat and it respects your privacy.
• Ghostty: A super fast, new Terminal emulator for the Mac.
• Halide: This camera app has been around for a while, but this year they released Process Zero, a mode that applies minimal corrections and makes photos look more like digital camera photos.

Goods

• aranet4: There are cheaper options, but a CO₂ monitor for my home office has helped me keep the air at good levels.
• heat-it: This tiny tool draws power from your phone to relieve itch & pain from insect bites.
• Leatherman 2H Wave+: The only big Leatherman that’s legal to carry in Germany, super versatile and handy to have around.

What were your favorites?

Initialize a repository

You can initialize jj in an existing git repository like this:

$ jj git init --git-repo .

This will create a .jj directory next to .git. You can now use both git and jj, although I wouldn’t recommend it. There’s a work-in-progress native storage backend, but since all my projects are git repositories anyway, this works great for me.

Note that this is non-destructive; if you want to go back to git, all it takes is a rm -r .jj.

Get an overview

Running jj log in the repository for this very website gives this output:

$ jj log
@  qzsvtxpv hey@arne.me 2024-10-21 09:58:06 e18f7532
│  Add blog/jj-in-practice
│ ○  yoxxsupn hey@arne.me 2024-10-20 22:55:03 ae5d9109
├─╯  Add library/calibans-war
│ ○  tvkvwslw hey@arne.me 2024-10-20 22:49:54 5e4dee1f
├─╯  Add library/the-posthumous-memoirs-of-bras-cubas
│ ○  pywmtrys hey@arne.me 2024-10-20 21:20:11 7bda14b7
│ │  Add atoms/1
│ ○  xnlzypwn hey@arne.me 2024-10-20 21:20:10 8a004404
├─╯  Add atoms functionality
◆  wxxtrmqk hey@arne.me 2024-10-20 16:18:15 main HEAD@git 1eb46c81
│  Add weekly/166
~

This already shows one of the biggest differences, compared to git: There’s no branches, other than main. You can create branches, which are called bookmarks in jj, but you don’t need to. Instead, you work mostly with changes¹.

The terminal above shows the change w (you can use the first letter to reference changes; on your terminal it’ll be highlighted as well) as a parent to x, t, y and q. All these child-revisions don’t have a branch/bookmark, but they don’t need one. You can see what’s in-flight at this repository better than with any git repo, especially if branches haven’t been cleaned up in a while.

Create a revision

My usual flow with git is to leave changes in the staging area until I’m ready to commit. Sometimes, if I have to switch branches or want to save my work, I’ll stash or create a WIP commit.

In jj, there is no staging area—everything is a revision. Let’s create a new revision on top of my revisions where I add atoms functionality:

$ jj new -r p

Running git log again:

$ jj log
@  kxqvnxnw hey@arne.me 2024-10-21 10:03:20 22c020cf
│  (empty) (no description set)
○  pywmtrys hey@arne.me 2024-10-20 21:20:11 HEAD@git 7bda14b7
│  Add atoms/1
○  xnlzypwn hey@arne.me 2024-10-20 21:20:10 8a004404
│  Add atoms functionality
│ ○  qzsvtxpv hey@arne.me 2024-10-21 10:03:18 27229dca
├─╯  Add blog/jj-in-practice
│ ○  yoxxsupn hey@arne.me 2024-10-20 22:55:03 ae5d9109
├─╯  Add library/calibans-war
│ ○  tvkvwslw hey@arne.me 2024-10-20 22:49:54 5e4dee1f
├─╯  Add library/the-posthumous-memoirs-of-bras-cubas
◆  wxxtrmqk hey@arne.me 2024-10-20 16:18:15 main 1eb46c81
│  Add weekly/166
~

You’ll notice that our active revisions are now left-aligned, and the one to add this very blog post has moved to the right. There’s no hierarchy, they’re all descendants of Add weekly/166.

After doing some work, e.g. adding a new atom, I can describe that revision with jj describe. This is comparable to git commit, but it doesn’t actually create a commit or a revision, it only describes the current one.

Sometimes I want to update a previous revision, in this case Add atoms/1. I can run jj squash to merge the current one with its parent.

Push and pull

To fetch new revisions, I run jj git fetch; to push branches/bookmarks, I run jj git push. This uses the same git server it was using before.

Before pushing, I need to move my bookmark to the revision I want to push. I push the main branch to deploy my website, so if I wanted to publish my atoms functionality (should I?), I would run jj bookmark set main -r p before pushing.

Rebase and split

Sometimes I need to rebase. Fortunately that’s a lot simpler than it is in git: I can run jj rebase -s <source> -d <destination> to move revisions around. If I wanted support for atoms for this blog post, I would run jj rebase -s q -d p and it would move the revision for this blog post on top of “Add atoms/1”.

jj also does automatic rebasing, e.g. if you squash changes into a revision that has descendants.

And if I have a revision that I’d like to be two, I run jj split and interactively select what belongs to which revision.

Undo

Undoing an (interactive) rebase in git is not fun. jj undo undoes the last jj operation, doesn’t matter if it’s abandoning (deleting) a revision or doing a rebase. This is a life saver! You can also run jj op log to display your last jj operations.

Things I stumble upon

I’ve been using git for a long, long time. My brain assumes that after a commit, I’m working on the next one. It also assumes that jj describe does the same as git commit (it does not). I often describe a revision and continue editing files, which then erroneously get added to the current revision. I’m not saying this is wrong, it makes sense in the jj world, but I keep tripping over that and have to run jj split to pull changes out again.
alterae on Lobste.rs pointed out that you can describe and immediately create a new revision on top of it with jj commit. Thanks!

One other thing is that you cannot check out a revision directly (or maybe I just don’t know how to), so when I’ve moved to a different revision and want to move back, I run jj new <revision>, which creates an empty revision on top of it. This means that if I’m not done with the revision, I have to keep running jj squash to move changes into it.
gecko on Lobste.rs pointed out that you can check out a revision directly with jj edit <revision>. Thanks!

Why it works for me

A week ago, I removed jj from my website’s repository, to see if I’d miss it. I added it back the same day. Jujutsu feels lighter than git, while at the same time giving you a full overview of what’s in-flight right now². Having no staging area means I only need to worry about revisions (see caveat above).

If trying new things sounds fun to you, give Jujutsu a spin!

Further reading

• Official Jujutsu Tutorial
• Comparison with Git
• Steve’s Jujutsu Tutorial
• Chris Krycho’s jj init essay
• Chris Krycho’s video on jj

It just works. — Steve Jobs

If you follow this blog, you’ll know that I’m doing a series called “Emacs Config From Scratch”¹. Emacs is an editor operating system, where you can configure and customize literally everything. I like that you can truly make it yours, but it’s a lot of work to get there.

Recently, I’ve become fond of (command line) tools that just work, out of the box². This blogpost is an ode to them.

Fish

Julia Evans recently posted Reasons I still love the fish shell, and the first point she makes is “no configuration”.

Things that require plugins and lots of code in shells like ZSH, like autosuggestions, are included and configured by default in fish. At the time of writing this, my fish config has less than 31 loc, most of which are abbreviations.

I have two fish plugins configured: z for jumping to a directory, and hydro as my shell prompt. Neither need configuration.

Helix

My Neovim config had 21 external plugins. Making LSP, tree-sitter and formatting work took a while (LSP alone needs 3 plugins) and in the end there were still things that didn’t work.

I’ve switched to Helix, which can do so much out of the box, here’s a non-exhaustive list:

• LSP (including autocompletion, show signature, go to definition, show references, etc.) just works
• Tree-sitter is built in, you can even do selections on tree-sitter objects
• A file picker and global search
• Pressing a key in normal mode shows subsequent keys you can press, and what they do
• You can jump to any visible word, add/remove/replace quotes or other characters
• … and so much more

The config for the code editor I use all day is 5 loc. Here it is:

theme = "kanagawa"

[editor]
line-number = "relative"
cursorline = true
rulers = [80]

I will say that it takes some getting used to as it folows the selection -> action model, i.e. you need to run wd instead of dw to delete the next word.

Lazygit

After raving about Magit in London, my team showed me Lazygit and I’ve been using it ever since—it’s really good and it does exactly what you want it to do, without configuration³.

You can toggle different screen modes, panes adjust in size when active and pretty much everything you want to do is only a few keystrokes away.

Zellij

A batteries-included Tmux alternative, Zellij doesn’t need any configuration to work well. You can set up Layouts without additional plugins (although there is a plugin system) and I’m generally not missing anything from my Tmux configuration.

My favorite feature is the floating panes. Press Ctrl + p, w to toggle a pane floating on top of everything else—I often use this for Lazygit.

What else?

Here are some tools you have sent me that are zero/minimal config:

• Matthew shared Broot, a new way to see and navigate directory trees
• Ilija shared k9s, a CLI to maange Kubernetes clusters
• Alexander shared Orbiton, a text editor they built

Do you have a tool that requires no (or minimal) configuration? Send me an email and I’ll add it to the list!

And if you’re building something, please strive to make the default experience work really well for most people.

Table Of Contents

• Housekeeping
• LSP
• Tree-sitter
• Language support
• Search
• Wrapping up

Housekeeping

The first thing I want to do is make the UI titlebar match the Emacs theme and hide the file icon:

(use-package emacs
  :init
  (add-to-list 'default-frame-alist '(ns-transparent-titlebar . t))
  (add-to-list 'default-frame-alist '(ns-appearance . light))
  (setq ns-use-proxy-icon  nil)
  (setq frame-title-format nil))

The next thing is automatically loading $PATH from my shell using exec-path-from-shell—this is important so Emacs can find our installed binaries, e.g. for language servers:

(use-package exec-path-from-shell
  :init
  (exec-path-from-shell-initialize))

Another problem I ran into was writing square brackets when on the MacBook, as it would interpret the keys as Meta-5/Meta-6. I fixed that by updating the keybindings from Part 1:

(use-package emacs
  :init
  (when (eq system-type 'darwin)
    (setq mac-command-modifier 'super)
    (setq mac-option-modifier nil)
    (setq mac-control-modifier nil)))

I like to keep most of my code at 80 characters, so let’s add a ruler:

(use-package emacs
  :init
  (setq-default fill-column 80)
  (set-face-attribute 'fill-column-indicator nil
                      :foreground "#717C7C" ; katana-gray
                      :background "transparent")
  (global-display-fill-column-indicator-mode 1))

Finally, we want to store backup files in ~/.saves instead of next to the file we’re saving:

(use-package emacs
  :config
  (setq backup-directory-alist `(("." . "~/.saves"))))

LSP

Let’s install company-mode first, for auto-completion:

(use-package company-mode
  :init
  (global-company-mode))

Now we configure the built-in LSP package eglot:

(use-package emacs
  :hook (zig-mode . eglot-ensure)
  :hook (rust-mode . eglot-ensure)
  :hook (go-mode . eglot-ensure)
  :hook (typescript-mode . eglot-ensure)
  :general
  (leader-keys
    "l" '(:ignore t :which-key "lsp")
    "l <escape>" '(keyboard-escape-quit :which-key t)
    "l r" '(eglot-rename :which-key "rename")
    "l a" '(eglot-code-actions :which-key "code actions")))

This runs eglot-ensure in languages we have language servers installed for. It also sets up SPC l r to rename a symbol and SPC l a to prompt for code actions.

Tree-sitter

We’ll use treesit-auto to automatically install and use tree-sitter major modes:

(use-package treesit-auto
  :custom
  (treesit-auto-install 'prompt)
  :config
  (treesit-auto-add-to-auto-mode-alist 'all)
  (global-treesit-auto-mode))

This is handy because it doesn’t require us to think about using e.g. zig-ts-mode instead of zig-mode, it handles everything for us.

Language support

Next, we install all language modes we need:

(use-package markdown-mode
  :config
  (setq markdown-fontify-code-blocks-natively t))
(use-package zig-mode
  :general
  (leader-keys
    "m" '(:ignore t :which-key "mode")
    "m <escape>" '(keyboard-escape-quit :which-key t)
    "m b" '(zig-compile :which-key "build")
    "m r" '(zig-run :which-key "run")
    "m t" '(zig-test :which-key "test")))
(use-package rust-mode
  :general
  (leader-keys
    "m" '(:ignore t :which-key "mode")
    "m <escape>" '(keyboard-escape-quit :which-key t)
    "m b" '(rust-compile :which-key "build")
    "m r" '(rust-run :which-key "run")
    "m t" '(rust-test :which-key "test")
    "m k" '(rust-check :which-key "check")
    "m c" '(rust-run-clippy :which-key "clippy")))
(use-package go-mode)
(use-package gotest
  :general
  (leader-keys
    "m" '(:ignore t :which-key "mode")
    "m <escape>" '(keyboard-escape-quit :which-key t)
    "m t" '(go-test-current-project :which-key "test")
    "m r" '(go-run :which-key "run")))
(use-package typescript-mode)

I’m using SPC m to change based on major-mode, e.g. means SPC m t means test in most programming modes, but won’t exist in markdown-mode.

Search

Sometimes we don’t know what file we’re looking for, so let’s add rg.el to help us find it:

(use-package rg
  :general
  (leader-keys
    "f" '(rg-menu :which-key "find")))

This opens a Magit-like menu and allows you to search in various modes (dwim, regex, literal, etc.).

Wrapping up

Opening a Zig project now looks like this³; see also the final init.el:

I’m going to switch to Emacs as my primary editor and tune it further in the coming weeks. In the next part, I want to add support for Org-mode, show a dashboard on startup, enable font ligatures and fix all the small things that I’ll find.

Subscribe to the RSS feed so you don’t miss Part 4, and let me know what you think!

Writing a small application is a lot easier than writing a library, especially if you’re hacking it together like I was. Let’s do something harder.

And because I work at Axiom, we’re going to write an SDK for the public API. In this first part I’ll set up the library and add a single getDatasets fn to fetch all datasets the token has access to.

Bootstrap the SDK

First, we create a directory called axiom-zig and run zig init:

info: created build.zig
info: created build.zig.zon
info: created src/main.zig
info: created src/root.zig
info: see `zig build --help` for a menu of options

We also want to create a .gitignore to ignore the following folders:

/zig-cache
/zig-out

Perfect. Next step: Create a client struct in root.zig. We’ll need an Axiom API token to authenticate requests, a std.http.Client to make requests and an std.mem.Allocator to allocate and free resources:

const std = @import("std");
const Allocator = std.mem.Allocator;
const http = std.http;
// We'll need these later:
const fmt = std.fmt;
const json = std.json;

/// SDK provides methods to interact with the Axiom API.
pub const SDK = struct {
    allocator: Allocator,
    api_token: []const u8,
    http_client: http.Client,

    /// Create a new SDK.
    fn new(allocator: Allocator, api_token: []const u8) SDK {
        return SDK{ .allocator = allocator, .api_token = api_token, .http_client = http.Client{ .allocator = allocator } };
    }

    /// Deinitialize the SDK.
    fn deinit(self: *SDK) void {
        self.http_client.deinit();
    }
}

test "SDK.init/deinit" {
    var sdk = SDK.new(std.testing.allocator, "token");
    defer sdk.deinit();
    try std.testing.expectEqual(sdk.api_token, "token");
}

Initially I had deinit(self: SDK) (without the pointer). Zig didn’t like this at all and led me down a rabbit hole of storing the http.Client as a pointer too—once I found my way out and remembered I need a pointer everything worked.

I like that Zig encourages writing tests not only next to the source code (like Go), not only in the same file (like Rust), but next to the code it’s testing.

Add getDatasets

Our first method will be getDatasets, which returns a list of Axiom datasets (see the api documentation).

Create a model

First we need a model:

pub const Dataset = struct {
    id: []const u8,
    name: []const u8,
    description: []const u8,
    who: []const u8,
    created: []const u8,
};

Don’t worry about created being a datetime, we’ll deal with that later.

Add the getDatasets fn

Let’s add a function to get the datasets to our SDK struct:

/// Get all datasets the token has access to.
/// Caller owns the memory.
fn getDatasets(self: *SDK) ![]Dataset {
    // TODO: Store base URL in global const or struct
    const url = comptime std.Uri.parse("https://api.axiom.co/v2/datasets") catch unreachable;

    // TODO: Draw the rest of the owl
}

We’re taking a pointer to SDK called self again, this means that this is a method you call on a created SDK. The ! means it can return an error. In a later post I want to go deeper into error handling, for now it can return any error.

Because there is no dynamic part of the URL, we can parse it at compile time using comptime. I like this explicit keyword, in Rust you need to rely on macros to achieve something similar, or use lazy_static.

Make the HTTP request

Let’s open a connection to the server:

var server_header_buffer: [4096]u8 = undefined; // Is 4kb enough?
var request = try self.http_client.open(.GET, url, .{
    .server_header_buffer = &server_header_buffer,
});
defer request.deinit();

I wonder if 4kb is always enough for server headers. Especially in a library I don’t want it to fail because the server is suddenly sending more headers.

Axiom uses Bearer auth, so let’s set the Authorization header:

var authorization_header_buf: [64]u8 = undefined;
// TODO: Store this on the SDK for better re-use.
const authorization_header = try fmt.bufPrint(&authorization_header_buf, "Bearer {s}", .{self.api_token});
request.headers.authorization = .{ .override = authorization_header };

An Axiom API is 41 characters, plus Bearer ‘s 7 characters equals 48 characters. We’re allocating 64 to be safe if it ever changes (it really shouldn’t).

Also note that I’m calling try fmt.BufPrint; this will return the error to the caller of our function (that’s what the ! indicating).

Finally, we can send the headers to the server and wait for a response:

try request.send();
try request.wait();

Parse the JSON-response

First, we need to read the body into a buffer:

var body: [1024 * 1024]u8 = undefined; // 1mb should be enough?
const content_length = try request.reader().readAll(&body);

Same issue as with the server headers: What is a good size for a fixed buffer here?

I’ve tried doing this dynamically with request.reader().readAllAlloc(...), but parsing the JSON with this allocated memory relied on the allocated []const u8 for string values. This means as soon as I deallocated the body, all string values in the returned JSON were invalid (use-after-free). Yikes.

Next, we call json.parseFromSlice with our body:

const parsed_datasets = try json.parseFromSlice([]Dataset, self.allocator, body[0..content_length], .{});
defer parsed_datasets.deinit();

Now we need to copy the memory out of the parsed_datasets.value to prevent it from being freed on the parsed_datasets.deinit() above and return it:

const datasets = try self.allocator.dupe(Dataset, parsed_datasets.value);
return datasets;

Edit: Matthew let me know on Mastodon that this implementation is still illegal, and it’s only working because the stack memory is not getting clobbered. You can set .{ .allocate = .alloc_always } in json.parseFromSlice, which will dupe the strings, but not actually solve the problem (where do the strings live?). What I ended up doing is creating a Value(T) struct, which embeds both the value and an arena allocator which I pass to json.parseFromSliceLeaky. This means the value you get back from getDatasets will have a deinit() method and you need to do .value to get the actual value. You can read the updated source code on Codeberg.

Write a test

And finally we’ll write a test where we initialize the SDK, get the datasets and ensure _traces is the first one returned. Once I set up CI, I’ll create an Axiom org just for testing so we can be sure which datasets are returned.

test "getDatasets" {
    const allocator = std.testing.allocator;

    const api_token = try std.process.getEnvVarOwned(allocator, "AXIOM_TOKEN");
    defer allocator.free(api_token);

    var sdk = SDK.new(allocator, api_token);
    defer sdk.deinit();

    const datasets = try sdk.getDatasets();
    defer allocator.free(datasets);

    try std.testing.expect(datasets.len > 0);
    try std.testing.expectEqualStrings("_traces", datasets[0].name);
}

If you want to see everything together, check it out on Codeberg.

Next steps

In the next part I’ll add createDataset, updateDataset and deleteDataset, initial error handling and show how you can import the library in a Zig project.

Any thoughts? Let me know!

• No hidden control flow.
• No hidden memory allocations.
• No preprocessor, no macros.

For someone like me coming mostly from Rust, Go and TypeScript, this is different—and different is interesting, so I wanted to know what it feels like to write code in it.

Here are my thoughts after 3 nights of using Zig to rewrite the static site generator¹ I use for the Fire Chicken Webring. Note that this is a limited use case and only scratches the surface of the language.

Explicit allocation

This is one of the biggest differentiators of Zig. Go doesn’t force you to think at all, Rust forces you to think about ownership and Zig forces you to think about allocations. If you want to allocate memory, you need to pass an allocator to it and remember to free it afterwards.

One thing that I stumbled upon a lot: Sometimes there is a .deinit() function on the returned struct, sometimes that method takes an allocator, sometimes you need to allocator.free(value) and sometimes it returns an enum or a struct, and you need to figure out which values you have to free.

Documentation

If you write Zig, you’ll find yourself reading Zig a lot to understand how to use a function, which resources you must free, and possibly, why that function panics. There is no generated documentation like docs.rs or pkg.go.dev; if you want to know which methods a library has, look at the source.

Here are some resources other than the source code that I found useful to get started:

• In-depth Overview
• Zig Language Reference
• Zig by Example
• Zig Cookbook
• Zig Guide
• Zig std documentation

Another reason you might need to look at the source code of function you’re calling is confusing error messages.

Errors

The error messages of the Zig compiler can be very hard to figure out. Here’s an example:

$ zig build run
Segmentation fault at address 0x102ee6000
Panicked during a panic. Aborting.

Generally, if you’re used to Rust’s exceptional error handling, this is rough.

Once I got an error from the standard library and only noticed after reading the source code that ArrayList is not a supported type to pass to the given function. Another time, the templating library I’ve temporarily used randomly panicked with an out-of-bounds after doing a nested loop.

Libraries

There are a bunch of libraries for Zig (see awesome-zig) and I can only talk about the one’s I’ve tried, but most of the libraries I’ve looked at are either archived, a thin wrapper around a C library, heavy WIP and barely usable, or have weird error scenarios.

This lead to me implementing my own shitty datetime function² and using std.fmt instead of templating.

I believe these are due to the immaturity of the language and ecosystem, but I wouldn’t be surprised if people started building their own libraries, which they take everywhere.

Strings

We have to talk about strings. Zig has none; if you want a string, use []const u8. You also can’t compare that type with ==, you need to use a specific function³.

Initially I found this irritating—why not introduce a string type that is []const u8 under the hood and overload the == operator? I think it would improve developer experience, but does it fit into Zig?

No magic

Remember the three idioms from the beginning of the article? Zig is huge on being transparent, i.e., no magic; the code you read is what happens.

And I appreciate that. In Rust, it’s common to build abstractions to hide boilerplate logic (e.g. using macros to generate the deserialization logic of a struct), in Go it’s common to generate code to do this. Zig doesn’t have any of that (though I guess you could generate Zig code). I’m not sure how well that scales in big codebases, but I think it’s interesting.

Conclusion

I like Zig. For a bigger project or something that needs async⁴, I’ll still reach for Rust for its safety features and vibrant ecosystem, but for small projects, it’s fun to reach for an interesting language.

If you know your way around servers, this is neither a novel nor a complicated setup—quite the opposite; the beauty of this configuration lies in its simplicity.

Table of Contents

• Set up a VM with NixOS
• Install and configure packages
• Configure Jellyfin
• Apps
• Conclusion

Set up a VM with NixOS

The smallest (and cheapest) VM on Hetzner Cloud, CX11 with 1 VCPU and 2 GB RAM, is more than enough¹.

Because my music collection is still pretty small, I’ve decided to go with Hetzner volumes. If you have more than 100 GB of music, I’d recommend looking into a different storage solution in combination with rclone, see the storage section of an earlier post.

Hetzner doesn’t have a one-click NixOS image, so I chose any image and followed the “traditional” ISO installation as described in this repo: nixos-install-scripts. The NixOS docs also recommend nixos-infect—if you take this path, I’d be genuinely interested to hear how it worked.

Then, just to be safe, I ran nix-channel --update and nixos-rebuild switch --upgrade on the VM to upgrade everything to the latest version.

After finding my attached volume with ls /dev/sd* and mounting it with mount /dev/sdb /mnt/media (replace /dev/sdb with the path of your volume), I ran nixos-generate-config to regenerate the hardware configuration and automatically mount it on the next boot.

Because this VM is only for music, I didn’t do anything to harden the vm. If you want more security, take a look at the excellent Paranoid NixOS Setup article by Xe.

Install and configure packages

On the VM, I opened /etc/nixos/configuration.nix in a text editor. Nano comes installed out of the box, but you can get vim in an ephemeral shell with nix-shell -p vim.

In that file, I started by changing networking.hostName and time.timeZone. Subsequently, I configured the installed packages:

environment.systemPackages = with pkgs; [
  jellyfin
  jellyfin-web
  jellyfin-ffmpeg
  caddy
  logrotate
];

Jellyfin

Jellyfin is an open-source media server, comparable to Plex. I installed Jellyfin itself (jellyfin), the official Jellyfin web client (jellyfin-web), and a modified version of FFmpeg for hardware acceleration (jellyfin-ffmpeg). Let’s enable Jellyfin:

services.jellyfin.enable = true;

Caddy

We need a reverse proxy, mostly for automatic HTTPS.
I chose Caddy because the configuration is the shortest²:

services.caddy = {
  enable = true;
  virtualHosts."jellyfin.example.com".extraConfig = ''
    reverse_proxy 127.0.0.1:8096
  '';
};
networking.firewall.allowedTCPPorts = [ 80 443 ];

You should replace jellyfin.example.com with the domain you want to use for your Jellyfin setup. Make sure to point A and AAAA records in your domain provider to the public IP addresses of the VM.

Logrotate

After a few days, I was uploading more music and noticed, that my SFTP uploads were stalled. After hours of debugging, I found out, that this apparently was due to a very large /var/log/auth.log beeing too large³.

logrotate fixes this by automatically rotating, compressing and removing this (and other) log files. It’s enabled like this:

  services.logrotate.enable = true;

Auto-upgrade

To keep maintenance low, I enable automatic system upgrades using the following configuration:

system.autoUpgrade = {
  enable = true;
  allowReboot = true;
}

This checks every day at 4:40 am by default, so the chances of the VM rebooting while I want to listen to music are very slim.

Apply changes

Run nixos-rebuild switch to apply the configuration.

Configure Jellyfin

Go to the address of your server and follow the installation wizard to set up Jellyfin⁴. Create a library for your music and upload some to /mnt/media.

Apps

Having a good mobile app is crucial for me. The official Jellyfin apps are excellent for configuring Jellyfin, but not great for listening to music.

When I discovered Manet, an iOS app, it changed everything. While it looks and feels very similar to Apple Music, it works significantly better. André, the developer who is developing this on the side, is super responsive and quick to fix the occasional bug. Seriously, if you use Jellyfin and iOS, and not use this app, you’re missing out. Did I mention that it’s beautiful and free?

On the web, I’m using the web client. It’s not great, but it’s fine. Hoping for Manet on macOS one day⁵.

Conclusion

And there you have it: A self-hosted music streaming service for around €6 / month, configured with a few lines of code and requiring little maintenance.

I’ve been using this for over a month now, and I couldn’t be happier.

What does your setup look like? Any feedback? Let me know!

And I’m trying to fix this: I don’t have TikTok¹ or Instagram, I only use YouTube in Safari with Shorts blocked, and I use one-sec for apps that I don’t want to waste my time on. But still, time-sinks keep creeping in after a week or two.

So, I did what I wanted to do for years: I put my iPhone at my desk and left it there for 7 days². Here’s how it went.

The setup

Here’s all the things I can do reasonably effective with my Apple Watch Ultra 2:

• Inspect and create calendar events
• Manage my tasks with the OmniFocus 4 watch app
• Send and receive texts with a swipe-capable on-screen keyboard or voice input
• Make and receive phone calls
• Track my hydration using Waterminder
• Track medication
• Check the weather with Carrot Weather
• Record workouts with Gentler Streak
• Record voice notes with Just Press Record
• Navigate to and in places with Maps
• Listen to music and podcasts with Apple’s apps

I also utilized the Action Button to run a Shortcut with the following menu:

• New OmniFocus inbox item
• Start audio recording
• Toggle my office light (for that sweet sweet Rembrandt lighting)
• Defer OmniFocus items to tomorrow (you can’t do that using the watchOS app)

How it changed my everyday life

Instead of being constantly reachable—not only via text or calls, but also via email and socials, I sat down in the evenings for some admin time. In that time, I would check and reply to emails and non-iMessage text messages, as well as going through OmniFocus and Just Press Record data to clean it up.

But besides that time, I was just—present. When I was out and about and waiting for something, I was forced to just wait. This gave me time to reflect and think things through, a time I didn’t know I was missing. Instead of having to make an effort to not look at my phone when I’m with friends, I was relaxed because I had no other choice. And instead of doom-scrolling while watching a TV show on the couch, I just watched the TV show (a nice side effect is that this raises the bar of content you consume).

But there were some downsides: I bought a new pair of glasses in that week and had no phone to make a quick photo (I hope I still like them when they arrive this week, lol). My watch had an issue with phone calls one morning, so I couldn’t make or take phone calls (a restart eventually fixed it). My 4-year-old complained that I can’t play an audiobook or music for him while in the car. Because the swipe keyboard was not as reliable as I wished it’d been, I used the voice input in places where it might be awkward. I had to take a piece of paper to write things down that I needed to remember (like the model of the lenses for my new glasses).

Here’s a guest contribution from my wife:

This husband of mine has many ideas. The “I dump my phone”-experiment was not my favorite one. I’m all for reducing your screen time and limiting doomscrolling. But being unreachable because your Apple Watch decides to throw a tantrum, not being able to answer quickly to a text or to capture an important family moment because you don’t have a camera—that’s just not practical, especially when you forget to recharge your watch. So this little experiment drove me crazy more than once tbh—and I am a little relieved it’s over now. I really do hope he still likes his new glasses when they arrive. It never gets boring with this one.

Should you do this?

This heavily depends on how much you are willing to give up. You can carry a notebook and pen and a camera and fix some of the issues noted above. Maybe you don’t need to text as much.

I definitely recommend trying it; I got my phone back today, and I appreciate both the flexibility—I can do almost anything with it—and being more present in some situations.

That being said, I was looking forward to getting my phone back after four days. Worth a try.

Here they are, in no particular order:

• “I’m On It”: Mike Fisher writes about their favorite response when given a task.
• The science of why you have great ideas in the shower: Stacey Colino has the neurological explanation for the reasons you get great ideas in the shower or find bug fixes when on a walk: The default mode network in your brain.
• Bricks of Love: create purpose and engagement with weekly updates: João Alves about purpose, motivation, and the magic of weekly updates.
• Visual design rules you can safely follow every time: Anthony Hobday has a list of design rules that you should remember.
• The Most Valuable Programmer: Arend van Beelen jr. writes about the feature that make someone an MVP (Most Valuable Programmer).
• There’s no such thing as a tree (phylogenetically): Georgia Ray explains why most trees developed individually and other weird botanic quirks.
• 8 Ways to Read (a Lot) More Books This Year: Neil Pasricha writes a very motivating article with tips to read more books.
• You’d Be Happier Living Closer to Friends. Why Don’t You?: Anne Helen Petersen asks why people don’t live closer to friends (i.e., in the same street).
• Every self-help book ever, boiled down to 11 simple rules: Chris Taylor tries to distill the essence of hundreds of self-help books into eleven rules.
• Multi-layered calendars: Julian noticed that our calendars are stuck in the past and explores a more modern approach using different layers for different activities.
• How a startup loses its spark: John Qian explains what makes a startup intoxicating and how these qualities are eroded with more employees.

What were your favorites? Let me know!

In Part 1, we’ve set up the UI and evil mode. Today we’ll set up a way to manage projects, quickly find files, set up custom keybindings, interact with Git and open a terminal inside Emacs.

Table of Contents

• Project manager
• Custom keybindings
• Fuzzy finding
• Git integration
• Terminal
• Small tweaks
  • Make Ctrl-u work like in Vim
  • Comment lines
  • Optimizing the garbage collector
  • Don’t use ESC as a modifier
• Conclusion

Project manager

Vim is usually terminal-first; you navigate to a directory and open Vim. Emacs is the other way around; you start Emacs, open a project and maybe a terminal buffer (see Terminal further down).

Let’s set up Projectile to manage our projects and quickly find files.

(use-package projectile
  :demand
  :init
  (projectile-mode +1))

You can now run M-x (a.k.a. Opt-x on macOS) and type projectile-add-known-project to add a project as well as projectile-switch-project to open a project.

This is neither fast, nor discoverable. Let’s set up some custom keybindings.

Custom keybindings

Before we define our own keybindings, we need to do something to improve discoverability. which-key will show available commands as you start a keybinding sequence:

(use-package which-key
  :demand
  :init
  (setq which-key-idle-delay 0.5) ; Open after .5s instead of 1s
  :config
  (which-key-mode))

We’ll use general.el because it makes it super easy to define keybindings and allows us to define them in a use-package function.

We’ll have SPC as our leader key, which allows us to press SPC and have all our custom keybindings show up.

(use-package general
  :demand
  :config
  (general-evil-setup)

  (general-create-definer leader-keys
    :states '(normal insert visual emacs)
    :keymaps 'override
    :prefix "SPC"
    :global-prefix "C-SPC")

  (leader-keys
    "x" '(execute-extended-command :which-key "execute command")
    "r" '(restart-emacs :which-key "restart emacs")
    "i" '((lambda () (interactive) (find-file user-init-file)) :which-key "open init file")

    ;; Buffer
    "b" '(:ignore t :which-key "buffer")
    ;; Don't show an error because SPC b ESC is undefined, just abort
    "b <escape>" '(keyboard-escape-quit :which-key t)
    "bd"  'kill-current-buffer
  )

We’re using :which-key to add a description that will show up next to the command. To add custom keybindings to Projectile, we need to edit the use-package definition and move it after the use-package general function:

(use-package projectile
  :demand
  :general
  (leader-keys
    :states 'normal
    "SPC" '(projectile-find-file :which-key "find file")

    ;; Buffers
    "b b" '(projectile-switch-to-buffer :which-key "switch buffer")

    ;; Projects
    "p" '(:ignore t :which-key "projects")
    "p <escape>" '(keyboard-escape-quit :which-key t)
    "p p" '(projectile-switch-project :which-key "switch project")
    "p a" '(projectile-add-known-project :which-key "add project")
    "p r" '(projectile-remove-known-project :which-key "remove project"))
  :init
  (projectile-mode +1))

Now we can press SPC and get suggestions that we can navigate along. SPC SPC lets you open a file in the current project (or a project if none is open), SPC b opens buffer options, SPC p project options, etc.

This is what it looks like:

But when you try to find a file, or add a project, you’ll notice that this is clunky as you need to type the exact path for it to work. Let’s fix that.

Fuzzy finding

We’ll be using ivy as our generic completion frontend. This will make choosing files and projects a lot more ergonomic:

(use-package ivy
  :config
  (ivy-mode))

Now we get a list of possible entries and live-search.

Git integration

To manage source control, we’ll use Magit, which is–rightfully–widely considered to be the best Git client ever:

(use-package magit
  :general
  (leader-keys
    "g" '(:ignore t :which-key "git")
    "g <escape>" '(keyboard-escape-quit :which-key t)
    "g g" '(magit-status :which-key "status")
    "g l" '(magit-log :which-key "log"))
  (general-nmap
    "<escape>" #'transient-quit-one))

To make Magit work nicely with Evil, let’s add evil-collection:

(use-package evil-collection
  :after evil
  :demand
  :config
  (evil-collection-init))

In addition we need to add this to the :init block of use-package evil to prevent evil and evil-collection interfering:

(setq evil-want-keybinding nil)

Now SPC g g will open up the current Git status. You can stage single files with s, all files with S and commit by pressing cc.

Finally, we want to highlight uncommited changes in the gutter:

(use-package diff-hl
  :init
  (add-hook 'magit-pre-refresh-hook 'diff-hl-magit-pre-refresh)
  (add-hook 'magit-post-refresh-hook 'diff-hl-magit-post-refresh)
  :config
  (global-diff-hl-mode))

Terminal

Even though we’ll try to make everything work from inside Emacs, sometimes it’s just quicker and easier to have a shell.

We’ll use vterm as a terminal emulator we can use inside emacs.

(use-package vterm)

We’ll also install vterm-toggle, a package that allows us to toggle between the active buffer and a vterm buffer:

(use-package vterm-toggle
  :general
  (leader-keys
    "'" '(vterm-toggle :which-key "terminal")))

Pressing SPC ' will open a terminal. Pressing it again will hide it, but keep any processes running.

Small tweaks

As every time, we’ll do a few small tweaks:

Make Ctrl-u work like in Vim

Add the following to the :init block of use-package evil:

(setq evil-want-C-u-scroll t)

Comment lines

We want similar behaviour to commentary.vim and comment objects in/out with gc:

(use-package evil-nerd-commenter
  :general
  (general-nvmap
    "gc" 'evilnc-comment-operator))

Optimizing the garbage collector

We’ll use GCMH, “the Garbage Collector Magic Hack”, to minimize GC interference with user activity:

(use-package gcmh
  :demand
  :config
  (gcmh-mode 1))

Move this up to be the first package loaded after configuring use-package, to improve start-up time.

Don’t use ESC as a modifier

If you want to exit a menu, <escape> is the key of choice, esp. coming from Vim. Let’s match that behaviour:

(use-package emacs
  :init
	(global-set-key (kbd "<escape>") 'keyboard-escape-quit))

Conclusion

We now have everything we need to manage projects, navigate to files, run terminal commands and manage Git. Starting with this post, I’m using this very setup to edit this series.

In part 3, we’ll set up Tree-sitter and, if available, LSP for Rust, Go, TypeScript and Markdown.

Subscribe to the RSS Feed so you don’t miss the following parts, and let me know what you think!

For some things, precision matters, for others, it doesn’t and when trying to build yourself into a better version of yourself, exact data points don’t matter. All that matters, is the trend line.

Yearly Themes act as a signpost to give your year a direction—the idea is to keep them in mind when making decisions, no matter how small.

Looking back at 2023

My 2023 started with two themes:

Year of Business

In the past, most of my side projects were open-source and/or non-profit. I wanted to dive into figuring out if side projects with actual revenue was something I wanted to pursue.

Year of Adventure

I have a desk job and work from home and while I enjoy watching outdoor media, I have very little actual experience.

In the second half of 2023 I switched themes¹ to:

Year of Balance

My time is mostly divided into family, work, side projects and leisure. I want to be conscious of keeping a balance in my time invested.

I’m okay with how Year of Business and Year of Adventure went; I have a better idea of what it takes to turn a hobby project into something that generates revenue, and we’re leasing an orchard².

Year of Balance went really well, I’m now doing a better job allocating the time to what’s important to me.

Yearly Themes 2024

These are my Yearly Themes for next year:

Year of Fillilng The Gaps

I’ve made progress in many areas in my life over the last few years. I feel like that created “gaps” in some less interesting areas. This year, I want to invest in these areas to raise the overall base-line of myself.

Year of Fitness

After doing Year of Health at twice, I aim to focus on improving, instead of maintaining, my fitness. One metric for this could be my VO₂ max, which my Apple Watch conveniently automatically records for me³.

What’s yours?

Do you do New Year’s resolutions or Yearly Themes, or something entirely different? What do they look like? I’d love to hear from you.

In this part, we’ll install Emacs, set up sane defaults, packaging and do some basic UI tweaks to build a solid foundation.

Table of Contents

• Install Emacs
• Remove UI elements
• Configure the package manager
• Set sane defaults
• Become evil
• Set font and theme
• Add a nicer modeline
• Conclusion

Install Emacs

On macOS, everyone recommends Emacs Plus. For other systems, check out Doom’s Emacs & dependencies documentation.

We’re running this command:

brew reinstall emacs-plus \
  --with-savchenkovaleriy-big-sur-icon \
  --with-native-comp

And this is what it looks like when we start Emacs for the first time:

Remove UI elements

We want to remove everything but the text. To do so, we first create a file in $HOME/.emacs.d/init.el.

(tool-bar-mode -1)             ; Hide the outdated icons
(scroll-bar-mode -1)           ; Hide the always-visible scrollbar
(setq inhibit-splash-screen t) ; Remove the "Welcome to GNU Emacs" splash screen
(setq use-file-dialog nil)      ; Ask for textual confirmation instead of GUI

If you start Emacs now, you’ll see the GUI elements for a few milliseconds. Let’s fix that by adding these lines to $HOME/.emacs.d/early-init.el²:

(push '(menu-bar-lines . 0) default-frame-alist)
(push '(tool-bar-lines . 0) default-frame-alist)
(push '(vertical-scroll-bars) default-frame-alist)

This is better:

We’ll take care of the default scratch text and the C-h C-a hint down below.

Configure the package manager

We’ll be using straight.el for package management.

This is the installation code from the straight.el README:

(defvar bootstrap-version)
(let ((bootstrap-file
    (expand-file-name
      "straight/repos/straight.el/bootstrap.el"
      (or (bound-and-true-p straight-base-dir)
        user-emacs-directory)))
    (bootstrap-version 7))
  (unless (file-exists-p bootstrap-file)
    (with-current-buffer
      (url-retrieve-synchronously
       "https://raw.githubusercontent.com/radian-software/straight.el/develop/install.el"
       'silent 'inhibit-cookies)
    (goto-char (point-max))
    (eval-print-last-sexp)))
  (load bootstrap-file nil 'nomessage))

The docs also recommend adding this to our early-init.el to prevent package.el from loading:

(setq package-enable-at-startup nil)

Next we’ll install use-package for tidier specification and better performance:

(straight-use-package 'use-package)

Then we’ll make use-package use straight.el by default and always :defer t for lazy loading:

(setq straight-use-package-by-default t)
(setq use-package-always-defer t)

Set sane defaults

It’s good practice to specify Emacs-specific settings in a use-package block, even though this doesn’t change anything functionally. In the following, I’ll repeat the use-package emacs function, but you can, and probably should, move these all into a single use-package block.

Let’s start without the default scratch message and the text at the bottom saying “For information about GNU Emacs and the GNU system, type C-h C-a”:

(use-package emacs
  :init
  (setq initial-scratch-message nil)
  (defun display-startup-echo-area-message ()
    (message "")))

In confirmation dialogs, we want to be able to type y and n instead of having to spell the whole words:

(use-package emacs
  :init
  (defalias 'yes-or-no-p 'y-or-n-p))

Make everything use UTF-8:

(use-package emacs
  :init
  (set-charset-priority 'unicode)
  (setq locale-coding-system 'utf-8
        coding-system-for-read 'utf-8
        coding-system-for-write 'utf-8)
  (set-terminal-coding-system 'utf-8)
  (set-keyboard-coding-system 'utf-8)
  (set-selection-coding-system 'utf-8)
  (prefer-coding-system 'utf-8)
  (setq default-process-coding-system '(utf-8-unix . utf-8-unix)))

Use spaces, but configure tab-width for modes that use tabs (looking at you, Go):

(use-package emacs
  :init
  (setq-default indent-tabs-mode nil)
  (setq-default tab-width 2))

Map the correct keybindings for macOS:

(use-package emacs
  :init
	(when (eq system-type 'darwin)
		(setq mac-command-modifier 'super)
		(setq mac-option-modifier 'meta)
		(setq mac-control-modifier 'control)))

Become evil

I’m used to Vim keybindings and want to keep them, so we’ll use evil:

(use-package evil
  :demand ; No lazy loading
  :config
  (evil-mode 1))

Set font and theme

We’ll be using the PragmataPro typeface:

(use-package emacs
  :init
  (set-face-attribute 'default nil
    :font "PragmataPro Mono Liga"
    :height 160))

For themes, I can recommend the Doom Themes, we’ll be using doom-challenger-deep³:

(use-package doom-themes
  :demand
  :config
  (load-theme 'doom-challenger-deep t))

Finally, we want relative line numbers in prog mode:

(use-package emacs
  :init
  (defun ab/enable-line-numbers ()
    "Enable relative line numbers"
    (interactive)
    (display-line-numbers-mode)
    (setq display-line-numbers 'relative))
  (add-hook 'prog-mode-hook #'ab/enable-line-numbers))

Add a nicer modeline

We’ll install doom-modeline:

(use-package doom-modeline
  :ensure t
  :init (doom-modeline-mode 1))

For pretty icons, we need to install nerd-icons as well:

(use-package nerd-icons)

After restarting Emacs, run M-x nerd-icons-install-fonts (Option-x on macOS) to install the icon font.

And we’ll install Nyan Mode, a minor mode which shows a Nyan Cat (which is 12 years old at the point of writing this) in your modeline to indicate position in the open buffer.

(use-package nyan-mode
  :init
  (nyan-mode))

Conclusion

This is what looks like:

We have sane defaults, we can open a file with :e, navigate around and we have a nice color scheme⁴ and modeline. Here’s the the final init.el and early-init.el

In part 2, we’ll add a project manager, our own keybindings, the best Git TUI, a handy shortcut to restart Emacs and a ton of small tweaks.

Subscribe to the RSS Feed so you don’t miss the following parts, and let me know if I missed anything foundational!

Inspired by Kevin Kelly’s incredible 68 Bits of Unsolicited Advice¹, I collected bits of advice I’ve picked up over the years—mostly by people wiser than me.

Here they are, in no particular order:

• Communication is your most important skill, get good at it.
• Be kind first, be right later.²
• Don’t make your problems other people’s problems.
• Read more books.
• Help others succeed, and they’ll help you succeed in the long term.
• It’s only awkward if you make it awkward.
• When giving presents, the perceived value counts, not the actual value (this goes in both directions).
• Your vacation starts when you leave your house and ends when you’re back in your house.
• People care more about stories than facts.
• Find someone outside your bubble that you can talk to and make sure you’re both able to understand where the other comes from.
• Think of yourself as the person you want to be, not the person you are.³
• Trust is the most important ingredient when building a team.
• Always choose the long-term option to leverage the compound effect.³
• Create systems instead of chasing goals.³
• Don’t let your expenses rise as fast as your income.
• Make time for your brain to work without distractions to allow the mind to wander.⁴
• Less is more.⁵
• Always expand your knowledge, skills and network to be ready when opportunities arise.⁶
• Curious people are smart. Be curious.⁷
• Don’t be afraid to look stupid.⁸
• Keep a can-do mindset.⁹
• Don’t get discouraged because of existing work. Instead, try to find ways to put your own spin on it.
• It’s never as easy as it looks.¹⁰
• Perfection is the enemy of good.¹¹
• Good design requires as little cognitive overhead as possible to use.¹²
• When creating, take all the shortcuts you can to get a prototype which you can iterate on.
• Under-promise and over-deliver.
• Always do extra.¹³
• Keep a brag document.¹⁴
• Surround yourself with people who are passionate about their work.

Thoughts? I’d love to hear from you!

Yesterday you found this fly website about amateur radio, and you want to explore more—but how can you find related websites? Yahoo is slow and not really showing you what you’re looking for. Then you notice that this website is part of the “Amateur Radio Webring”. You click the arrow to the right and dive into another website about amateur radio.

You wake up.

The year is 2023. You can no longer get a Squeezit anywhere, you live under surveillance capitalism and the enshittification is ruining the web. You found this goofy personal website, and you’d like to browse similar ones. What do you do? Find the person on socials, look at who they’re following and check if they have a website?

It’s time to bring webrings back.

Introducing the Fire Chicken Webring; an invite-only webring for personal websites. You can explore this webring by going to the footer of this website and clicking on either arrow to navigate to another personal website.

If we’re friends, or I follow you anywhere, @ me and I’ll add you. If not, here’s some other modern webrings²: Hotline Webring, Sidebar.io Webring, a11y-webring.club, CS.Sjoy.lol, Fediring.net, and Appliance Ring.

Own a niche website? Why not start your own webring?

And, while it was really fun remembering projects I’ve long forgotten, there was no structure, and it was often difficult to figure out what a project did and what it looked like—some even missed crucial data. This made me think about how I want to archive my projects going forward.

Here is my new strategy:

Leave it online

If the project is on the web, doesn’t require maintenance and doesn’t cost you money, leave it online.

Occasionally, you’ll need to move to a different domain, for example when re-doing a website. When talking to Ollie about this, he told me that some people leave their old websites online at <year>.<domain> and I love that idea³.

You can look up old content and redirect links, so your URIs stay cool. And in ten years it’ll probably still be online.

Archive it

If you can’t leave it online, save it to your file system. You don’t have to go all Johnny.Decimal, but at least create a dedicated folder and subfolders for every year.

But instead of just copying your project to the archive folder and be done with it, consider these points to make life easier for your future self:

Make screenshots

Having a screenshot allows you to relive your memories more easily without going through the hassle of setting up a project. If you want to go the extra mile, do a screen recording showcasing your project—this has the bonus effect of hearing your voice from years ago, and it has more context.

Add a README

Explain what the project did, when it was created and abandoned, who contributed and how to get it running again.

Back up the database

Some of my projects are missing a database dump, so all the actual content is gone. Run sqldump or whatever export functionality your database supports and add it next to your files.

Keep generated assets

When using static site generators, add the folder containing the built HTML, CSS & JS to the archive. That way, all you have to do is run a static file server to be able to browse the complete website.

Save it to the Internet Archive

If you don’t own your platform (maybe you’re publishing to Substack or Notion), you can at least save your website to the Wayback Machine. I would also advise saving your content somewhere you control.

Show me yours

So that’s it, that’s my new project archival strategy.

How are you archiving your projects? Am I missing anything? Let me know.

These are mine:

Mail Client

HEY

Mail Server

HEY & Fastmail²

Notes

Tot & Obsidian

To-Do

Things

iPhone Photo Shooting

Camera.app

Photo Management

Photos.app

Calendar

Calendar.app synced with iCloud

Cloud File Storage

iCloud Drive

RSS

Reeder synced with Feedbin

Contacts

Contacts.app synced with iCloud

Browser

Safari

Chat

iMessage, WhatsApp, Signal

Bookmarks

Safari

Read It Later

n/a

Word Processing

Pages.app

Spreadsheets

Numbers.app

Presentations

Keynote.app

Shopping Lists

Grocery

Meal Planning

n/a

Budgeting and Personal Finance

YNAB

News

Lage der Nation³, New York Times

Music

Apple Music

Podcasts

Overcast

Password Management

1Password

Now there are a few categories I want to add myself:

Weather

CARROT

TV Show Tracker

CouchTimes

Terminal Emulator

iTerm

Code Editor

NeoVim

Photo Editor

Photomator

Since yesterday, this website has been powered by my own SSG¹. It’s not meant to be reusable, it’s just normal code—parsing and generating files for this specific website.

And oh boy do I love it.

Why??

When Vercel released Next.js 14 recently, some friends I’ve talked to were still on Next.js 12 and really felt the pressure to upgrade to not fall behind even more. This made me think about the longevity and robustness of my website, and so I decided I don’t want to depend on other people’s decisions and run after version upgrades I don’t care about.

And even if your content is Markdown and media, almost everything around it needs to be updated when switching frameworks—sometimes even when upgrading. When I used Astro before, I wanted to statically generate OG images and, after some research, managed to build it and even wrote an article explaining how. You lose all of this custom logic.

Plus, you get to choose your own stack. Want to write your content in AsciiDoc? No-one can stop you!

I know what you’re thinking, and you’re right, it’s way more work than using something that already exists. But it’s also so much more fun. You can do anything with this, and you don’t need to read documentation or try to understand other people’s architectural decisions—just start writing code!

Okay, tell me how you did it

After contemplating building something dynamic² for search without JavaScript, I decided to stay with a static site. It’s faster, and you don’t have to worry about security or stability. And of course, I chose the best programming language on the planet, Rust (my beloved). Wait, come back, this is not a Rust post!

A static site generator mostly needs to do five things:

1. Convert markdown to HTML
2. Render HTML templates
3. Compile CSS
4. Generate RSS feeds
5. Generate a sitemap

And of these, you might not even need the last three. Surely, your favorite programming language has a Markdown parser and a templating engine.

For Rust, I chose these crates³:

• comrak and gray_matter for parsing Markdown and the frontmatter
• maud for compile-time templates
• grass for SCSS compilation
• rss for (you guessed it) generating RSS feeds
• quick-xml for generating the sitemap

Once I got the tools I needed, I just started writing software. I built something to parse my content, something to render all the different templates I needed, something to generate the RSS, something to generate a sitemap and…that’s it, really!

And when it’s time to add OG images to this website, I can choose the best libraries and just build it.

What now?

I hope this article left you either validated that rolling your own is not worth it, and you want to keep using a framework, or interested to see what’s on the other side.

If you’re in the latter camp, you can check out the source of this website to get some inspiration. But most importantly: Choose a tech stack that excites you and have fun!

Most of the guides out there (including Vercel’s official OG Image Generation) use a function to generate the OG image dynamically. While there’s nothing wrong with that, I really wanted mine to be statically generated on build-time; it’s faster, cheaper and cooler.

Build your image

The first thing to do is figure out what your OG image should look like. We’re going to use Vercel’s Satori, a JavaScript library which can render a HTML tree as SVG. Vercel also has a great OG Image Playground, where you can play around and quickly get results.

Set the size to 1200×630px as that’s what Facebook recommends in their guidelines. Use Flexbox liberally and enable debug mode when figuring out the layout. A Complete Guide to Flexbox is a great resource to have at hand.

Create an Astro endpoint

Got a nice image built in the playground? Then let’s get started. Install Satori to generate the SVG and sharp to then convert it to PNG:

$ npm install satori sharp

Then create an endpoint, e.g. pages/og-image.png.ts with the following code:

import fs from "fs/promises";
import satori from "satori";
import sharp from "sharp";
import type { APIRoute } from "astro";

export const get: APIRoute = async function get({ params, request }) {
  const robotoData = await fs.readFile(
    "./public/fonts/roboto/Roboto-Regular.ttf"
  );

  const svg = await satori(
    {
      type: "h1",
      props: {
        children: "Hello world",
        style: {
          fontWeight: "bold",
        },
      },
    },
    {
      width: 1200,
      height: 630,
      fonts: [
        {
          name: "Roboto",
          data: robotoData,
          weight: "normal",
          style: "normal",
        },
      ],
    }
  );

  const png = await sharp(Buffer.from(svg)).png().toBuffer();

  return new Response(png, {
    headers: {
      "Content-Type": "image/png",
    },
  });
};

One drawback that you can already see in the code above is that Astro does not support TSX endpoints, so we’ll need to use React-elements-like objects.

You’ll also always need to provide a font because it’ll be embedded. I used Roboto in the example above, Inter or Open Sans are other solid free sans fonts (choose WOFF or TTF/OTF, WOFF2 is not supported).

Run astro dev and navigate to the endpoint (in our example :3000/og-image.png) to see the generated image.

Generate for each item in a collection

Once you have an image that you like in a function, you can create them in batch, for whole collections. Let’s assume you have a blog collection and your blog posts live at pages/blog/:slug/index.astro. Create a pages/blog/:slug/og-image.png.ts with your API route and the getStaticPaths function exported:

import { getCollection, getEntryBySlug } from "astro:content";

export async function getStaticPaths() {
  const posts = await getCollection("blog");
  return posts.map((post) => ({
    params: { slug: post.slug },
    props: post,
  }));
}

export const get: APIRoute = async function get({ params, request }) {
  // ...
};

If you now run astro build, you’ll see that it statically generates an OG image for every blog post you have on your site.

Handling images

Images (like fonts) need to be embedded into the SVG. The easiest way I found is using data urls by first reading the file to a Base64 string like this:

const myImageBase64 = (await fs.readFile("./public/my-image.png")).toString(
  "base64"
);

And then setting it as the backgroundImage or src property in Satori:

{
  type: "div",
  props: {
    style: {
      backgroundImage: `url('data:image/png;base64,${myImageBase64}')`,
    }
  }
}

Be aware that Satori does not support backgroundSize: cover, so if you have that use case, you’ll need to build it yourself with image-size and some math.

Set OG tags in HTML

Now the only thing left to do is link to your OG images in your <head>. There are two properties you’ll want to use for images: og:image and twitter:image.

<meta property="og:image" content="/blog/og-image.png" />
<meta property="twitter:image" content="/blog/og-image.png" />

Use dynamic paths on collections to automatically use the correct image. Check out the Open Graph protocol for more Open Graph meta extensions.

Further links & conclusion

If you want to see real, working code (I know I often do), check out the endpoint that powers the OG images of my book reviews: pages/books/[...slug]/og-image.png.ts. This is what it looks like: OG image of a book review.

Did I miss anything? Can this workflow be further improved? Drop me an email or @ me in the Fediverse, I’d love to hear from you.

Chances are that if you look at your inbox, it’s full of unsolicited marketing emails, log-in notifications or spam. Or you’re doing inbox zero and all that trash lives in your archive.

As everything else, email is subject (hah) to entropy. If you’re not careful, chaos will take over.

A different concept

As controversial as the company behind HEY is, the concept that they introduced with their mail app has fundamentally changed how I think about email. I adapted the part that resonated with me to my Fastmail account like this:

Inbox

This is where all emails sent by humans end up. That’s it.

Papertrail

Notifications, invoices, everything that you don’t want to delete but are not really interested in. This folder has about 1.6k unread emails right now. They’re not meant to be read, but if I need to look something up, I know where to look.

Newsfeed

I’m subscribed to over 20 newsletters and all of them end up in here. If I have time, I’ll read the newsletters and add the articles I want to read to Instapaper.

By the way, if you’re looking for something to add to your newsfeed, check out Arne’s Weekly.

The Setup

I’m using Fastmail with a custom domain and have aliases with rules for the different destinations, for example papertrail@example.org or newsfeed@example.org.

This way, if I sign up for a new service or subscribe to a newsletter, instead of having to adapt existing rules, I can use the proper email address and everything will go where it should.

This is not Fastmail specific, you can do the same with most providers. For example, if you have hikingfan@gmail.com, you could set a rule for hikingfan+papertrail@gmail.com and one for hikingfan+newsfeed@gmail.com and use those email addresses when signing up.

The human factor

If I look at my inbox, it’s a joy. Feedback to blog posts, articles and personal messages from people I care about. Sticking with this strategy made email about humans, not about machines.

I encourage you to try it!

If you have a different concept, feedback or ideas, please let me know.

Update (Mar 08, 2022): Multiple people have responded with their systems and questions (which I love, please keep doing that), some missed a way to track if a service “lost” their email address. If you use an alias, e.g. papertrail@example.org, you can use the + operator like this: papertrail+twitter@example.org. The sorting rule will be a bit more complicated, but you won’t have to adapt it every time you sign up for something.

The upside is that it gave me the opportunity to rethink my Plex setup. Hosting it at home is great for storage costs and control, but it’s hard to share with friends or access on the go, especially with a NATed IPv4, so I decided to move to the cloud.

Table of Contents

• Choosing a server and storage method
• Setting up NixOS
• Setting up storage
• Configuring Plex
  • Adding an Audiobooks Plugin
• Configuring Nginx
• How much does it cost?
• Wrapping up

Choosing a server and storage method

I chose Hetzner Cloud because I like their service, and they use green energy.

The biggest challenge was storage. Hetzner charges around €50/month for a 1 TB volume (others have comparable pricing).

But then my friend Eric told me about rclone and its ability to mount blob storage (which is cheap) as a virtual disk. That means Plex sees all files as if they were actually there and if it tries to read a file, it’s downloaded on demand if it’s not cached already.

Armed with this knowledge, I started setting up the server.

Setting up NixOS

NixOS is a declarative and reproducible operating system. You have a configuration file in /etc/nixos/configuration.nix that defines your installed applications, configuration and system setup. And if you mess up, you can always roll back.

The first I did was creating a server on Hetzner with any distribution (I went width a CPX11 and Ubuntu) and then following the instructions on the install scripts for Hetzner Cloud.

If you follow along, make sure to choose a server with at least 40 GB of disk space.

After booting into NixOS, I changed the root password by running passwd and upgraded NixOS (see Upgrading NixOS). If you want to further secure your NixOS installation, Christine Dodrill has a great guide called Paranoid NixOS Setup.

Setting up storage

I decided to go with Backblaze B2 as I have used it before, it’s cheaper than S3, and I don’t support Amazon. If you want to use something else, rclone supports a lot of providers.

After creating a bucket for the media, I created an Application Key and made note of the keyID and applicationKey.

Then I added the following lines to my Nix configuration at /etc/nixos/configuration.nix to install rclone and create a /etc/rclone/rclone.conf for the bucket:

environment.systemPackages = [ pkgs.rclone ];

environment.etc = {
  "rclone/rclone.conf" = {
    text = ''
      [b2]
      type = b2
      account = <keyID>
      key = <applicationKey>
      hard_delete = true
      versions = false
    '';
    mode = "0644";
  };
};

If you follow along, make sure to replace <keyID> and <applicationKey>.

By the way, NixOS comes with nano preinstalled, so if you want a real editor, you can get it with the following command:

$ nix-shell -p vim

For the disk mount, I created a Systemd service that mounts the bucket on start and automatically starts on boot.

systemd.services.plex_media = {
  enable = true;
  description = "Mount media dir";
  wantedBy = ["multi-user.target"];
  serviceConfig = {
    ExecStartPre = "/run/current-system/sw/bin/mkdir -p /mnt/media";
    ExecStart = ''
      ${pkgs.rclone}/bin/rclone mount 'b2:<bucket name>/' /mnt/media \
        --config=/etc/rclone/rclone.conf \
        --allow-other \
        --allow-non-empty \
        --log-level=INFO \
        --buffer-size=50M \
        --drive-acknowledge-abuse=true \
        --no-modtime \
        --vfs-cache-mode full \
        --vfs-cache-max-size 20G \
        --vfs-read-chunk-size=32M \
        --vfs-read-chunk-size-limit=256M
    '';
    ExecStop = "/run/wrappers/bin/fusermount -u /mnt/media";
    Type = "notify";
    Restart = "always";
    RestartSec = "10s";
    Environment = ["PATH=${pkgs.fuse}/bin:$PATH"];
  };
};

If you follow along, make sure to replace <bucket name>.

The --vfs-* arguments configure the virtual file system. I only have 40 GB local disk space, so I set the cache size to 20 GB (using --vfs-cache-max-size).

I then ran nixos-rebuild switch to apply the configuration, uploaded some data to the bucket and listed /mnt/media to make sure everything works.

Configuring Plex

NixOS has a predefined service for Plex, which I used like this:

nixpkgs.config.allowUnfree = true; # Plex is unfree

services.plex = {
  enable = true;
  dataDir = "/var/lib/plex";
  openFirewall = true;
  user = "plex";
  group = "plex";
};

With this configuration, Nix will open the correct ports in the firewall, create a user called plex with a group also called plex and install the Plex Media Server with the configuration in /var/lib/plex.

Adding an Audiobooks Plugin

I wanted to use the Audiobooks.bundle metadata agent for better matching, so I added this to the let-section at the top of plex.nix:

let
  audiobooksPlugin = pkgs.stdenv.mkDerivation {
    name = "Audiobooks.bundle";
    src = pkgs.fetchurl {
      url = https://github.com/macr0dev/Audiobooks.bundle/archive/9b1de6b66cd8fe11c7d27623d8579f43df9f8b86.zip;
      sha256 = "539492e3b06fca2ceb5f0cb6c5e47462d38019317b242f6f74d55c3b2d5f6e1d";
    };
    buildInputs = [ pkgs.unzip ];
    installPhase = "mkdir -p $out; cp -R * $out/";
  };
in
  # ...

That fetches the commit 9b1de6b of the audiobooks plugin and makes sure that the SHA256 is correct.

Then I told Plex to use this plugin like this:

services.plex.managePlugins = true;
services.plex.extraPlugins = [audiobooksPlugin];

If you’re following along and get an error which says services.plex.managePlugins no longer has an effect, remove that line.

At this point, after running nixos-rebuild switch again, I was able to access the Plex interface at https://<domain or ip>:32400.

Plex needs an initial configuration, but only allows it if it’s coming from a local connection. One way to do this is an SSH tunnel, which I opened like this:

$ ssh -L 32400:localhost:32400 user@domain-or-ip

Then I opened http://localhost:32400/web in my local browser and set up Plex.

Configuring Nginx

I wanted a nice domain with HTTPS on 443 (instead of HTTP on port 32400), so I set up Nginx with Let’s Encrypt next.

The first thing I did was setting openFirewall to false in the Plex configuration. Then I allowed port 80 and 443 for HTTP and HTTPS and all the Plex ports except for 32400 as we want to proxy the web interface through Nginx.

services.plex = {
  openFirewall = false;
  # ...
};

networking.firewall = {
  allowedTCPPorts = [ 3005 8324 32469 80 443 ];
  allowedUDPPorts = [ 1900 5353 32410 32412 32413 32414 ];
};

Then I configured ACME:

security.acme.acceptTerms = true;
security.acme.defaults.email = "<your email>";

The default provider is Let’s Encrypt, you can find their terms of service here: Policy and Legal Repository.

Now it was time to add the Nginx service. I used recommended settings and only PFS-enabled ciphers with AES256. As this proxies Plex requests, I forwarded some headers as well. Here’s the code:

services.nginx = {
  enable = true;

  # Recommended settings
  recommendedGzipSettings = true;
  recommendedOptimisation = true;
  recommendedProxySettings = true;
  recommendedTlsSettings = true;

  # Only allow PFS-enabled ciphers with AES256
  sslCiphers = "AES256+EECDH:AES256+EDH:!aNULL";

  virtualHosts = {
    "<your domain>" = {
      forceSSL = true;
      enableACME = true;
      extraConfig = ''
        # Some players don't reopen a socket and playback stops totally instead of resuming after an extended pause
        send_timeout 100m;
        # Plex headers
        proxy_set_header X-Plex-Client-Identifier $http_x_plex_client_identifier;
        proxy_set_header X-Plex-Device $http_x_plex_device;
        proxy_set_header X-Plex-Device-Name $http_x_plex_device_name;
        proxy_set_header X-Plex-Platform $http_x_plex_platform;
        proxy_set_header X-Plex-Platform-Version $http_x_plex_platform_version;
        proxy_set_header X-Plex-Product $http_x_plex_product;
        proxy_set_header X-Plex-Token $http_x_plex_token;
        proxy_set_header X-Plex-Version $http_x_plex_version;
        proxy_set_header X-Plex-Nocache $http_x_plex_nocache;
        proxy_set_header X-Plex-Provides $http_x_plex_provides;
        proxy_set_header X-Plex-Device-Vendor $http_x_plex_device_vendor;
        proxy_set_header X-Plex-Model $http_x_plex_model;
        # Buffering off send to the client as soon as the data is received from Plex.
        proxy_redirect off;
        proxy_buffering off;
      '';
      locations."/" = {
        proxyPass = "http://localhost:32400";
        proxyWebsockets = true;
      };
    };
  };
};

If you’re following along, make sure to replace <your domain>.

To secure things even further, I set some headers for every request:

services.nginx.commonHttpConfig = ''
  # Add HSTS header with preloading to HTTPS requests.
  # Adding this header to HTTP requests is discouraged
  map $scheme $hsts_header {
      https   "max-age=31536000; includeSubdomains; preload";
  }
  add_header Strict-Transport-Security $hsts_header;
  # Enable CSP for your services.
  #add_header Content-Security-Policy "script-src 'self'; object-src 'none'; base-uri 'none';" always;
  # Minimize information leaked to other domains
  add_header 'Referrer-Policy' 'origin-when-cross-origin';
  # Disable embedding as a frame
  add_header X-Frame-Options DENY;
  # Prevent injection of code in other mime types (XSS Attacks)
  add_header X-Content-Type-Options nosniff;
  # Enable XSS protection of the browser.
  # May be unnecessary when CSP is configured properly (see above)
  add_header X-XSS-Protection "1; mode=block";
'';

Finally, I ran nixos-rebuild switch one last time to apply the configuration. Then I opened https://my-domain in a browser and started creating Plex libraries.

How much does it cost?

The CPX11 costs €4,75/month with backups enabled, B2 costs $0.005/GB/month storage + $0.01/GB downloaded. Storage pricing depends heavily on the amount of media stored and the amount of media downloaded. I pay around €10/month for my setup.

Wrapping up

All that’s left to do now is further configure NixOS to set a hostname, timezone, installed packages like htop and enabling Automatic Upgrades.

In case that’s useful for you, here is the configuration.nix from when I tested this blog post.

If you discover an issue or have a question, please don’t hesitate to let me know, I’m more than happy to help!

This is the first post in a series and this one is about technologies and tooling.

Technologies

I’m writing a native app in Swift and UIKit.

The decision against using React Native or any other third-party mobile technology was mostly because native feels better (to me), is often faster and gets new features first. Using React Native would have sped up the development process a lot (mostly because I know that technology and my Swift/UIKit knowledge is a little rusty), but I wanted it to be native and I’m in no rush.

The project was initially set up to use SwiftUI as it seems to be the future of iOS development, but I quickly hit some limits. More experienced iOS-Developers would have probably found a way around it, but I feel more at home with UIKit and it’s a stable, battle-tested technology.

Tooling

Spending most of my working time writing Go I’ve come to value automatic formatting and good linting. For that I’m using SwiftFormat and SwiftLint, both with the default configuration. You can configure Xcode to automatically run those when building, which I highly recommend.

For dependency management I’ve started using Carthage, mostly because that was the defacto-standard when I last wrote an app. But I’ve switched over to Swift Package Manager because it has great Xcode-integration and is generally stable.

Most iOS developers have experienced their share of .xcodeproj-related merge conflicts or weird diffs. Generally I prefer all files in my project to be human-readable. For that I’ve used XcodeGen, which allows you to define your project in a simple project.yml and ignore your project with these lines in you .gitignore:

*.xcodeproj
!*.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved

That means that on CI, new clones or changes in project.yml you need to install XcodeGen and run xcodegen generate to set it up, but for me that’s worth it.

Talking about CI, I’ve set up Fastlane for linting and testing. It allows easy definition of rules and automatic TestFlight or even AppStore submissions (including taking screenshots), which is awesome. It also has a ton of plugins.

Since Travis CI costs a small fortune for private repositories I’ve migrated away and now use GitHub Actions. It took some time to configure it right, so here’s my .github/workflows/ci.yml, hoping it’s useful for some people:

name: CI

on: [push]

jobs:
  lint-and-test:
    runs-on: macos-latest
    steps:
      - run: sudo xcode-select -s /Applications/Xcode_11.5.app/Contents/Developer
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Cache Bundler
        uses: actions/cache@v2
        with:
          path: vendor/bundle
          key: $-gems-$
          restore-keys: |
            $-gems-
      - name: Cache Swift Package Manager
        uses: actions/cache@v2
        with:
          path: .build
          key: $-spm-$
          restore-keys: |
            $-spm-
      - name: Install dependencies
        run: |
          bundle update --bundler
          bundle install
          brew install xcodegen swiftlint swiftformat
      - name: Generate Xcode project
        run: xcodegen generate
      - name: Lint
        run: bundle exec fastlane lint
      - name: Test
        run: bundle exec fastlane test

That’s my setup so far. If you have any questions or suggestions, hit me up.

On the Cortex podcast (which inspired the whole series), CGP Grey and Myke Hurley sometimes talk about their checklists; whole projects that can be invoked by a tap if needed. These lists are for things that are important to get right, but you do them not often enough to remember every step, examples are an Airport or a YouTube checklist. They mostly use OmniFocus for this, which can export and import projects as TaskPaper.

When thinking about this, I found more and more usecases for checklists and really wanted to have this set up, but I personally can’t deal with the way some things work in OmniFocus. I use Things for my todos, which doesn’t support TaskPaper, but supports its own JSON format. I didn’t want to store my checklists in a proprietary format like this Things-specific JSON, I wanted TaskPaper.

Then I remembered playing around with Scriptable, which could execute JavaScript on iOS with native bindings to UI, Clipboard, etc. – this sounded perfect for my usecase, so I started writing a script to convert TaskPaper to Things JSON, which will be the core of my checklist flow.

The Script

I ended up writing a 300-line script (it’s on GitHub) with only enough functionality to fit my needs (e.g. it only supports tabbed indentation and may break on the slightest deviation).

Since I wanted to run this script from Apples Shortcuts app, I needed to use a hack for input/output data. Many apps face these problems and use the clipboard (e.g. AutoSleep), so that’s what I did as well. If you run the script in the Scriptable app, it will get the clipboard contents expecting text in TaskPaper format, convert it to the Things JSON and copy it.

Here’s how the @tag and @attr(value) work:

• @due(2019-02-09) would be setting the due date
• @today will set the task or project to start today
• @start(2019-02-09) will set the task or project to start on the given date (in YYYY-MM-DD format)
• @due(2019-02-09) will set the due-date of a task or project to the given date
• Anything else without a value (like @foo) will be a Things tag (this tag has to exist beforehand)
• Anything else with a value will be a Things attribute, see the reference for attributes

The Shortcut

I wanted one shortcut to start all checklists from. Sadly you cannot get a directory listing from an iCloud folder, so for now if I add a new checklist, I have to add the filename to the List at the top.

This is what the Shortcut looks like:

After a checklist was chosen, the shortcut gets the file from iCloud Drive (it has to be in the Shortcuts application folder to be accessible). Then it copies the file contents to the Clipboard and runs the script (the Scriptable action should appear automatically in your Shortcuts app once you created it). After that, it retrieves the Things JSON from the clipboard, url-encodes it and opens Things with its URL scheme.

Conclusion

This shortcut-scriptable-combination helps to use checklists in Things from anywhere while storing them in a highly-compatible format. I really love to find more use cases for checklists. Do you use checklists? What usecases do you have? I’d love to hear from you.

In this post I describe how I created an Automator application, which will record the latest episode of a Spotify podcast, fill out metadata like title and description and generate a file for metadata for a podcast client to subscribe to.

Preparation

If you want to follow along, you need a machine with macOS and the following installed:

• Spotify
• Audio Hijack ($77, sorry)
• jq
• Golang

You also need a bit of knowledge in Apple Script, Bash scripting and JSON and be comfortable in a terminal.

Create Audio Hijack Session

Audio Hijack is an application that can do complex audio pipelines, often used for recording podcasts or live streaming. We use this to capture the output of Spotify to a file. Audio Hijack has a concept of sessions, meaning various saved pipelines.

To prepare things, start Audio Hijack and create a new session based on the Application Audio template. This post assumes you only have on session. If you have multiple, make sure it’s at the first position. In the session, select Spotify as Application and change the Recorder to 128 kbps (or whatever you prefer). I recommend disabling the Output Device, but it’s helpful if you want to debug something. After saving, it should look similar to this:

Spotify Credentials

We need various metadata about the latest show, like title, Spotify uri or duration. To get those, we use the Spotify Web API. You need to create a Spotify App by going to the developer dashboard and create a client id. Fill out the fields and you’ll get a Client ID and a Client Secret.

Spotify ID

We also need the Spotify ID of the podcast you want to mirror. To get that, click the three dots on the podcast page in Spotify, select Share and Copy Spotify URI. The uri looks something like spotify:show:abcdef, where abcdef is your Spotify ID.

Folder Setup

Lastly, there needs to be a folder where the podcast lives. We use a tool in our last step to generate the RSS feed, so we can subscribe to the podcast from our favourite podcast app. Fot the tool to work, we need to have a podcast.toml similar to this example, but without the [[episodes]] parts in our folder. There also needs to be an empty subfolder called dist/.

Let’s do this

1. Create an Automator Project

Open the Automator app and choose New Document. Then click on Application to build a .app file you can launch later.

2. Get Latest Episode Metadata

We need the following attributes of the latest episode:

• Spotify URI
• Duration
• Name
• Description
• Release date

We use Bash to get the data, so drag a new Run Shell Script onto your workflow with the following contents:

#!/bin/bash

# Exit the script if any command returns an error code.
set -e

# Define variables
PODCAST_PATH='/path/to/podcast/folder'
SPOTIFY_ID='abcdef'
AUTH_HEADER='abcdef123456' # base64 encoded `<client id>:<client secret>`

# Get Spotify access token
TOKEN_RES=$(curl -s -X POST 'https://accounts.spotify.com/api/token' \
	-H Authorization:"Basic $AUTH_HEADER" --data 'grant_type=client_credentials')
ACCESS_TOKEN=$(echo $TOKEN_RES | /usr/local/bin/jq -r .access_token)

# Get show
SHOW_RES=$(curl -s "https://api.spotify.com/v1/shows/$SPOTIFY_ID" \
	-H Authorization:"Bearer $ACCESS_TOKEN")
# Get first (latest) item
ITEM=$(echo "$SHOW_RES" | /usr/local/bin/jq '.episodes.items[0]')
# Get release date
RELEASE_DATE=$(echo "$ITEM" | /usr/local/bin/jq -r .release_date)

# If the episode already exists, exit early
if [ -f "$PODCAST_PATH/dist/episodes/$RELEASE_DATE.mp3" ]; then
	(>&2 echo "Episode already exists")
	exit 1
fi

# Get and echo metadata, each line will be a parameter to the next action
# in the Automator workflow.
echo "$ITEM" | /usr/local/bin/jq -r .uri
echo "$ITEM" | /usr/local/bin/jq -r .duration_ms
echo "$ITEM" | /usr/local/bin/jq -r .name
echo "$ITEM" | /usr/local/bin/jq -r .description
echo "$RELEASE_DATE"

We need the metadata again later, so save it in a variable by dragging the Set value of variable below the Bash action and giving it a name (e.g. Metadata).

3. Start the Recording Process

Now we get to the messy part. Drag a Run AppleScript action to the end of the workflow and paste the following code.

Read the comments (lines starting with --) to know what it’s doing. Make sure the checkbox next to Automator in System Settings → Security & Privacy → Accessibility) is checked, otherwise you will get an error and the keyboard shortcuts won’t work.

on run {input, parameters}
	set uri to item 1 of input
	set duration_ms to item 2 of input
	set title to item 3 of input
	set description to item 4 of input
	set release_date to item 5 of input

	-- Prepare Spotify
	tell application "Spotify"
		-- Start spotify
		activate

		-- Start playing our episode
		play track uri

		-- Make sure we start at 0s
		-- If we are at 0s, this will skip to the previous track
		delay 1
		set episode_id to id of current track
		previous track
		pause
		delay 1
		if episode_id is not id of current track then
			play track uri
			pause
		end if
	end tell

	-- Start recording
	tell application "Audio Hijack"
		-- Start Audio Hijack
		activate

		tell application "System Events"
			-- CMD + 1 to open Sessions
			keystroke "1" using command down
			-- Arrow down to select the first one
			key code 124
			-- Open session
			keystroke "o" using command down
			-- Start recording
			keystroke "r" using command down
		end tell
	end tell

	-- Play track
	tell application "Spotify"
		-- Bring to foreground
		activate

		-- Start playing our track again
		play track uri

		-- Wait the length of our episode
		delay duration_ms / 1000

		-- Press pause
		pause

		-- Quit spotify
		quit
	end tell

	tell application "Audio Hijack"
		-- Bring Audio Hijack to foreground
		activate

		tell application "System Events"
			-- Stop recording
			delay 1
			keystroke "r" using command down
		end tell

		-- Quit Audio Hijack
		quit
	end tell
end run

4. Save Release Date to it’s Own Variable

We use the publish date of the episode as filename, so we need to get this first. Drag the action Get Value of Variable into your workflow and select the Metadata variable (or whatever you called it). After that, drag a Run AppleScript action at the end with the following contents.

on run {input, parameters}
	-- Return the fifth parameter of our Metadata variable,
	-- which is the release date
	return item 5 of input
end run

Set the variable ReleaseDate using a Set Value of Variable action.

5. Move File to Destination

Use a Find Finder items action to search the destination folder of your Audio Hijack session for files with all of the following attributes:

• Kind is music
• Date created is today

Then drag a Run AppleScript with the following contents into your workflow to get the first item (which will be the latest).

on run {input, parameters}
	# Get latest item
	return item 1 of input
end run

After that, rename the file using Rename Finder Items. Choose Name Single Item and set Basename only to ReleaseDate.

Then move the renamed file to podcast-folder/dist/episodes/ with a Move Finder Items action.

6. Metadata and Deployment

Now that we have our recording, we have to generate the RSS feed with the metadata so podcast clients can display the episodes in a nice list. After that we upload both the feed and the episode.

Use Get Value of Variable to get the Metadata variable again.

To generate the feed.xml, we append the metadata of an episode to a simple TOML file. I wrote a small tool for this, which you can find here: toml-podcast. After generating the feed.xml, we use the AWS CLI deploy it and the newly recorded episode to an AWS S3 bucket.

Add a Run Shell Script action with the following contents:

#!/bin/bash

set -e

PODCAST_PATH='/path/to/podcast/folder'
URI="$2"
DURATION_MS="$3"
TITLE="$4"
# For description, we have to escape double quotes ("), because the TOML strings
# use double quotes as well.
# If the TOML is invalid, toml-podcast will crash.
DESCRIPTION=$(echo "$5" | sed "s/\"/\\\\\"/g")
RELEASE_DATE="$6"

# Add episode metadat to the end to podcast.toml
cat << EOT >> "$PODCAST_PATH/podcast.toml"
[[episodes]]
title="$TITLE"
file="$RELEASE_DATE.mp3"
date="$RELEASE_DATE"
description="$DESCRIPTION"

EOT

# Build feed.xml using toml-pdocast
cd $PODCAST_PATH
/Users/arnebahlo/Developer/go/bin/toml-podcast
# Your $GOBIN will look different, find out your path by typing `which toml-podcast`
# in your terminal

# Set AWS credentials (replace with your real credentials)
export AWS_ACCESS_KEY_ID="ABCDEF"
export AWS_SECRET_ACCESS_KEY="GHIJKL"

# Upload episodes + feed.xml
cd dist/
/usr/local/bin/aws s3 sync episodes s3://fuf-mirror/episodes
/usr/local/bin/aws s3 cp --cache-control max-age=600 feed.xml s3://fuf-mirror/feed.xml

I use a Cache-Control header because I serve the podcast via a CloudFront, the AWS CDN and I want the feed.xml to be at most 10 minutes old.

Conclusion

Now recording the latest episode of your favourite Spotify podcast takes one click. If you have a spare Mac you could even start it automatically matching the release cycle of the podcast.

Since this is such a good idea, I naturally defined my own yearly themes for 2019. One of those is called Year of Automation, which to me means automating everything I can in my personal as well as professional life.

I will try and documente all bigger efforts (you don’t want to see all my email rules) in this blog series.

We use Jest for running the tests, which is running on Node.js. As we found out in the process, Node.js uses ICU (International Components for Unicode) for its i18n support and, if not otherwise specified, only contains English ICU data.

The reason it worked on our local machines was, that they had node installed with full ICU data (Homebrew, for example, installs all by default), but the Docker image we used on CI didn’t.

Solution

To have full ICU data available, you can either

• compile the node binary with the flag --with-intl=full-icu (see Options for building Node.js), or
• install the full-icu package and use an environment variable (NODE_ICU_DATA=node_modules/full-icu) or a command-line flag (--icu-data-dir=node_modules/full-icu) to tell node where to find the data (see Providing ICU data at runtime).

Since it was only failing on CI, we updated the build script to install the full-icu package and export the environment variable. Also, in case you wondered, all major browsers support the Intl-API, according to Can I use.

Conclusion

If you use any i18n features in your JavaScript application, make sure to include a basic test to be sure all locales you need are supported.

A good architect maximises the number of decisions not made

— Robert C. Martin in Clean Architecture

Most web services I worked with use a MVC-style architecture, with a handlers package and, if at all, a repository package. While this may be great for small services, the handlers package introduces a big problem: It mixes transport logic with business logic. This makes refactoring hard (imagine switching your HTTP framework) and therefore forces you to make decisions about these kind of things before even starting the project. So when I started a new project recently, I decided to use the hexagonal architecture (aka Ports and Adapters) and so far I’m really happy.

What I like about it

Here’s what I like about it:

All dependencies point inward

All outer layers like transport, storage or logging depend on the business logic, but never the other way around. The business logic is agnostic of any other layer, it doesn’t care, how it’s served or how data is stored, it’s pure code. This makes changing it super simple.

You can defer decisions

You can defer many decisions about technologies used until you really need them. You could, for example, start out with an inmem package for storage and only decide which database to use when you really need persistence.

Refactorings are simple

Since everything is contained in it’s domain, refactoring the transport package, for example, is refactoring only transport code. There is pure separation of concerns and everything has a clear place.

Testing business logic is simple

Since you only have pure code without layer dependencies, you can easily inject an inmem package as storage for example. No need for mocking complex database structs, which cost time.

Why a hexagon

It actually doesn’t matter how many sides the shape has. The point is, that there are many. The center represents the business logic and every side represents a port into or out of our application (that’s why it’s also called Ports and Adapters).

A real-world example

For this post let’s assume that we’re building an API to manage an inventory of some sort – it’s still similar to the application I’m building. You should be able to list all items in the inventory and logged-in users should have basic CRUD access.

To set things up, I created these packages:

• user: Domain logic for user management (login, logout, validate)
• inventory: Domain logic for inventory (list, create, read, update, delete)
• inmem: In-memory storage for user and inventory
• http: HTTP transport logic, does de-/encoding and request handling

The user and inventory packages define an interface for the storage struct. This way we can inject any struct that implements that interface and keep the separation of concerns.

Here’s how our main.go would look like, simplified:

package main

import (
	"net/http"

	transport "github.com/bahlo/inventory/http"
	"github.com/bahlo/inventory/inmem"
	"github.com/bahlo/inventory/inventory"
	"github.com/bahlo/inventory/user"
)

func main() {
	userStorage := inmem.NewUserStorage()
	userService := user.NewService(userStorage)
	http.Handle("/v1/user", transport.UserHandler(userService))

	inventoryStorage := inmem.NewInventoryStorage()
	inventoryService := inventory.NewService(inventoryStorage)
	http.Handle("/v1/inventory", transport.InventoryHandler(inventoryService))

	http.ListenAndServe(":8080", nil)
}

Problems

In real-world applications, we always have to make compromises and fight for clear separation of concerns. This is a list of problems I ran into while building the application.

Authentication

Let’s say we want to implement a token-based authentication and we need to protect some routes of the inventory service. Where should we get the token-validation function from? Getting the user service via our NewService constructor would result in unnecessary dependencies. What I ended up doing was a http.Guard(userService) function, which returned a http middleware (func (next http.Handler) http.Handler) which parses the token and validates with userService.UserForToken. The middleware is then passed into the transport.InventoryHandler and wrapped around methods that needed protection. This way, there are no new dependencies.

Model decorators

Another problem are Go tags (read up). Let’s say we need some for transport (e.g. json:"id") and database (e.g. db:"first_name"), but they’re attached to the model, which lies in the domain logic. A fix would be having the model structs duplicated in the other packages with the needed tags, but this introduces a lot of duplicate code and unnecessary complexity, so I decided to leave it as-is right now until I found a better solution.

Conclusion

I’m really happy with my application and I don’t think I’ll go back to MVC-style applications any time soon. I encourage you to try and build a service using a hexagonal architecture and share your experience – doesn’t have to be Go. If you want to read more on hexagonal architecture, I recommend checking out go-kit. There is also a GopherCon 2018 talk by Matt King, here is the script until the videos are up. Also if you have comments or suggestions, hit me up 🤙.

But wait

Sublime Text does have a <name>.sublime-project, which holds configuration for the curent project. Why doesn’t Vim has something like that?

Just do it yourself

It’s not hard, paste the following lines anywhere in your .vimrc:

if filereadable(expand(".vim-project"))
  source .vim-project
endif

You can now create a .vim-project-file anywhere you want and just write stuff in it like in your .vimrc, this is one of mine:

autocmd VimEnter * NERDTree
autocmd VimEnter * Tagbar

Note: You may want to close Vim automatically after all windows but NERDTree are closed, see the FAQs for that.

Just deploy to your own server via Git.

Step one

If you haven’t already done this, run rake setup_github_pages in your local Octopress repository and give it any valid GitHub url.

Step two

Set up a bare Git repository on your server to push to

mkdir -p ~/projects/octopress.git
cd ~/projects/octopress.git
git init --bare # Related: http://git-scm.com/book/ch4-2.html

Step two and a half

Create a post-receive on your server in ~/projects/octopress.git/hooks/ and give yourself execute permissions with chmod u+x post-receive.

#!/bin/bash
# You already know that you'll have to change the paths
git --work-tree=$HOME/html/octopress --git-dir=$HOME/projects/octopress.git checkout -f

Step three

Back in your local Octopress installation.

cd _deploy
git remote set-url origin user@domain.com:projects/octopress.git
git pull -u origin master # Where master is the branch you set in your Rakefile as deploy_branch, defaults to master

And you’re set. If you run into any trouble, let me know.