Björn Friedrichs' Blog

PDF Interpolator: Replacing text in templated PDFs with spreadsheet data

Wed, 25 Feb 2026 19:35:00 GMT

I recently built PDF Interpolator , a desktop application that replaces text in PDF files using data from spreadsheets. It started with a simple idea, if you have a templated PDF (a pricing list or invoice) you should be able to automatically fill it using a spreadsheet. Map the columns, hit process, and you get a new PDF with the numbers swapped in. All of it runs locally on your machine. I purposefully wanted to avoid cloud processing to ensure that no data leaves your computer, but more on that in a bit.

My previous work on PDFBlaze was invaluable to understanding the requirements and issues for this project. PDFs are a notoriously complex format, so it helped a lot that for this project as I already had a good understanding of the underlying structure and how to manipulate it. Just for reference the PDF version 1.7 specification is over 500 pages long and was released almost 20 years ago, the more recent version 2.0 (2017) clocks in at almost 1000 pages.

The why: PDF design and data sensitivity

I built this for a relative who needed it for their business, and their use case turned out to be quite interesting. Because of current market forces they had to recalculate their pricing sheets many times in relatively short intervals. Unfortunately this forced them to spend a lot of time painstakingly updating hundreds of individual prices to create catered PDFs for different clients. The manual work involved in updating prices, regenerating documents, and making sure everything looked right was eating into their time. They aren’t tech-illiterate at all, but it’s not their primary job to sit at a computer and it felt like a large burden to spend their energy on this extra task. Additionally, the industry or at least their target audience, comes from a pool of clientele that happens to care a lot about the details. Now, this is mostly concerning the product, but in such a sector you often require to be very conscious about the image, brand and design you project. As such my relative wanted to use their own design tools (e.g. InDesign, Illustrator, whatever they were comfortable with) to create beautifully laid-out PDFs. Then they just wanted to sub in the prices. A boring or generic template that looks like a generated document was not really an option.

Generally this kind of tool is hard to come by, because it’s a niche use case, and also it actually involves some pretty complex technical hurdles to overcome. There are some alternatives floating around online, but all of questionable quality, pricing structures, or data security. A web-based PDF generator or a service that processes documents in the cloud was somewhat problematic anyway, for a lot of businesses their pricing data is the anchor of their business. Sending it anywhere, even to a quote-unquote trusted third party, was out of the question. To me a primary requirement was that everything had to run locally and no data to ever leave their computer.

That’s what PDF Interpolator does. You pick a spreadsheet, map the source column (the placeholder text in the PDF) to the target column (the value from your sheet), select your PDF, choose an output location, and process. The app preserves the original layout, fonts, and formatting. It just swaps the text. Fully offline, no account required, no telemetry.

The nitty gritty: what I had to deal with under the hood

As mentioned earlier, PDFs are notoriously messy to work with. I already built PDFBlaze before as a online-service for templated PDFs. This meant I had at least a rough idea of what I was getting into. PDFBlaze was sadly not suited in this case as since it is run by me the data protection issue was less of a concern, but the templating engine requires the user to create the whole thing in my online editor, which as mentioned before wasn’t really an option. Thus, the technical challenges to overcome for this app were the following:

Fonts and encodings

PDFs don’t store text as plain strings. They store sequences of bytes that map to glyphs via font encodings. And it gets worse: different fonts use different encodings, sometimes the same “base font” can be encoded as multiple fonts with different encodings. WinAnsiEncoding, MacRomanEncoding, custom encodings defined in the font dictionary — you have to handle all of them. When you replace text, you need to encode your replacement string back into the same byte representation the PDF expects, otherwise the glyphs won’t render correctly. I had to build a font registry that maps Unicode characters to the correct byte codes for each font, and when a character doesn’t exist in the current font (e.g. a particular case is the euro sign in a font that only has ASCII), I fall back to other fonts in the same family.

Content streams: strings, arrays and split bytes

PDF content streams are essentially sequences of drawing operations. Text is rendered inside BT … ET blocks. The tricky part is that text can be specified in multiple ways: as a single string with Tj, or as an array with TJ where each element can be a string or a spacing adjustment. Sometimes that array is split across multiple operations. Sometimes strings are hex-encoded <414243>, sometimes they’re encoded in octal notation \041\042\043 and sometimes they’re literal (ABC) with escape sequences.

I had to build a tokenizer that tracks byte positions so I could surgically replace only the text blocks that changed, leaving all the graphics, paths, and images untouched. One wrong splice and the whole page corrupts.

A particularly challenging session was when I discovered that Adobe Acrobat Reader does not like certain representations of text. A hex-encoded string like <414243> should be printed with the Tj operator, since if TJ is used a reader expects the text to be a sequence of strings and spacing adjustments. Interestingly, every reader I tested did not mind the missing spacings except for Acrobat Reader.

And because PDF is a binary-ish format, content streams can be split at what feel like random byte boundaries. This means that I had to ensure that re-writing the content stream does not break the PDF structure and that the resulting PDF is still valid. I also didn’t want to unnecessarily bloat the PDF, so I had to be careful about removing unused content after the replacement and re-writing content streams with the appropriate compression filters.

Number formatting: German vs English

Spreadsheets, at least when read through libraries like xlsx, unfortunately seem to return numbers in English format without internationalisation: comma as thousands separator, period as decimal. So 1,234.56 means one thousand and change. In German locale it’s the opposite: 1.234,56. My relative’s business runs in Germany. Just passing through the values, a price like 1,234.56 is basically nonsensical to a German reader. I had to add locale-aware number formatting that detects the system language and converts between formats when loading from the spreadsheet. It’s one of those things you don’t think about until you’re debugging why all the prices are wrong.

Putting it together

The pipeline works like this: load the PDF, parse each page’s content stream with position tracking, extract font dictionaries and build character mappings, decode text blocks to Unicode, perform replacements (with font fallback when needed), re-encode to bytes, and patch only the modified BT … ET blocks back into the stream. Everything else stays byte-for-byte identical. The result is a PDF that renders the same in Adobe Reader and other finicky viewers, with all the original structure preserved.

It was a satisfying project to work on. Solving real problems for someone you know, and learning a lot about a format that most people happily treat as a black box. If you have a similar use case for templated PDFs, local data, design-sensitive output, PDF Interpolator might be worth a look. It’s available for Windows, macOS, and Linux.

AI is amazing, AI is scary

Sun, 04 Jan 2026 11:51:00 GMT

… and AI has fundamentally changed the way I think about what it means to be a software engineer.

The last few years, but 2025 in particular, has been a whirlwind when it comes to the capabilities and skills AIs can offer. Ranging from almost instantly answering complex questions, all the way to making full plans and executing them autonomously. Where at first it was easy to discard their nature as being simple predictive parrots, we are now starting to realise that when designed correctly AI agents are much more capable. Increasing context windows, reiterating plan structures and having feedback loops within tasks, dare I say it, suddenly AI feels like it’s „thinking“ much more so than ever before.

From a software perspective, tools like Claude Code or Cursor are capable of implementing, modifying and debugging reasonably complex issues, if provided with enough context. They have become much better at understanding surrounding code structures, plus adhering to workspace code guidelines and patterns.

Automated tooling is now wide scale available, where some GitHub repositories launch automatic agents to create PRs when an issue is created, then a separate automated agent will review the PR and add notes. Sometimes this can go back and forth multiple times before a human even looks at the PR.

There is many examples of these AI guided development workflows, two I find very inspiring is Charlie Marsh‘s „uv“ and another Jarred Sumner‘s „Bun“ (now owned by Anthropic). These are not small hobby projects, they are massively popular tools which have to be carefully worked on and these people are succeeding by doing so with AI.

After over a decade as a software engineer, nothing has shifted my view on how development works so drastically as these recent advancements of AI. In the past, new tools (e.g. for debugging, observability, code structuring, etc.) were released all the time and were worth investing the time to learn, but nothing compares to the effect that AI has and will have. In my opinion AI is a tool a software engineer will have to learn to use. You will not be able to avoid it. It is able, unequivocally, to speed up a lot of tasks for me already. If you haven’t yet, my plea is, go and try it out. Learn how to use it effectively, learn what it is able to do, and crucially what it isn’t. Find workflows that speed you up in the right places.

To non-technical and leading staff: Make sure your engineers have the resources available to learn and use these tools. This doesn’t mean you have to burn through thousands of pounds and millions of tokens, even just baseline access to something like Claude or Cursor are a massive deal. Most engineers I know are naturally inclined to improve their skillset, they want to ride the wave of new technologies and advancements. Locking them out of these tools not only means that you’re likely slowing down development, but also realistically are frustrating your staff with a feeling of being left behind by the industry.

Now, the big question is: Where does that leave the role of a software engineer? The most important part at play here is the human factor. Someone needs to understand the domain, someone needs to understand the product requirements, someone needs to translate them to machine requirements and someone needs to validate and manually correct issues. The real skill of an engineer isn’t writing the code itself, it’s being able to deeply understand a problem and reflecting it in a performant, secure and available system. AI doesn’t really replace any core capabilities here, it just massively enhances the speed by which they can be delivered. A good engineer will be able to leverage these tools and continue to deliver high-quality code at a faster rate, allowing them to focus on more or multiple issues at a time. A bad engineer will use it as a crutch, without reviewing the automated work. Which inevitably will start to muddle the carefully crafted systems, creating tech debt and incrementally adding unsolveable riddles.

It really wouldn’t surprise me if by the end of 2026 the core competencies of skilled developers in high velocity teams will have shifted. Where previously their time was mostly spent writing code by themselves, it will be mostly consumed by planning, reviewing, and correcting code written by AI.

I find this thought equally unnerving and exciting. I spent years learning and improving my craft, seeing it upended like this leaves me with a very strange feeling. That being said, I choose to view this change positively. After all, progress is exciting, and learning is exciting too (I promise!). Being part of the first wave of engineers that get to explore this new way of building on technology feels empowering, I just need to make sure it’s not leaving me behind. At the end of the day, I would see it as a failure of myself if a machine was able to replace me, instead of me being able to drive the machine to do what I want it to do.

Multi-row, dynamically truncated text width with ellipsis in pure CSS

Wed, 27 Aug 2025 21:36:00 GMT

I ran into this annoying CSS problem that neither AI nor the internet seemed to be able to produce a sensible solution for. I don’t think it’s a hard problem nor but it did take me a little while to wrap my head around it. I’m now just documenting the issue for prosperity.

The basic issue boils down to wanting a two-row layout with text where both rows have a variable length (or width). In the layout one of the rows should dictate the width of the container, while the other row truncates to it’s size with ellipses.

TL;DR:

Title: An overly long but truncated title
Content: Any length content

Example:

An overly long but truncated title

Any length content

Code:

 <div
  style={{
    display: "inline-flex",
    flexDirection: "column",
  }}
>
  <div style={{ display: "flex" }}>
    <div
      style={{
        width: 0,
        flexGrow: 1,
        overflow: "hidden",
        textOverflow: "ellipsis",
        whiteSpace: "nowrap",
      }}
    >
      A long but truncated title
    </div>
  </div>
  <div>
    Any length content
  </div>
</div>

Explanation

The important components of this setup are:

Using inline-flex on the outer container to make it shrink to fit the content of the row that controls the size. This means that whichever row is controlling the size will determine the overall width of the container and thus truncate the other row.
Wrapping the truncated view in a flex container that the truncated text can grow into. This will allow the text to take up the available space without exceeding the container’s width.
Setting the truncated text to width: 0 and flex-grow: 1 to make it grow to the size of the interim flex container, but it can never exceed further than the overall container.

It creates a rather elegant solution where there is no need to calculate any sizes, and it’s adaptable to any content size. It also automatically animates rather nicely if the width-controlling row has a transition.

The playground

In the following example the content is editable, give it a go and see how it behaves:

An overly long but truncated title

Edit me

Additionally, if the width of the lower row is constrained, it will also work nicely:

An overly long but truncated title

Content that is much longer and will break because the container is restricted in width

As mentioned before, if the width-controlling row is animated, it will also animate the truncation of the other row:

An overly long but truncated title

Any length content

Toggle width

Lastly, it also works great if you have multiple components of varying widths that need to sitting next to each other in one row (this was my use case)

An overly long but truncated title

First title

An overly long but truncated title

Second title

An overly long but truncated title

Third title

An overly long but truncated title

Fourth title

Microsoft Teams silent login flow in 2025

Fri, 01 Aug 2025 17:00:00 GMT

This post outlines the implementation of a silent login flow for Microsoft Teams. At SimplyDo we had previously implemented a solution for this and it worked, after some changes from Microsoft there is now a slightly more elegant solution available.

Sidenote: in all fairnesss, most of our prior issues stemmed from the proactive messages required by Teams applications, but this is also much more straightforward nowadays. If you’re interested in (or struggling with) implementing proactive notifications feel free to send me a message on one of my socials.

You can find our process for the previous solution in our team blog post . You will find that the process is actually still extremely similar, especially in regards to Steps 1 & 2. However, since then Microsoft has made some changes to their recommended Teams packages, so this updated approach should be more in line with the setup you can expect when creating a new Teams app in 2025.

Either way, the following should guide you through an example of how to implement a silent login flow in Microsoft Teams using the Teams SDK and the Microsoft Graph API. The example will cover both the frontend and backend parts of the flow.

The MS Teams frontend

The flow begins in the Teams environment itself. What we are looking for is a way to utilise the users authentication context of Teams itself to silently authenticate the user in our app.

For this we use the following versions of the Teams SDK, as of writing these are the latest versions available.

  "@microsoft/teams-js": "^2.36.0",
  "@microsoft/teamsfx": "^4.0.0",
  "@microsoft/teamsfx-react": "^4.0.2",

Technically only @microsoft/teams-js is required for this, but I assume most people will look at this in context of a React app. However, as you can see in their code the teamsfx packages actually just a wrapper around an authentication request around to make the ssoToken available, so this should always be available as long as app.initialize() has been called. References: Wrapping the internal call and calling the underlying authentication

If you open a Teams app in the Desktop or web client you will have the useTeamsUserCredential hook available to you. This hook will allow you to access the Teams user credentials and initiate the login flow. Crucially, you have access to the ssoToken which is the auth token that validates the user in Teams. This token is what we will use to authenticate the user in our app.

The setup should look something like this:

import { useTeamsUserCredential } from "@microsoft/teamsfx-react"

const Component = () => {
  const teamsCredentials = useTeamsUserCredential({
    initiateLoginEndpoint: import.meta.env.VITE_START_LOGIN_PAGE_URL,
    clientId: import.meta.env.VITE_CLIENT_ID,
  })
  const [currentUser, setCurrentUser] = useState(null)
  const [userLoginStatus, setUserLoginStatus] = useState("loading")

  const { loading, teamsUserCredential } = teamsCredentials
  if (loading) {
    return <div>Loading...</div>
  }

  useEffect(() => {
    if (userLoginStatus !== "loading") {
      return
    }
    setUserLoginStatus("initialising")

    // If we already have a token, we can skip the login flow
    const apiToken = localStorage.getItem("token")
    if (apiToken) {
      api.registerToken(apiToken)
      const user = api.getUser()
      setCurrentUser(user)

      setUserLoginStatus("loggedIn")
      return
    }

    const initialiseLogin = async () => {
      // Ensure the ssoToken is available
      const userInfo = await teamsUserCredential?.getUserInfo()
      if (!userInfo) {
        setUserLoginStatus("loginFailed")
        return
      }

      // Read the silent id token from the TeamsFx context
      const ssoToken = teamsUserCredential?.ssoToken?.token
      const response = await api.loginWithTeams({ ssoToken })

      api.registerToken(response.token)
      localStorage.setItem("token", response.token)
      setCurrentUser(response.user)

      setUserLoginStatus("loggedIn")
    }
    initialiseLogin()
  }, [teamsUserCredential])
}

Here we first call the .getUserInfo() method to ensure that the user is logged in and we have access to the ssoToken. This token is then passed to our backend API to authenticate the user. Once the request succeeds we can use this information set a session token in our api which allows us to further communicate with our backend without having to re-authenticate through the ssoToken in the future.

The backend

In the backend we will verify the ssoToken and use it to authenticate the user. Before we do so we need to check what our audience for the token is. This can be done by checking the aud claim in the token. You should never parse this directly from the token, but it will be stable across requests. If you are not deployed yet you can also check your Azure AD app registration to see what the audience is set to.

The following image shows where you would find the App audience in the App registration. Let’s assume it’s set to api://<your-app-id> for now.

Now that we know the audience, we can verify the token and extract the user information from it. The token is signed by Microsoft and we can verify it using the public keys provided by Microsoft.

Please be aware that in this example we will request user information from the Microsoft Graph API using the https://graph.microsoft.com/.default scope. This scope grants access to any delegated permissions configured for the application, but fails if there isn’t any. You will need to ensure that the app registration has the necessary permissions granted to resolve the fields of the following Graph API call. The configured permissions can be found in the app registration under “API permissions”.

In these examples I will use a few dummy functions to illustrate how you could use the data in this flow, but you will need to implement your own logic to handle the user data and authentication flow in your app.

Python TypeScript

For Python we use the requests and pyjwt libraries to verify the token. The msal library is used to acquire an access token on behalf of the user if the user is not found in our database.

  import os
  import requests
  import jwt
  from msal import ConfidentialClientApplication

  # Microsoft maintains a rotating set of public keys to verify the JWT signature.
  # Reference:
  # https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens#validate-the-signature
  config_response = requests.get(
      "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
      timeout=5,
  )
  config_data = config_response.json()
  jwks_url = config_data.get("jwks_uri")

  jwks_response = requests.get(jwks_url, timeout=5)
  public_keys = {
      key["kid"]: jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps(key))
      for key in jwks_response.json().get("keys", [])
  }

  # The api handler as invoked by api.loginWithTeams on the frontend
  def login_from_teams_token(data):
      teams_token = data["ssoToken"]
      token_headers = jwt.get_unverified_header(teams_token)
      public_key = public_keys[token_headers["kid"]]

      decoded_token = jwt.decode(
          teams_token,
          key=public_key,
          algorithms=["RS256"],
          audience="api://<your-app-id>",
      )

      tid = decoded_token["tid"]

      # The oid is the users unique identifier in Azure AD
      # This can be None or empty in certain scenarios, so handle it accordingly
      oid = decoded_token.get("oid")
      if oid:
          # Find the user and return it, otherwise we have to provision a new user
          user = get_user_by_oid(oid)
          if user:
              return {
                "token": create_api_token(user),
                "user": user,
              }

      # MICROSOFT_APP_ID and MICROSOFT_APP_SECRET are the app registration credentials
      msal_client = ConfidentialClientApplication(
          client_id=os.environ["MICROSOFT_APP_ID"],
          client_credential=os.environ["MICROSOFT_APP_SECRET"],
          authority=f"https://login.microsoftonline.com/{tid}",
      )

      access_data = msal_client.acquire_token_on_behalf_of(
          user_assertion=teams_token,
          scopes=["https://graph.microsoft.com/.default"],
      )

      if "access_token" not in access_data:
          raise Exception("Failed to acquire access token")

      # Example of how the token can be used to create a new user
      resp = requests.get(
          f"https://graph.microsoft.com/v1.0/me?$select=id,givenName,mail",
          headers={
              "Authorization": f"Bearer {access_data['access_token']}"
          },
      )
      user_data = resp.json()
      user = create_user(
          oid=oid,
          email=user_data.get("mail"),
          first_name=user_data.get("givenName"),
      )

      return {
        "token": create_api_token(user),
        "user": user,
      }

Disclaimer: I chucked the Python example into AI to generate a TypeScript version. It may not be perfect (or working for that matter), but it should give you an idea.

  import axios from "axios";
  import jwt, { JwtHeader, JwtPayload } from "jsonwebtoken";
  import jwkToPem from "jwk-to-pem";
  import { ConfidentialClientApplication } from "@azure/msal-node";

  const configUrl = "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration";

  let publicKeys: Record<string, string> = {};

  async function fetchPublicKeys(): Promise<void> {
    const configResponse = await axios.get(configUrl, { timeout: 5000 });
    const jwksUri = configResponse.data.jwks_uri;

    const jwksResponse = await axios.get(jwksUri, { timeout: 5000 });
    const keys = jwksResponse.data.keys || [];

    publicKeys = keys.reduce((acc: Record<string, string>, key: any) => {
      acc[key.kid] = jwkToPem(key);
      return acc;
    }, {});
  }

  interface TeamsLoginData {
    ssoToken: string;
  }

  // The api handler as invoked by api.loginWithTeams on the frontend
  export async function loginFromTeamsToken(data: TeamsLoginData): Promise<any> {
    const teamsToken = data.ssoToken;

    if (!Object.keys(publicKeys).length) {
      await fetchPublicKeys();
    }

    const tokenHeaders = jwt.decode(teamsToken, { complete: true })?.header as JwtHeader;
    const kid = tokenHeaders?.kid;

    if (!kid || !publicKeys[kid]) {
      throw new Error("Invalid token: Key ID not found");
    }

    const publicKey = publicKeys[kid];

    const decodedToken = jwt.verify(teamsToken, publicKey, {
      algorithms: ["RS256"],
      audience: "api://<your-app-id>",
    }) as JwtPayload;

    const tid = decodedToken["tid"];
    const oid = decodedToken["oid"];


    // The oid is the users unique identifier in Azure AD
    // This can be null or empty in certain scenarios, so handle it accordingly
    if (oid) {
      const user = await getUserByOid(oid);
      if (user) {
        return { user, token: createApiToken(user)};
      }
    }

    // MICROSOFT_APP_ID and MICROSOFT_APP_SECRET are the app registration credentials
    const msalClient = new ConfidentialClientApplication({
      auth: {
        clientId: process.env.MICROSOFT_APP_ID!,
        clientSecret: process.env.MICROSOFT_APP_SECRET!,
        authority: `https://login.microsoftonline.com/${tid}`,
      },
    });

    const result = await msalClient.acquireTokenOnBehalfOf({
      oboAssertion: teamsToken,
      scopes: ["https://graph.microsoft.com/.default"],
    });

    if (!result || !result.accessToken) {
      throw new Error("Failed to acquire access token");
    }

    // Example of how the token can be used to create a new user
    const graphResponse = await axios.get("https://graph.microsoft.com/v1.0/me?$select=id,givenName,mail", {
      headers: {
        Authorization: `Bearer ${result.accessToken}`,
      },
    });

    const userData = graphResponse.data;

    const user = await createUser({
      oid,
      email: userData.mail,
      first_name: userData.givenName,
    });

    return { user, token: createApiToken(user)};
  }

Nothing here is terribly complicated, but it does require some understanding of how the Teams SDK works and how to verify the JWT tokens. The key takeaway is that you can use the Teams user credentials to silently authenticate the user in your app without requiring them to log in again.

Using UUID v4 in Expo (native + web)

Fri, 25 Jul 2025 20:00:00 GMT

Today I ran into a problem with generating v4 UUIDs in an Expo app. The uuid package is a popular choice for generating UUIDs, but it doesn’t work out of the box in Expo apps because it relies on Node.js’s crypto module. Specifically the getRandomValues function, which is not available in the Expo environment.

There seem to be workaround such as the react-native-uuid package which re-implements the random number generator using Math.random() which I’m not a huge fan of.

There’s also react-native-get-random-values which is a polyfill for the crypto.getRandomValues function, but it has not been updated in months (years) and users seem to have multiple issues with it. I didn’t want to outsource a core functionality to a potentially flakey dependency (which in fairness it may not be, but I didn’t want to deal with the headache if it was).

Instead I decided to rely on the expo-crypto package which is a part of the Expo SDK and provides a reliable way to generate random values. uuid’s v4 generation implementation allows you to pass in a custom random number generator, so we can use expo-crypto’s getRandomValues function to generate the random bytes needed for the UUID.

It may have been possible to somehow polyfill the crypto.getRandomValues function in a way that would work with the uuid package, but I didn’t want to spend time on that. Especially not because from prior experience I know how much of a pain it is when Expo, metro or something else in the process changes down the line. Instead, I opted for a straightforward solution that simply re-exports it’s own v4 function.

It’s a simple and elegant solution that works on both native and web platforms. Here’s how you can implement it in your Expo app, just remember to import v4 from your own file instead of the uuid package directly:

// uuid.ts

import { getRandomValues } from "expo-crypto"
import { v4 as uuidv4 } from "uuid"

export const v4 = () => {
  const random = new Uint8Array(16)
  getRandomValues(random)

  return uuidv4({
    random,
  })
}

Multiple services in Tailscale with Traefik + Docker

Thu, 19 Jun 2025 20:00:00 GMT

Preamble

I finally went through the process of upgrading my home server from a Raspberry Pi to a more powerful machine. This was mainly motivated by me wanting to use Immich but my Raspberry Pi 4 was not powerful enough to run it alongside the other services (such as Vaultwarden and Home Assistant ).

I had already been using Tailscale to access my Vaultwarden and Home Assistant instances, but I had just been running them on different ports on the same machine, Vaultwarden in particular also required a Caddy reverse proxy to handle the TLS certificates. As part of this upgrade I aimed to make my setup a bit neater and instead of routing everything through different ports, I wanted to use subdomains for each service.

Traefik was not strictly necessary as a choice for this, as Caddy should be able to handle this as well, but I was curious about it and wanted to try it out. It also seemed to have good integration with Docker and Tailscale built in.

I ended up upgrading to a Beelink S12 as I wanted something small and quiet, but powerful enough to run multiple services. It didn’t need to be a complete powerhouse, but I just didn’t want to have to worry about it for a bit at least. And the price was just right to not break the bank. I ended up ditching the default Windows install and just went with Ubuntu Server as this is what I was most comfortable with.

The nitty gritty

In theory the setup is quite simple, install Tailscale, Traefik and Docker, then configure Traefik to route requests to the correct Docker containers based on the subdomain. Then use the built-in Tailscale resolver in Traefik to handle the certificates for me automagically.

In practice however this is not quite as simple. I assume most people who have used Tailscale are aware of this but Tailscale does not support multiple subdomains per device. This means assigning uniquely routable subdomains to each service is not possible. One option would be to use a single subdomain and then route requests based on the path, but while this is more recently possible with Vaultwarden it is not possible with Home Assistant . It also apparently can cause all kinds of issues with WebSockets and other parts of the services that expect them to be on their own subdomain.

Instead after some searching around and reading through the Traefik documentation I realised I could just route DNS requests to subdomains of my choosing to my Tailscale network, then sign those subdomains using Let's Encrypt . I will be using AWS Route53 for this, but this video shows how it can be achieve with Cloudflare as well: https://www.youtube.com/watch?v=Vt4PDUXB_fg .

I will redact my actual setup in this example, let’s just assume:

Your tailnet is tail-net.ts.net
Your internal Tailscale device IP is 100.XXX.YYY.ZZZ
You have a domain example.com that you own and can configure DNS for.

The first step is to set up your desired DNS subdomains in your DNS provider to point at your tailnet device address. To allow all services to be forwarded to Tailscale I set up a wildcard A record for *.athome.example.com pointing to 100.XXX.YYY.ZZZ. This way any subdomain request will be routed to the Tailscale device. Any subdomain works here, I just chose the namespace athome to free up the other subdomains for other purposes.

EDIT: This section previously referred to using a CNAME record to point the subdomains to the Tailscale device instead of it’s IP. However, it turns out there is an issue with routing on Windows and Android devices when doing so. Therefore, this is amended to using an A record now.

Then Traefik can be configured to handle the requests for these subdomains and route them to the correct Docker containers based on the subdomain. The configuration is quite straightforward, you just need to set up the entry points, providers and the certificates resolvers.

Traefik - Config Traefik - Docker Compose Route53 IAM Policy

# traefik.yml

entryPoints:
  http:
    address: ":80"

https:
  address: ":443"

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false

certificatesResolvers:
  myresolver:
    acme:
      storage: "/letsencrypt/acme.json"
      email: email@example.com
      dnsChallenge:
        provider: "route53"
        resolvers:
          - "8.8.8.8"

The Traefik configuration is quite standard, a couple things to note:

resolvers are set to use Google’s DNS servers, this is required to properly resolve the DNS challenges while having configured the CNAME redirect.
provider is set to route53, this is the AWS Route53 DNS provider. You can use any supported DNS provider here, but I chose Route53 as I already use it for my domain.
Using the docker provider to automatically route Docker containers that are started within the Traefik network.

# docker-compose.yml

services:
  traefik:
    image: traefik:latest
    restart: unless-stopped
    container_name: traefik
    ports:
      - 80:80
      - 443:443
      - 8080:8080
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./traefik.yml:/etc/traefik/traefik.yml:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock:ro
      - ./letsencrypt:/letsencrypt
    networks:
      - traefik
    environment:
      - "AWS_ACCESS_KEY_ID=XXXX"
      - "AWS_SECRET_ACCESS_KEY=XXXX"
      - "AWS_HOSTED_ZONE_ID=XXXX"
      - "AWS_REGION=XXXX"
      - "LEGO_DISABLE_CNAME_SUPPORT=true"

networks:
  traefik:
    external: true

The Docker Compose configuration is also quite standard, a couple things to note:

The AWS specific credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_HOSTED_ZONE_ID, AWS_REGION) only need to be supplied if you are using Route53
The LEGO_DISABLE_CNAME_SUPPORT environment variable is set to true. Basically, because we are forwarding all subdomains to the Tailscale device, by default Traefik (or rather it’s dependency LEGO) will start following the CNAME records to set up the certificates. However, this will cause it to follow the CNAME to the Tailscale device and then try to set up the certificate there, which will fail as your tailnet address is not routable from the public internet. This is no longer necessary when using an A instead of a CNAME record for the subdomains.
I use an external Docker network called traefik to allow Traefik to communicate with the other containers. You can create this network with the following command: docker network create traefik

This policy is only relevant if you are using AWS Route53 as your DNS provider.

It allows Traefik to manage the DNS records for the subdomains you want to use. You will need to create an IAM user with this policy and provide the credentials in the Docker Compose file.

Make sure to replace <YOUR_HOSTED_ZONE_ID> with your actual Route53 hosted zone ID.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "route53:GetChange",
                "route53:ListHostedZonesByName"
            ],
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
                "route53:ChangeResourceRecordSets",
                "route53:ListResourceRecordSets"
            ],
            "Resource": "arn:aws:route53:::hostedzone/<YOUR_HOSTED_ZONE_ID>"
        }
    ]
}

With this configuration in place, Traefik will automatically handle the DNS challenges for the subdomains you have set up in your DNS provider. It will request certificates from Let’s Encrypt and store them in the /letsencrypt/acme.json file. This file should be mounted as a volume in the Traefik container to persist the certificates across restarts, otherwise you may have issues with Let’s Encrypt rate limits.

Below are example Docker Compose files that I use on my instances. Personally, I prefer to disable Traefik’s automatic service detection by setting exposedByDefault: false, which means I need to explicitly add traefik.enable=true to the labels of any service I want to expose.

Since Traefik can route traffic to containers within its network, it’s not necessary to expose service ports to the host machine. However, if a service runs on a port other than :80, you must specify the port in the Traefik labels, as Traefik cannot detect it automatically. For example, Home Assistant runs on port 8123 by default, so you need to add the label traefik.http.services.homeassistant.loadbalancer.server.port=8123 (see the full config below). If you bind multiple networks to a service – e.g, if you have other services in the same compose file that you don’t want to expose to the Traefik network – you can use the traefik.docker.network label to specify which network Traefik should use to route traffic to the service. So, in my case I would add traefik.docker.network=traefik to every service that I specify more than one network for.

Vaultwarden Home Assistant

Setting up a service is straightforward:

Configure a rule for the domain you want to use for Vaultwarden, e.g. vaultwarden.athome.example.com.
Set the TLS resolver to the one you configured in Traefik, e.g. myresolver.
Set the DOMAIN environment variable in Vaultwarden to match the domain in your Traefik rule.

# docker-compose.yml

services:
  vaultwarden:
    image: vaultwarden/server:latest
    restart: always
    container_name: vaultwarden
    volumes:
      - ./vw-data:/data
    environment:
      - DOMAIN=https://vaultwarden.athome.example.com
      - ADMIN_TOKEN=XXXXXXXX
      - WEBSOCKET_ENABLED=true
      - INVITATIONS_ALLOWED=false
      - SIGNUPS_ALLOWED=false # Set to true if resetting
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.vaultwarden.rule=Host(`vaultwarden.athome.example.com`)"
      - "traefik.http.routers.vaultwarden.tls.certresolver=myresolver"
    networks:
      - traefik

networks:
  traefik:
    external: true

# docker-compose.yml

services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - ./ha-data/config:/config # Retain home assistant config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    privileged: true
    networks:
      - traefik
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.homeassistant.rule=Host(`homeassistant.athome.example.com`)"
      - "traefik.http.routers.homeassistant.tls.certresolver=myresolver"
      - "traefik.http.services.homeassistant.loadbalancer.server.port=8123"


networks:
  traefik:
    external: true

Once the services are ready and started, Traefik will automatically pick up any changes using the docker provider. You can now visit your services using the subdomains you configured, e.g. https://vaultwarden.athome.example.com and https://homeassistant.athome.example.com. Just as a hint, it can take a few minutes sometimes for the DNS challenge to complete and for the certificates to be issued, so don’t panic if it doesn’t work immediately.

Conclusion

This setup now allows me to finally separate my personal services into their own subdomains. I wish it was easier to achieve using just Tailscale but I am fine with the relatively small compromise of having to route the requests through a DNS provider.

Maybe this helps someone else who is trying to achieve a similar setup. If you have any questions or suggestions, feel free to reach out to me on Mastodon or Bluesky .

Building my own (virtual) bookshelf

Sun, 09 Mar 2025 20:00:00 GMT

A couple of years ago I made a snap decision to buy a Kindle and it is now the main reason for me getting back into reading regularly. I think it is a fantastic device that lets me read any book I want, be it at home with the light turned off or on the go. I genuinely cannot recommend it enough.

All that praise out of the way, while the Kindle is great it presents me with one small but annoying issue. Unlike with collecting real, physical books you never get the satisfaction of seeing your collection grow. All your books are solely contained on your small electronic screen. To offset this a little bit I already like logging books I have read (or plan to read) on Goodreads . For that purpose, I think it is a great platform and it lets me keep track of what I have read and what I want to read next. Comparatively though that is really not the same as having a physical bookshelf.

For a while now I had this idea that it would be cool to somehow pass this list of books into a 3D renderer to at least get some visual sense of what my collection would look like. Recently I finally sat down and actually considered what I would like this to look like.

My goals were:

A 3D representation of the books I had read
Ideally it should just be able to load a list of books from a JSON/XML file
It should be interactive, so I can click on a book and get more information about it
I wanted it to be embeddable so that other people may be able to also use it in the future.

Upon starting the investigation for this project I was immediately disheartened when I saw that Goodreads does not offer a public API (anymore) . I browsed their website for a bit and considered scraping for a while, but I really did want this project to be mostly standalone, without regular needs to configure a scraping service. I noticed that, almost hidden on the bottom of the page, every list actually has an RSS feed.

This was perfect, the RSS feed not only included all the necessary data such as titles and links, it also has links to nice thumbnails of the book covers. That meant I was able to just parse the list of books from that RSS feed without any need for scraping or otherwise.

To render the bookshelf and books themselves I am using Three.js . Using Three.js allowed me to relatively quickly iterate on a simple 3D scene that served me well. It also comes with some nice drag and zoom controls out of the box.

So below you can see the result: A virtual bookshelf filled with the books I have read since I started using Goodreads. You can move the scene via drag and zoom in and out with the mouse wheel. Holding shift or control while dragging will also move the whole scene to get a better view. Hovering over a book shows a bit of extra information in the sidebar, and by clicking it you get a little highlight on the current book.

Field of view

Books per shelf

Divider every

Horizontal rotation

Vertical rotation

Only Read

You can find a full-screen version here here.

There are also a few tweaks that can be configured within the canvas itself, such as the number of books per shelf, the count of dividers, or the initial angle when viewing the scene.

These tweaks are also configurable via the URL, so when embedding it yourself (see below) you can pass in your own parameters to adjust the scene to your liking.

booksPerShelf - The amount of books per shelf
dividerEvery - How many books should be separated by a divider
horiRotation - The initial horizontal rotation of the scene (in degrees)
vertRotation - The initial vertical rotation of the scene (in degrees)
onlyRead - Only show books that have been marked read, 1 for true, 0 for false (default: 1)
url - The URL to the RSS feed (default: the one from my Goodreads)

You can check out the editable version here

Overall, I am quite happy with the result. It was a fun little project that I could finish in a few days and it was nice to see the books I have read in a different light. I hope you enjoy it too.

P.S: The site is set up so that you can embed it as an iframe with your set of books. To do so you will have to host your own Goodreads .xml because the iframe will have to fetch the data. Goodreads does obviously not allow wildcard CORS requests, so you will need to host (or forward) the file yourself and configure a CORS origin for my site Access-Control-Allow-Origin: "bjoernf.com". The iframe will then load and parse your own list.

An example embed would be:

<iframe src="https://bjoernf.com/fun/bookshelf?url=https://your-own-xml-url.com" width="100%" height="500px"></iframe>

Pdf Mini: Images with transparency

Tue, 19 Nov 2024 20:00:00 GMT

I have released a first version of my new project https://pdfblaze.com . It’s an ultrafast, convenient way to generate PDFs by using custom templates and dynamic values.

As part of creating this application I had to learn a lot about the PDF and TrueType font specifications. Some of the information I needed was quite arduous to find, to say the least.. So, I want to make a mini series of blog posts where I intend to tackle one specific issue I had encountered in each post.

Without further ado, let’s get into it.

Images with transparency in PDFs

The long and short of it: the main issue with transparency in images is that the PDF specification does not really consider the alpha channel part of the pixel data itself. Rather we need to separate the RGB pixel data from the alpha data and then overlay them using an SMask.

To explain this in more detail the best I can do is show you an example of how to specify an image with such an alpha mask. A regular image will usually be described by an XObject dictionary something like this:

1 0 obj <<
/Type /XObject
/Subtype /Image
/Width 3
/Height 3
/ColorSpace /DeviceRGB
/BitsPerComponent 8
/Filter [ /ASCIIHexDecode ]
>>
stream
ff0000 00ff00 0000ff 0000ff ff0000 00ff00 ff0000 0000ff ff0000
endstream

(note: I leave out some properties like \Length in these examples. While PDF viewers are usually able with recovering without them, I’d not recommend omitting them and stick to adding any fields the specification requires)

This example shows rendering a simple 3x3 pixel image where we defined that every RGB value in the data stream has 8 bits of freedom, as indicated by the DeviceRGB colour space and 8 BitsPerComponent. This means that the trailing data stream of the object is simply the literal pixel values encoded as a hex string (depending on the filter but here ASCIIHexDecode means just hex). In this case we have 3x3 = 9 pixel values, the resulting colour matrix is encoded left-to-right top-to-bottom as follows:

red    green  blue
blue   red    green
red    blue   red

The resulting image when printed onto a PDF looks like this:

Note: I rendered the image larger than a 3x3 grid so the colours interpolate into each other during upscaling by default, but this wouldn’t normally happen for regular images rendered at their actual size. In most case this would of course be a much larger image, usually encoded with a filter that offers way more compression.

Now, if we want to add transparency to this image all we actually need to do is define a separate XObject as an SMask for our original image.

This SMask should follow the same structure (i.e., the same height and width definitions) but since we are only defining an alpha mask we only need the DeviceGray colour space instead of DeviceRGB. This is because we only need a single byte per alpha value instead of 3. According to this, such an XObject would be defined like this:

2 0 obj
<<
/Type /XObject
/Subtype /Image
/Width 3
/Height 3
/ColorSpace /DeviceGray
/BitsPerComponent 8
/Filter [ /ASCIIHexDecode ]
>>
stream
ff ff ff 66 66 66 00 00 00
endstream
endobj

And of course don’t forget to amend the previous object to include the SMask

1 0 obj
<<
/Type /XObject
/Subtype /Image
/SMask 2 0 R
[...]

The resulting image will have combined the mask and the pixels for this resulting image:

As you can see there isn’t actually much to it, all you need to do is separate your RGB colour channel from the alpha channel and then define them separately in another XObject. However, if you (like me) have jumped into the full PDF specification you may know it’s sometimes difficult to parse these details from it.

And that is all for this post, enjoy your images with transparency!

TanStack Router SPA co-located in Astro

Sat, 17 Aug 2024 20:00:00 GMT

I was setting up a site that primarily serves a front-page plus documentation, where most parts are static and I wanted to fully generate them ahead of time to serve from a bucket. Astro makes this very easy, and also enables me to create and iterate on content for documentation very quickly. Furthermore, it also has the nice benefit being able to weave in interactive components on the fly if needed.

The docs in question are fully generated from markdown, but I like to have a few interactive examples so that users can build a better understanding of features. My use case is basically just a complex JSON configuration in a single object, not multi-file setups so users. It is very useful to have some visual feedback to play around with, but having to jump into a code sandbox for testing any change seemed overkill.

To create this, Astro reads my .mdx templates which includes embedded React components. Via Astro Islands I can serve this very efficiently and only have to load the components when needed.

However, to actually use the platform I have a fully interactive part which acts as a dashboard to the user. Here they can configure their account specific settings, upload files and do whatever needs to be done. There is a lot of moving parts, so I opted to build it as an SPA instead of relying on Astro. This comes with so many nice ease-of-use features and reactivity plus the package ecosystem of React. It just made sense to me for building such a dashboard.

I wanted to use TanStack Router as the navigation for this portion and while their documentation is extremely well written and easy to follow it is more meant for a “classic” Vite setup. There is no official integration setup, but it was still fairly easy to configure in the end.

My file tree layout is as follows:

./
|- astro.config.mjs
|- src/
|  |- layout/                  <  These are the regular Astro folders,
|  |- content/                 <
|  |- pages/                   <
|  |  |- index.astro           <
|  |  |- dashboard
|  |  |  |- [...page].astro    < This Astro page imports the React dashboard from
|  |                             from src/dashboard/main
|  |
|  |- components/              <  Folders for shared (react) components,
|  |  |- astro/                <  they can be imported in Astro or the Dashboard
|  |  |- react/                <  code.
|  |
|  |- dashboard/               <  Dashboard code, here I can set up
|  |  |- main.tsx              <  @tanstack/react-router files as
|  |  |- routes/               <  in a regular project.
|  |  |  |- __root.tsx         <
|  |  |  |- dashboard/         <  Matching the route `/dashboard` of the Astro page
|  |  |  |  |- index.lazy.tsx  <
|  |  |- routeTree.gen.ts      <  Auto-generated by @tanstack/router-plugin/vite

This layout lets me to co-locate Astro layout and components with the React dashboard. It is super useful because it allows me to import shared React components in both areas.

To generate the routeTree.gen.ts that is required for TanStack Router, the internal Vite bundler of Astro needs to be made aware of the generator plugin. I use the following Astro config:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from "@astrojs/react";
import mdx from "@astrojs/mdx";

import { TanStackRouterVite } from '@tanstack/router-plugin/vite'

// https://astro.build/config
export default defineConfig({
  integrations: [react(), mdx()],
  vite: {
    plugins: [TanStackRouterVite({
      routesDirectory: "./src/dashboard/routes",
      generatedRouteTree: "./src/dashboard/routeTree.gen.ts",
      routeFileIgnorePrefix: "-",
      quoteStyle: "double",
    })]
  }
});

Astro makes it possible to append to Vite plugins by exposing the vite key in its configuration. By setting the routerDirectory and generatedRouteTree params in the TanStackRouterVite options it is possible to point the route generation at the correct folder. I had no luck using the tsr.config.json as referenced in the documentation, but passing the options directly like so seems to work fine. Just make sure to npm install @tanstack/router-plugin/vite for this to work.

The following two files are then practically the glue to import the actual dashboard into Astro and render it into the page layout. Astro needs to know which paths exist to generate the proper SSG routes. This can be accomplished by parsing the routeTree as generated by TanStack Router and populating getStaticPaths.

---
// src/pages/dashboard/[...page].astro
import Layout from "../layouts/Layout.astro"

import { Dashboard as ReactDashboard } from "../../dashboard/main.tsx"

import { type Route } from "@tanstack/react-router"
import { routeTree } from "../../dashboard/routeTree.gen.ts"

export async function getStaticPaths() {
  const mapChildren = (route: Route): any => {
    if (!route?.options) {
      return []
    }
    return [
      route.options,
      ...Object.values(route?.children || []).flatMap((child) =>
        mapChildren(child)
      ),
    ]
  }

  const asMapped = mapChildren(routeTree as unknown as Route)
  return asMapped.map((route: { path?: string }) => ({
    params: {
      // splice the prefixed `/dashboard` by the generator
      path: route.path?.split("/")?.splice(2)?.join("/"),
    },
  }))
}
---

<Layout title="">
  <main>
    <ReactDashboard client:only="react" />
  </main>
</Layout>

At this point I want to note that this strategy will generate a new file for EVERY route in your SPA router. In my case this is useful because it still allows me to dump the whole site into a bucket, but if you are running an Astro adapter to serve your site dynamically in hybrid or server mode then you might want to consider using prefetch: false for just this page.

Finally this is the React component which is the entry point for the dashboard:

// src/dashboard/main.tsx
import { RouterProvider, createRouter } from "@tanstack/react-router"

// Import the generated route tree
import { routeTree } from "./routeTree.gen.ts"

// Create a new router instance
const router = createRouter({ routeTree })

// Register the router instance for type safety
declare module "@tanstack/react-router" {
  interface Register {
    router: typeof router
  }
}

// Usually here we would render to the DOM, but since Astro will handle
// this for us we are okay to just return the component
export const Dashboard = () => <RouterProvider router={router} />

As far as I can tell this setup is totally seamless and behaves exactly like you would expect. I am super impressed by both TanStack’s Router and Astro to just go hand-in-hand like this without any issues.

What’s a story point anyway

Sun, 11 Aug 2024 20:00:00 GMT

Recently I read an interesting post about story points in agile development titled „Story Point Revisited“ by Ron Jeffries. It made me think about how I feel about them and estimation processes for software development in general.

A TL;DR recap

In this article Jeffries critiques the use of story points as a misplaced proxy for just estimating time in the first place. According to him their original inception was driven by the fact that the „ideal“ time of implementation is often distorted by distractions and it led his team to the conclusion that the actual time of work needed often ended up being closer to three times of that ideal. By calling 3 days a „point“ they avoided confusion (what’s a „story day“?) and it was a reasonably straightforward solution when dealing with the problem of encoding difficulty, effort and complexity with the concept of time.

If you are in any way involved with other developers you will have invariably have run into the crowd that absolutely deplores this kind of story point and anything vaguely connected to planning poker sessions. While I always generally accepted that some people have this position, I never quite understood it (or agreed with it for that matter). This post made me appreciate the potential issues with the system better and upon reflection it made me think of some of the key factors that in my opinion make or break story point estimations:

Do not measure time

I know, I know. This one seemingly everyone talks about, and in actuality no one does. But I am being serious when I say, before you think of time, think about how difficult a change seems, how many components it touches, how much infrastructure or underlying systems need to change. What is the impact for the user? What are the risks? Are there any wait times, blockers, other team members involved? Any ticket may have dozens of such considerations and any of them may move the time needed to implement by hours or days. How many of those? Most of the time no one really knows and in my opinion this is where story points really shine.

If you think of every single one of those decisions as a sliding scale, e.g. 0-5, and all your team members feel roughly the same about where a task lands on that scale for these decisions, then all of these complexities sum up into one number. I don’t want you to think about this too literally, don’t start pulling out a calculator in your scrum meetings, but rather think about it in a metaphorical sense. I never consider time directly as a factor when I estimate a ticket, the points I estimate will just naturally scale with the complexity of a ticket because of all the encoded decisions, and thus it will take more or less time to complete.

After all, the estimation process is extremely useful as any initial estimation reveals a real insight into every developers thought process which ultimately determines an items difficulty. If there is large discrepancies in estimated points for a ticket here it’s a great opportunity to teach or learn about why a change may be more or less problematic than initially thought. In the future these gaps of estimation between team members will almost magically close by themselves, the team grows together and becomes way more “dialled-in” to all the potential factors a change might carry with it.

There is a caveat to this, which is that it only works if quite literally time is not of the essence in terms of your development cycle. In particular I mean, the result of the work has to be more important than the time spent on it. It won’t work if your time worked is tracked against a paying client, instead of you developing a product for your own company where the feature or change is „just“ an inherent value add. If your project needs to be delivered by a certain time, or there is a particularly statistics driven culture around delivering workloads on time then this simply won’t work. If you need to measure time, measure time not story points.

This leads into my next point:

No comparisons, EVER

Given my previous philosophy on how I think about story point estimates, I think this one will come at no shock. It simply does not make sense to compare items when they have their story points estimated for vastly different reasons.

Two tickets might have vaguely similar points, but one might be a deeply complex change in a core system, while the other might require long wait times because of trial and error runs in our CI. One or the other may be done considerably faster or slower than the other for should-have-known and/or completely unforeseeable reasons.

Additionally, these points we estimate and assign are invariably a compression over a range. In my opinion this range can by definition not be well defined, the same amount of points can mean very different things if they happen to be on opposite ends of the “acceptable” range for their point estimate. For example, currently we pretty much only estimate 1, 2, 3, 5, or 8 points - anything larger than 8 is practically too large to be considered one unit of work and will be split into smaller tickets. This correlates roughly with “no ticket should take longer than one or two days work”. To somewhat break it down:

1 can be a one line fix or any very small change.

3 would be probably the most common medium workload that touches multiple files and vaguely changes or adds to a system without requiring a total deep dive.

8 would be a very large and substantial change, requiring multiple rounds of reviews and rigorous testing.

Now how does it make sense if eight 1-point typo fixes can equal one such substantial change? That’s the neat thing, it doesn’t! The estimation merely suggests how much effort will be funneled into implementing that one change, as such it’s completely independent of any other ticket in your backlog. It’s an estimation for that one workload, and that one workload alone.

You might think that this could not possibly work and that our amount of worked points has to fluctuate wildly. My counterpoint to that would be this graph of weekly points delivered over a period of 6 months, it represents how an average of how many points any single developer would have delivered per week, scaled against the available capacity in the team (to account for leave, hirings, etc.)

While we do have variation, we keep a fairly consistent level of delivered work week to week. Importantly, we don‘t care about the actual week to week performance because - once again - we don’t compare. It can sometimes be useful to reflect on a particularly „good“ (or bad) week to investigate which tickets have caused such stark deviation. In turn that in itself can act as a great self-fuelling function to get a better feel as a team for what constitutes an easy or hard ticket, and perhaps even more importantly, why it does! It teaches us more about the work we are doing day to day.

The horror

With all that being said, this brings us to the seemingly biggest issue with story points that I luckily never had to experience myself. Even just the prospect fills me with dread and therefore I believe I understand some of the issues people have with a point based system.

-> Abusing point estimates for cross-team reports and performance metrics.

This one is a real head scratcher to me, as I had never even considered that there are project managers who may look at story points and then compare the amount of completed points across teams. The mere thought of this seems horrifying at best to me. I have always worked in small companies, the size of developer teams never exceeding the amount of people where you could comfortably have a meeting with everyone in the same room. Even then, the amount of times people have disagreed how hard a ticket would be for one reason or another, and how seemingly arbitrary these reasons sometimes are… I simply cannot fathom how anyone would attend such a meeting and feel like there is any merit in drawing useful comparisons from those metrics.

Do not compare, please.

Conclusion

To wrap up, all of this only represents my personal perspective and I cannot assert that all I propose in this post is the only real way to use story point estimations. Software development usually is a highly dynamic process and I imagine that some teams have found ways to work around the exact issues I preach to avoid here. Nevertheless, everything I have learned about this process myself, and the opinions and comments I have read make me believe my conclusions about estimation are generally applicable.

Finally, I truly do believe that utilising story points for agile development cycles can work, but you need a very cohesive team, that has enough agency to deliver work outside of strict deadlines. If accurately tracking or reporting on spent development time and/or increasing a sense of velocity based on completed estimates are important goals to you, I would suggest avoiding story point estimation altogether.

For my current team and frankly, all the teams I have worked in so far, story point estimation never felt like a chore but rather a useful tool. However, I do appreciate the perspective this review has given me.

Puppeteer in GitHub Actions

Thu, 01 Aug 2024 20:00:00 GMT

I couldn’t find a straightforward way on how to accomplish launching headless puppeteer in GitHub Actions. This turned out to be surprisingly simple and does not require any third party actions or containers at all. It took me a while to find this bit of information though and therefore I’m just leaving it here too, perhaps it will be useful to someone (even me) in the future.

The trick is to just point the executable path to the correct location in the action. You can install the puppeteer package as you normally would and all you need to do then is point executablePath to usr/bin/google-chrome-stable. Done.

For reference, these are the full launch argument that which are currently working:

const browser = await puppeteer.launch({
  headless: true,
  defaultViewport: null,
  args: [
    "--ignore-certificate-errors",
    "--no-sandbox",
    "--disable-setuid-sandbox",
    "--disable-accelerated-2d-canvas",
    "--disable-gpu",
  ],
  executablePath: "/usr/bin/google-chrome-stable",
});

It is quite possible that you won’t need all of the arguments specified above for it to continue working. The current working puppeteer version in the project is puppeteer": "22.14.0"

And that’s all …

Generating images with sharp in dockerised Bun

Fri, 17 Nov 2023 20:00:00 GMT

Preface: as of writing this bun’s latest released version is 1.0.12 and for sharp it is 0.33.0-alpha.12

As can be seen by some of my previous posts on this blog, I love using this website itself to play around and familiarise myself with new tech. Before, I wrote about my own homebrewed SSR approach plus hydration. This was super fun to build, but wasn’t the most stable or easiest to maintain. I have recently switched to Astro which is a more mature version of the same idea with many nice additions and quality of life features. It also does not require react but supports JSX-style templating, very neat.

But because I can’t help myself I decided to not go with an actual stable, regular node server and instead started tinkering with Bun . In case you haven’t heard, Bun is an incredible new runtime/dependency manager developed by the extremely talented team at Oven. However, while it is impressive, in it’s current state it isn’t entirely without flaws.

Back to the matter at hand: I have been working on exposing a custom endpoint which dynamically generates a social card image based on the current route. To generate and compose these images I use the sharp package. This is a well maintained image manipulation library with a very intuitive API. This works and looks great, and I thought it would be as simple as just pushing it to get it to work. Here is an example of what my previous post looks like when, for example, pasting a link to Facebook:

Unfortunately this wasn’t quite as easy as just adding the image generation part. While in my development environment everything works fine, there are some issues when setting it up in a docker container (which I use to host this website). At the moment bun breaks post-install scripts of dependencies, which sharp unfortunately relies upon, at least in the current stable release version 0.32.x. I found a GitHub issue which referenced an “alpha” version of sharp which removed the reliance on it. And in fact, with sharp@0.33.0-alpha.9 this works (I tried upgrading to the current latest -alpha.12 too but this also seemingly breaks).

Once I had figured this out, I was sure it everything else would just fall into place… nope, no luck - apparently the Docker image oven/bun:1.0.12 (which as of right now is latest) is broken when installing my dependencies. I don’t know if this is the case for everyone or just for the particular set of dependencies in my repo, what I do know is that I had to revert to the previous version oven/bun:1.0.11 to get it working again.

I was very happy when my build finally succeeded, the container spun up and the image generation worked! Well, until I realised that the bun docker image ships without any fonts pre-installed. So what I got was a lovely selection of boxes: ”☐☐☐☐☐☐☐☐☐☐☐”, while this is almost entertaining enough to keep as-is, I decided to at least try and solve the issue first. Luckily, this wasn’t too much of a problem, I now simply install fontconfig as part of my Docker build and then copy the fonts into my release image. This is required because sharp uses the resulting fontconfig file to resolve available fonts.

FROM oven/bun:1.0.11 as base

FROM base as fonts
RUN apt-get update
RUN apt-get -y install fontconfig fonts-roboto
RUN fc-cache -fv

[...]

FROM base AS release
COPY --from=fonts /usr/share/fonts /usr/share/fonts
COPY --from=fonts /etc/fonts /etc/fonts

[...]

Now my images finally render correctly, including text and everything. Probably these setup issues will be resolved soon (either in sharp and/or bun) but until then this is a helpful workaround.

Making exercise convenient

Mon, 13 Nov 2023 20:00:00 GMT

Everyone has some sort of system to keep themselves in shape, but keeping yourself in the habit of regular exercise can be just as rewarding and fun as it can be difficult, annoying or demanding.

One realisation I have had about working out is that there is one thing above anything else that I value. That thing is convenience, for one I love living close to my gym. It wasn’t really a consideration when I chose this place but being able to walk to my gym within less than 5 minutes is a huge motivator. I have some weights at home and there is a lot of exercises you can do at home anyway, but actually going to the gym just puts me into a flow state that I can’t achieve at home. Previously I’d still often just accept not having this simply because I didn’t actually want to make the trek to the gym. Now, there is rarely a point for me to work out at home, popping over is so easy that I just always end up doing it.

Secondly, I went to the gym for the first time when I was ~16 years old (over 10 years ago now.. jeez) and since then I have been very on and off with actually going. Sometimes I wouldn’t go at all for a few years, for example when moving out for my undergrad etc. My relationship and expectations with exercising is therefore a bit all over the place. I have had friends and gone to work out with people on all ends of the spectrum who either went the straight up body builder route or quit almost straight away. Especially in youth there probably was a lot of not-so-great advice.

For a long time my assumption with working out was that you should pretty much always go as hard as possible, and exert yourself to get the maximum out of the exercise you are doing. Build as much muscle as you can, any way possible. This rings especially true if you have a long travel time to maximise that initial time investment.

What I used to do is fairly long workouts in the range of 90-120+ minutes. But what that exertion did was that it didn’t really leave me satisfied to break myself down like that. Instead of feeling good about the work, I was super tired and sometimes even feeling unwell afterwards. Head spinning or slight feeling of sickness also wasn’t uncommon. And at some point I just realised I don’t have to do that, I can do short and intense workouts and then just enjoy the rest of my day. Nowadays I much much prefer shorter, more frequent workouts. I often go for just about 45 minute sessions now.

This may not be optimal, to be honest, I don’t care. I use the gym as a means to stay relatively fit, and also as a way to check out of my day-to-day and just lift some weights. Some days this also really bolsters my mental health. I don’t chase records, I don’t ego lift, I do my best to stay in form and keep myself from getting injured. While some might find that boring, it really works for me. With that come other non-optimal things I do, I don’t drink protein shakes or take any supplements. Through my cooking I maintain a pretty balanced diet almost automatically and at that point whatever nutrients or protein I get from that is what I get.

I think this is where my entire viewpoint on exercise weaves together. I want working out / the gym to be a positive, healthy addition to my life. At no point do I want to change my habits (wants or needs) to adjust for this. I live my life and the gym gets added on simply as an improvement, something that doesn’t require maintenance or thought. I don’t mean this to be advice, or preachy in any way. I fully understand and am happy for people who do choose to make it a bigger part of their lives. However, I often felt like I almost had to hide that I don‘t consider it like that. Like as if when you don’t take it seriously it isn’t a „valid“ way to exercise.

It took me a long time to figure out that the best way to do it is the way that makes me personally happy, and which fits best with how I want to live my life. As I don’t see this sentiment out there a lot I wanted to share it as an anecdote.

Breaking the rules (sometimes)

Sat, 07 Oct 2023 20:00:00 GMT

A while ago I came across this idea in music production, this is paraphrased but the idea is: „It doesn’t matter if what you’re doing is wrong, if you like it“. I have seen this echoed multiple times and often it comes with the addendum „understand why it’s wrong and then do it anyways“. Only then will you distinguish yourself from the pack and make something truly special and interesting.

I thought about this mindset a lot recently. Let me make you consider this: Everyone starts life with roughly the same ways in terms of education, from a young age, as kids, we get taught how things are done, how they are supposed to be done. As we grow older we realise that the „olden“ ways might not be perfect, that our teachers had flaws and so do their preachings. However, oftentimes within them there are valuable lessons, we understand why things are done a certain way or how something works and then we adapt it so that it works better for us.

This also extends to later in life. I do think most of us hit this moment in our careers where we think we know exactly what’s going on. We have finally cracked the code, we may be aware that there is more to learn but generally we are sure we know the extent of what there is to know and only little is left to master. A certain image comes to mind.

Source

So when we think we have arrived, we almost certainly have not. And this isn’t about the classic, the „there is always more to learn“. This is more specifically about a certain point that will shift how you view problems and solutions within your domain. A point where you notice that a decision was made outside of the rules, but instead of disliking the decision you actually agree? Suddenly this unfolds an almost infinite amount of knowledge and experimentation beyond what you understood as the de facto rules of the subject matter. You will have this moment of „wait, you can do that?“ and it will completely warp your understanding of what you thought you knew so well.

And while I think this immediately makes a lot of sense for artistic disciplines, I think it translates to many other areas. As a developer I formally learned about all these concepts that over decades were refined to make my craft as optimal as possible. Think ideas such as abstraction, normalisation, typing, etc..

Once I started working with and not just studying these concepts, it felt like I got the hang of them relatively quickly. I thought I could refactor everything to follow the „perfect rules“ that I got taught previously. In my head they were sound and made sense. It surprised me when people with years and years of experience engineered solutions that felt incomplete or conceptually wrong to me. Even more so when I had to fight for the „correct“ way to implement whatever concept I was dealing with at the time. However, the more I built, the more I learned. One approach being technically more correct doesn’t always mean it is mandatory to do it that way.

Sometimes what you do 99% of the time is not required in certain edge cases. Sometimes it’s fine to duplicate code or columns in your database. Sometimes it’s fine to use an „any“ type. Sometimes it’s fine to spend 5 instead of 30+ minutes to build a script to run it exactly once and then forget about it and touch it never again.

What is important is that you understand why it is ok to break the rules in those cases. And for that you have to learn and understand the rules first. You have to internalise what they contribute and, perhaps, what their drawbacks are. You may even break the rules but get it wrong multiple times first, before it clicks and you get it right. Over time this will evolve and the boundaries of „technically correct“ and „accomplishes the job just right“ blur more and more. The part to remember is that this should not be done out of laziness or because of a lack of care. It needs to be an active, deliberate choice. However, when it is, allowing it to happen will enable you to be more considered and also more expressive. In software engineering this may not be as flexible as in music or other art forms, but in my experience it still applies to some extent. Plus, if nothing else it is nice to reconsider why you do the things you do, rather than just habitually follow what you picked up previously.

To wrap up my thoughts on this: It is important to learn the rules. Learning the rules allows you to make happy accidents, rather than mistakes.

Utilising the co-occurrence of user interface interactions as a risk indicator for smartphone addiction

Tue, 16 Aug 2022 20:00:00 GMT

I just published a substantial paper on the viability of using smartphone interactions for addiction evaluation in Elsevier‘s Pervasive and Mobile Computing .

The study highlights a novel methodology to transform and analyse large amounts of interaction events to infer a user’s level of smartphone addiction. This is a step forward from using commonly used metrics such as pure screen on time which can misrepresent the cognitive complexities and dependencies of human behaviour.

Additionally, we find that session to session behaviour shows a lot of variance. From this we conclude that, even with a stable user trait such as addiction, users display problematic use patterns in only a subset of all their sessions.

While the paper is still in pre-press stage as of now, you can already find it here: https://doi.org/10.1016/j.pmcj.2022.101677

Resolving 404 issues with S3, CloudFront and SPAs

Mon, 01 Aug 2022 20:00:00 GMT

Today I worked on an issue that led me down a rabbit hole to resolve an issue with AWS. We noticed that security headers were missing from some of our CloudFront responses. Weirdly, everything was fine at first glance. Navigating to the application at its base path would return all expected headers. The issue was reported specifically for our /login path and as it turned out, using this path as an entry point would indeed not send the correct headers.

Without going into too much detail, the application in question is served using a single index file, where any path then gets resolved by the application itself via react-router . A classic setup for a React SPA. On the AWS side, the static files are located in a S3 bucket with Static website hosting enabled. This is used as an Origin domain in a CloudFront distribution. The headers get applied by a CloudFront Function in a Viewer Response.

So far so good. The first issue I identified was that a page load on any path that was not the root (such as /login) would result in a 404 response. But importantly, the application would still load and render correctly. I initially assumed this was just a peculiar cache-miss problem on CloudFront’s end but it turned out to be more complicated than that.

After a lot of back and forth of checking configurations I found a lead in S3’s Static website hosting. It turns out the index file was specified for both, the Index document but also the Error document. This meant that even if the path to a resource was specified incorrectly (in this case, any path was added to the request at all) the index file would always be served anyway.

It also appears that CloudFront will always forward the original request URL (e.g. /login) directly to its Origin. In the case of S3, it will try to resolve the path as a file. Since we only host the index file and a static folder, the request fails with a File Not Found response. Critically, in case of an Origin returning an error code CloudFront does not apply the Viewer Response function.

So how do you fix this? AWS does not have an easy way to deal with this. There is no in-built filtering functionality or any other way to create an automatic redirection to the correct resources. I found two solutions that did not work for me, and one that did.

Solution that does not work #1: Set up a custom error page in CloudFront

CloudFront distributions allow to set custom error pages based on responses received from their Origin. While this allows to remap the 404 error to a 200 status code, CloudFront will still not apply its Viewer Response function. Therefore, while the console network tab is happy, our fault is not fixed.

Solution that does not work #2: Setting the Default root object

As seen on StackOverflow, some people had success setting the Default root object in the Distributions General Settings (source) to their index file. However, this did not help at all in this case.

Solution that did work: Conditionally rewriting the path in the Viewer Request

Remember how CloudFront forwards every URL directly to its Origins. Using the Viewer Request function of a Distribution we can update the path to be rerouted to the root element /. This will cause S3 to respond with the index file. Note, we still serve static files from the same domain so we want to avoid rewriting all requests.

For reference, this is the function we added. Please forgive the ugly code, it was a long day - I intend to clean it up tomorrow. I also despise whatever environment AWS is running these in as it would not accept my slightly more elegant regex.

function handler(event) {
  var request = event.request;
  var pathItems = request.uri.split("/");
  var lastItem = pathItems[pathItems.length - 1];
  // Rewrite any paths that do not end in a file (e.g. .html, .css or .js)
  if (lastItem.indexOf(".") === -1) {
    request.uri = "/";
  }
  return request;
}

This finally resolved our issue, as S3 now returns the index file for every request that is not a static file request which then made CloudFront add the headers using it edge functions.

In conclusion, if you run into an issue where on first page load your non-root paths do not load and you use S3 as an origin for your CloudFront Distribution, try to rewrite the request URL in your Viewer Request function to remove any unnecessary path before the request reaches S3.

Statistics are weird

Tue, 07 Dec 2021 20:00:00 GMT

As part of my PhD research I have had to interact with way more statistical evaluation than ever before. Even though I would have to go through the occasional ANOVA et al. for my under- and postgrad degrees, I never really needed to internalise how and why statistical testing was actually done. It is one of those topics where when you are just starting out, you accept a few things as fact.

Just to be clear, I am far from understanding it all. I feel like that the more I’m learning about statistics the more it dawns on me how much further there is to go. That being said, I picked up a few bits that have helped me align my own understanding with a few of the basic rules.

My biggest take away so far has been that there is never a 100% catch all test for every problem. Often the correct choice is to scan related literature for their reporting metrics or trying to find literature that relates to your core comparisons even if it does not match the exact topic.

I have also learned to question my results. More often than not, going further than simply checking a p<0.05 has helped me for the better. Understanding and exploring how and why those relationships occur and what they mean has been a big help in comprehending my own research.

Especially my discovery of reporting effect sizes has been eye opening. It is super interesting to see my own results transform completely just because I pay attention to the different magnitudes apart from just equalling them on terms of significance.

name == "main"

Sun, 24 Oct 2021 20:00:00 GMT

or, humble beginnings.

I will be looking to add more content here soon, especially about the inception of this website.

Björn Friedrichs' Blog

PDF Interpolator: Replacing text in templated PDFs with spreadsheet data

AI is amazing, AI is scary

Multi-row, dynamically truncated text width with ellipsis in pure CSS

Microsoft Teams silent login flow in 2025

Using UUID v4 in Expo (native + web)

Multiple services in Tailscale with Traefik + Docker

Building my own (virtual) bookshelf

Pdf Mini: Images with transparency

TanStack Router SPA co-located in Astro

What’s a story point anyway

Puppeteer in GitHub Actions

Generating images with sharp in dockerised Bun

Making exercise convenient

Breaking the rules (sometimes)

Utilising the co-occurrence of user interface interactions as a risk indicator for smartphone addiction

Resolving 404 issues with S3, CloudFront and SPAs

Statistics are weird

__name__ == "__main__"

name == "main"