freddydumont's blog

How to add Custom Locations in Nginx Proxy Manager

Fri, 11 Apr 2025 00:00:00 GMT

After installing Coolify on my homelab and proxying it with Nginx Proxy Manager (NPM), I ran into an issue. Even with WebSockets Support enabled, I kept getting warnings in the UI and browser console about failed WebSocket connections.

The problem was that Coolify uses different routes and ports for WebSockets, and configuring NPM to handle this correctly isn’t obvious.

Here’s how to properly set up custom locations in NPM when you need them:

Basic Setup

First, create your proxy host with the main website configuration
Enable WebSockets in the main configuration if needed
Add custom locations for specific paths requiring special handling

Adding WebSocket Custom Locations

From your proxy host details page, click “Custom Locations” and then “Add Location” :

Configure the Basic Fields

Location: Enter the path (e.g., /app or /terminal/ws)
Scheme: Select http (or https if your backend uses SSL)
Forward Hostname / IP: Enter the IP address only (e.g., 192.168.1.12)
- that is, without the path used in location
Forward Port: Enter the specific port for this path (e.g., 6001)

Configure Advanced Settings

In the text area that shows up after clicking the gear icon, you must include the complete location block configuration.

location /your-path {
    proxy_pass http://your-ip:your-port;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
}

You’d expect the textarea’s contents to be inserted in the block generated from the mandatory inputs, but that won’t work. Don’t ask me why.

Coolify example

Coolify has two different WebSocket paths:

For `/app` WebSocket:

Location: /app
Scheme: http
Forward IP: 192.168.1.12
Port: 6001
Advanced Config:

location /app {
    proxy_pass http://192.168.1.12:6001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
}

For `/terminal/ws` WebSocket:

Location: /terminal/ws
Scheme: http
Forward IP: 192.168.1.12
Port: 6002
Advanced Config:

location /terminal/ws {
    proxy_pass http://192.168.1.12:6002;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
}

Troubleshooting

If your proxy shows offline, check the generated Nginx configuration. You’ll find them under /data/nginx/proxy_host. Numbers will match what’s in the UI.

Check your firewall configuration with ss -tuln. The application ports you’re trying to proxy should be in the list.
Ensure that the location path in the Advanced tab exactly matches the Location field

Generate D2 PNG diagrams in GitHub Actions

Fri, 10 May 2024 00:00:00 GMT

D2 is a cool little DSL that allows you to generate diagrams from code.

It’s quite easy to learn, and can be a much better option for developers than using drag-and-drop diagramming software.

Running it locally is simple: d2 my-diagram.d2 will generate a SVG of your diagram.

However, if your D2 code embeds remote images, those links will be embedded in the SVGs, so those images will not show in contexts where doing that isn’t allowed.

While you can generate a PNG locally, d2 relies on playwright to take a screenshot of the SVG.

For this reason, or any other, you might want to build your diagrams in CI using GitHub Actions.

Here’s a workflow that does just that, commented for clarity:

name: 'Generate PNG diagrams'

# Triggers on new version tags with filename suffix, e.g., dns.d2 -> v1.2.3-dns
on:
  push:
    tags:
      - 'v*.*.*-*'

# softprops/action-gh-release@v1 needs these permissions
permissions:
  contents: write

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Extracts the file name from the pushed tag
      - name: Extract filename
        run: echo "FILENAME=${GITHUB_REF#refs/tags/*-}" >> $GITHUB_ENV

      - name: Install d2
        run: curl -fsSL https://d2lang.com/install.sh | sh -s --

      # Caches playwright without relying on `package.json`.
      # If you want to force a playwright upgrade, delete the cache in the GitHub Actions UI.
      - name: Cache playwright binaries
        id: cache-playwright
        uses: actions/cache@v4
        with:
          path: ~/.cache/ms-playwright
          key: playwright-cache

      # Installs playwright if it's not already cached
      - name: Install playwright
        if: steps.cache-playwright.outputs.cache-hit != 'true'
        run: npx playwright install --with-deps chromium

      # Assumes the diagram is located at the repo's root.
      # Adjust according to your project structure.
      - name: Generate diagram
        run: d2 ${{ env.FILENAME }}.d2 ${{ env.FILENAME }}.png

      # Publishes the PNG under GitHub's Release tab
      - name: Release
        uses: softprops/action-gh-release@v1
        with:
          files: ${{ env.FILENAME }}.png

Using this basic workflow, your PNG diagrams will be available under the Release tab in GitHub.

How to generate NixOS LXC templates in GitHub Actions

Sat, 23 Dec 2023 00:00:00 GMT

I started using Nix some time ago when I got this M2 MacBook Air. With nix-darwin and home-manager, it’s a great way to handle dotfiles.

The thing with Nix is, when you start using it somewhere, you start using it everywhere. There is no turning back to entering commands one after the other to install and configure programs.

Naturally, when I started homelabbing with Proxmox (PVE) as my hypervisor, I used NixOS to create LXC containers, which are bootstrapped using a template.

While you could pull a NixOS container template from Hydra, install it in PVE, and pull your configuration from your Nix config repo, what if you could instead generate a pre-built NixOS LXC template direclty from you repo?

That’s exactly what I ended up doing, using GitHub Actions and nixos-generators.

Solution

Here’s my GitHub Actions workflow to generate NixOS container templates. I’ve commented for clarity.

name: 'generate-lxc'

# The workflow is triggered on new version tags with a hostname suffix,
# where the hostname corresponds to a nixosConfiguration in flake.nix.
on:
  push:
    tags:
      - 'v*.*.*-*'

# softprops/action-gh-release@v1 needs these permissions
permissions:
  contents: write

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Extract the hostname from the version tag suffix and
      # save it as an environment variable.
      - name: Extract tag suffix
        run: echo "TAG_SUFFIX=${GITHUB_REF#refs/tags/*-}" >> $GITHUB_ENV

      - name: Install nix
        uses: cachix/install-nix-action@v24
        with:
          github_access_token: ${{ secrets.GITHUB_TOKEN }}

      # Use the tag suffix to specify which configuration to build with the generator,
      # and then store the build path in an environment variable.
      - name: Generate NixOS configuration
        run: |
          nix run github:nix-community/nixos-generators -- -f proxmox-lxc --flake .#${{ env.TAG_SUFFIX }} | {
            read path
            echo "BUILD_PATH=$path" >> $GITHUB_ENV
          }

      # Move the build artifact to a working directory and
      # rename it to include the tag suffix.
      - name: Prepend tag suffix to file name
        run: |
          NEW_FILENAME="${{ env.TAG_SUFFIX }}-$(basename ${{ env.BUILD_PATH }})"
          RELEASE_PATH="${{ github.workspace }}/$NEW_FILENAME"
          cp "${{ env.BUILD_PATH }}" "$RELEASE_PATH"
          echo "RELEASE_PATH=$RELEASE_PATH" >> $GITHUB_ENV

      # Create a GitHub release and attach the generated container template.
      - name: Release
        uses: softprops/action-gh-release@v1
        with:
          files: ${{ env.RELEASE_PATH }}

This assumes you’re using flakes, and have a flake.nix file at the root of your repo.

Here’s what nixosConfigurations should look like:

{
  # ...

  outputs = { darwin, home-manager, nixpkgs, ... }: {

    darwinConfigurations = {
      # macOS config
    };

    nixosConfigurations = {
      "nfs" = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          "${nixpkgs}/nixos/modules/virtualisation/proxmox-lxc.nix"
          ./nixos
          ./nixos/nfs.nix
        ];
      };

      "dns" = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          "${nixpkgs}/nixos/modules/virtualisation/proxmox-lxc.nix"
          ./nixos
          ./nixos/dns.nix
        ];
      };
      # ... other configurations
    };
  };
}

For instance, if I want to build the nfs system, I commit and push my changes, then tag it as v0.2.2-nfs. For dns, I would tag it v0.1.0-dns. Here’s what the releases page look like:

If your repo is public, you can then use the Download from URL button in the PVE user interface and give it the tarball URL direclty. Otherwise, download it locally and upload it to PVE manually.

And that’s it! When you create a Linux container using this template, you’ll have a NixOS machine ready to go!

How to configure Vite to include additional folders

Sat, 02 Sep 2023 00:00:00 GMT

When setting up Panda CSS in a RedwoodJS project, I ran into a small issue: although autocomplete worked fine in my editor, the dev server couldn’t find the generated Panda files, so the styles weren’t applied.

The solution

The solution is quite simple, if you know that the keyword to search for is resolve!

I ended up finding it in this StackOverflow answer. Note that the accepted answer is out of date and only adds unnecessary steps.

All you need to do is add the following highlighted lines to your Vite config.

const viteConfig: UserConfig = {
  plugins: [redwood()],
  resolve: {
    alias: [
      {
        find: 'styled-system',
        replacement: resolve(__dirname, 'styled-system'),
      },
    ],
  },
};

This tells Vite to find imports starting with styled-system, in the same folder as Vite’s config.

Explanation

By default, Vite’s entry point in a RedwoodJS project is in web/src, so the bundler has no awareness of what’s at the root level (web). The resolve alias maps styled-system imports to the correct location, fixing the issue.

Radix Themes vs Primitives

Mon, 14 Aug 2023 00:00:00 GMT

The recent release of Radix Themes piqued my interest but I feel some questions aren’t answered:

How does this solution compare to other UI component libraries, and how difficult is it to customize? How does it differentiate itself in this crowded market of React component libraries?

Background

Radix Primitives is a library of accessible, unstyled React components, initially released in 2020. They can be adopted independently, and styled using any approach: CSS classes, Tailwind, CSS-in-JS, etc.

I recommend reading the Introduction page of their docs to understand what they’re about if you’re not familiar with headless component libraries.

But to summarize quickly, these collections of components implement common UI patterns found on the web, that aren’t provided by the HTML spec, but are well documented and understood by the web development community.

There’s a number of other headless component libraries in the React ecosystem.

There’s React Aria, which focuses on accessibility with hooks and components for the patterns mentioned above, or Headless UI, which prioritizes compatibility with Tailwind.

Other frameworks also have similar libraries.

How to use unstyled components

How does it work in practice? Let’s look at some code adapted from the Radix Primitives docs:

import * as React from 'react';
import * as Popover from '@radix-ui/react-popover';
import './styles.css';

const PopoverDemo = ({ triggerContent, popoverContent }) => (
  <Popover.Root>
    <Popover.Trigger className="PopoverTrigger">
      {triggerContent}
    </Popover.Trigger>
    <Popover.Portal>
      <Popover.Content className="PopoverContent">
        {popoverContent}
        <Popover.Arrow className="PopoverArrow" />
      </Popover.Content>
    </Popover.Portal>
  </Popover.Root>
);

export default PopoverDemo;

It’s quite straightforward:

Import the building blocks of the pattern you want to implement, which, in this case, are exported as a compound component.
Create the structure using the component parts you imported.
Add styles, either with className as shown above, or with your preferred CSS solution.

An unstyled component library such as Radix Primitives lets you abstract away the accessibility rabbit-hole and focus on the differentiating factor of your application, instead of reimplementing patterns that really should be part of the HTML spec.

Overall, Primitives are an excellent choice for developers looking to implement their own design system.

Radix Themes

Moving on to Themes, an interesting release built on top of Radix Primitives.

It’s a bit hard to define, and determine where it falls in the component library market.

I’d like to say it’s a theming library for Primitives, but it appears be more limited than that. I’d want to compare it favorably to Theme UI, but the latter is fully customizable, while Themes restrict you to the following tokens:

If you’re expected to accept the look and feel of the components provided, in order to simplify development of simple pages and prototypes, I fear we’ll again see an endless stream of recognizable designs à la TailwindUI. A bunch of landing pages looking exactly the same, with slight differences in color schemes.

What if you want to build a completely different UI, using the Themes components, would it make any sense or should you use Primitives directly? Here’s what one of the co-founders of Radix UI had to say about the distinction between themes and primitives:

Totally, this is the idea. Primitives are great if you want full control to build your own design system from scratch. But a lot of folks are looking for something that helps them get started faster, with great design choices already baked in.
— Stephen Haney (@sdothaney) August 9, 2023

And here’s what the announcement stated about styles:

Let’s talk about styles.

1️⃣ Is Radix Themes a styling solution? – No.
2️⃣ Are you expected to write styles? – Sometimes, more if you feel adventurous.
3️⃣ I want to use Radix Themes with my favourite CSS tech. Will it work? – Yes!
— Radix by WorkOS (@radix_ui) August 8, 2023

So it’s not a styling solution, but you should be able to modify the components to fit your requirements.

Radix Themes in practice

After playing around with Themes in a quickly scaffolded React app, here’s my conclusion: while styling is possible, I wouldn’t say all components make it easy.

For example, changing the border color of the Card component requires either overwriting or disabling box-shadow on an ::after pseudo-element using !important, then setting a border on its child div rather than the component itself.

You’ll need to put in some effort and dig into the source code or devtools to understand where and how the built-in styles are applied.

So it’s definitely not a styling solution for Radix Primitives, which I would have loved to see. Instead, it’s a themeable component library, limited in its customization options.

Conclusion

For a custom design, better use Primitives directly, along with a token-based styling solution provided by another library.

If, on the other hand, you’re happy with the look and feel of Radix Themes, and you’re trying to build something quickly, understanding that moving to your own design system later would require a rewrite to Primitives, Radix Themes might be a good pick.

As with all pre-styled component libraries, you’re gaining speed now in exchange of a larger maintenance burden later, should you decide to give your project its own visual identity.

The key is in understanding those trade-offs.

Separation of concerns

Tue, 08 Aug 2023 00:00:00 GMT

Software development dogmas can take a long time to die.

Take Separation of concerns, an important principle of computer science, which, if not understood properly, leads to programs sectioned along inefficient, sometimes arbitrary lines.

This confusion can be seen in a type of recurring comment, an unfunny and unintentional meme, that we see in online discourse. It goes something like that:

HTML, CSS and JS being distinct languages, they are separate concerns.
Modern component frameworks are bad, because they break this rule.

Now, let me preface this discussion by noting that it specifically applies to web application development.

If you’re not building a highly interactive application, in a component-driven way, your concerns might be different than the ones described here.

With that out of the way, are the concerns of Structure, Style, and Interactivity really separate?

Components in other languages

If one were to design a language from scratch today, whose purpose is to build interactive applications, would they divide it into three? One language to create the structure of the component, another to style the component and one more to define its behavior?

I doubt anybody would think this is a good idea. Sounds pretty damn dumb if you ask me.

Yet, we find people claiming that this is how web apps should be built, supporting their argument with the fact that HTML, CSS and JS are three different languages, thus three different “concerns”, as if oblivious to the historical context of how web technologies came to be.

The web is HTML, CSS and JavaScript because it evolved from a read-only document sharing system, that later gained its styling and interactive capabilities, not because those technologies are the optimal UI development paradigm.

Let’s use a modern example by looking at SwiftUI, a somewhat recent approach to building user interfaces. Here’s some code pulled from their docs:

Button(/* */) {
  Label("Refill Water", systemImage: "arrow.clockwise")
    .foregroundStyle(.secondary)
    .frame(maxWidth: .infinity)
    .padding(.vertical, 8)
    .padding(.horizontal, 12)
    .background(.quaternary, in: .containerRelative)
}

You’ll notice that the notion of separating styling from the component structure is absent here.

Now, I’m not pointing to SwiftUI as the definitive source for UI development. My own experience indicates that this approach is more efficient than separating structure and style.

I’ve seen monolithic CSS files climb to thousands of lines, and methodologies such as BEM to try and rein in the chaos, but nothing is as simple and elegant as component-scoped styles.

Presentation as a specific concern

Different frameworks handle styling differently, but most embrace the idea of component encapsulation.

Having external styles impact your components in a cascade, originating from outside to dictate the appearance of child elements makes reasoning about, and debugging styles more challenging, requiring the developer to constantly keep extra context in mind.

If you find yourself asking “Where is this CSS coming from?”, there’s an issue with your architecture. Your concerns are so well separated that you have no clue what’s going on.

HTML, CSS and JS serve the same concern: presenting data. This is why frameworks like Vue and Svelte bundle them into single-file components.

While React doesn’t prescribe a styling approach, and uses JSX rather than SFCs, the popularity of CSS-in-JS and Tailwind is undeniable.

Style encapsulation at the component level is more efficient and easier to work with, especially as the component library grows.

Let’s take a look at an example, this time using Theme UI, described as “a library for creating themeable user interfaces based on constraint-based design principles.”

To keep things simple, I’m pulling the example from their front page:

// Create your theme

import type { Theme } from 'theme-ui'

export const theme: Theme = {
  fonts: {
    body: 'system-ui, sans-serif',
    heading: '"Avenir Next", sans-serif',
    monospace: 'Menlo, monospace',
  },
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#33e',
  },
}

// Style your UI

/** @jsxImportSource theme-ui */
import { ThemeUIProvider } from 'theme-ui'
import { theme } from './theme'

export const App = () => (
  <ThemeUIProvider theme={theme}>
    <h1
      sx={{
        color: 'primary',
        fontFamily: 'heading',
      }}
    >
      Hello
    </h1>
  </ThemeUIProvider>
)

Notice how style information is defined as data in the theme, which is then used in the JSX template via the sx prop.

Again, I’m not advocating for a specific library here; I’m using this example to illustrate that web technologies collectively address the same presentation concern, which includes both structure and style.

Conclusion

In the era of component-based UI frameworks, structure, style, and interactivity are not individual “concerns” that should be separated. They collectively serve the same fundamental presentation concern.

Web technologies evolved into what they are today to bring new capabilities to the platform. We shouldn’t limit ourselves to a dogmatic separation of those technologies that idolizes a perceived purity over practical efficiency.

Good abstractions should be discovered, rather than created. As you work in a codebase, its different concerns become readily apparent. In a web application, they may be things like data fetching, state management, and business logic, not the artificial boundaries between HTML, CSS, and JS.

So, the next time you hear someone mention “separation of concerns” as if the phrase itself were an argument, feel free to challenge them and ask what concerns they’re trying to separate. Chances are they haven’t put much thought into it.

How to prevent Theme UI color mode flash

Sat, 18 Feb 2023 00:00:00 GMT

Back when Theme UI was first introduced, the prefers-color-scheme media query didn’t exist. You’d have a button on the website to switch between light and dark mode, or any other color scheme provided by the site’s developers.

This worked well, until the standardization of the color scheme media query. Nowadays, most websites implement color schemes by responding to the user’s preference via CSS.

To work with this new expectation, Theme UI introduced the system color mode, which would respond to the prefers-color-scheme media query.

However, this functionality is implemented in JavaScript, not in CSS, so there can be a color mode flash on initial page load, because the document is rendered before the JS bundle is evaluated.

Reading through the source code linked above, you can’t help but wonder why this system wasn’t scrapped entirely. It feels incredibly overengineered by today’s standards, where a CSS media query along with an event listener would do the trick.

It’d be great if we could opt out of this behavior, but alas, we can’t. So here’s a hack that will prevent the color flash to occur:

if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
  document.documentElement.classList.add('theme-ui-dark');
} else {
  document.documentElement.classList.add('theme-ui-__default');
}

window
  .matchMedia('(prefers-color-scheme: dark)')
  .addEventListener('change', (event) => {
    if (event.matches) {
      //dark mode
      document.documentElement.classList.remove('theme-ui-__default');
      document.documentElement.classList.add('theme-ui-dark');
    } else {
      //light mode
      document.documentElement.classList.remove('theme-ui-dark');
      document.documentElement.classList.add('theme-ui-__default');
    }
  });

Note that for this hack to work, it needs to block rendering, so you have to add it in a <script> before the closing </head> tag.

Methods will vary depending on the framework; I added it as a child of <Helmet> for my site. As far as I can tell, there is no perceptible performance impact.

You might wonder how this hack even works. The reason is Theme UI ships a set of CSS custom properties for each color mode with the initial document request.

The CSS looks like this:

html {
  --theme-ui-colors-text: #1c1917;
  --theme-ui-colors-background: #fafafa;
}

html.theme-ui-__default,
.theme-ui-__default html {
  --theme-ui-colors-text: #1c1917;
  --theme-ui-colors-background: #fafafa;
}

html.theme-ui-dark,
.theme-ui-dark html {
  --theme-ui-colors-text: #f5f5f5;
  --theme-ui-colors-background: #171717;
}

If you open the devtools and switch between color schemes, you’ll notice that Theme UI replaces the values of the CSS custom properties set on the html tag, the first block in the above example.

Our script overrides Theme UI’s handling of color modes entirely, by instead switching the class on the html tag between theme-ui-dark and theme-ui-__default.

The higher specificity of classes mean that whatever is set on html is irrelevant.

Be aware that Theme UI’s behavior could change in the future, make sure you read the release notes before upgrading major versions.

How to use PostGIS with Prisma

Sun, 03 Jul 2022 00:00:00 GMT

At the time of writing, Prisma doesn’t support PostGIS. However, we can still make spatial queries using raw database access. The setup is fairly simple, but it’s not documented so this posts goes into that.

Requirements

You’ll need to use raw queries, so some SQL knowledge is required.

To actually work with spatial data, you’ll also need to understand how PostGIS works and what functions are available.

There’s surprisingly little information for PostGIS beginners online and the documentation is quite difficult to navigate unless you know exactly what you’re looking for, so I’ll go over the basics in the next section.

If you want a complete course, I used the LearnSQL.com PostGIS course and can easily recommend it.

Feel free to skip to Installing PostGIS if you just want the Prisma setup.

PostGIS basics

There are two types of spatial data in PostGIS: geometry and geography:

Geometry is for 2D calculations: faster, but inaccurate at global scale.
Geography is for 3D calculations: exact, but slower.

That’s because geometry calculates on a map projection (a plane) while geography takes the actual shape of the earth (a globe) into account. In most cases, you’ll want to use geometry, and this is what this post assumes.

In PostGIS, X refers to the longitude (vertical lines) and Y refers to the latitude (horizontal lines).

There are 3 basic subtypes of geometries:

POINT(X Y)
LINESTRING(X Y, X Y, ...)
POLYGON((X Y, X Y, ...), (X Y, X Y, ...), ...)

Finally, you can interact with spatial data through PostGIS functions. Here are a few examples:

Function	Example	Description
ST_MakePoint	`ST_MakePoint(-71.1043443253471, 42.3150676015829);`	Creates a `POINT` from coordinates that can be inserted into a geometry column
ST_Distance	`ST_Distance(A, B);`	Returns the smallest distance between two geometries
ST_DWithin	`ST_DWithin(A, B, distance);`	Returns true if `A` and `B` are within `distance` of each other

What SRID should I use?

The SRID is a unique identifier for a specific coordinate system. There are worldwide and local systems as well as systems in degrees or meters.

From what I understand, EPSG:4326 appears to be the standard global coordinate system using degrees (latitude and longitude) and EPSG:3857 is the system used by web mapping applications such as Google Maps.

For my project, I opted to store coordinates as 4326. If I need a distance in meters, I’ll convert to 3857 using ST_Transform.

For more info, see this StackExchange answer.

Installing PostGIS

First, you need to make sure that your database supports PostGIS.

In most cases, managed cloud PostgreSQL databases enable it out of the box. If you’re working locally, I suggest you take a look at the installation instructions for your platform.

I opted for Postgres.app which conveniently includes PostGIS. Highly recommend it if you’re on macOS and want a simple setup.

Adding PostGIS support to Prisma

Since Prisma 4.0, extendedIndexes is Generally Available. If you’re not on version 4 yet, you’ll need to enable some preview features.

Here’s the schema we’ll be using as an example:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider        = "prisma-client-js"
  binaryTargets   = "native"

  // preview features to enable if not on v4:
  previewFeatures = ["extendedIndexes", "improvedQueryRaw"]
}

// we'll assume we had this simple model before enabling postgis
model Location {
  id        Int      @id
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Now, to be able to run PostGIS functions on the Location table, we’ll add the following lines:

model Location {
  id        Int      @id
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  // the geometry column itself
  coords    Unsupported("geometry(Point, 4326)")

  // the index for that column
  @@index([coords], name: "location_idx", type: Gist)
}

Let’s break this down:

The Unsupported field type tells Prisma Migrate to use a specified type for a column. This data will not be available to the Prisma Client. More info in the Prisma docs.
Unsupported doesn’t work on its own, so we give it a type. It could be as simple as "geometry", but here we also specify one of the subtypes and SRIDs seen above.
The index is still confusing to me. I’m told you need to use it. I understand the reasoning behind its usage, but I couldn’t describe exactly what it does. Database stuff ¯\_(ツ)_/¯.

Note: Prisma versions 4.5 and above support PostgreSQL extensions through a preview feature. There shouldn’t be any problem during migration if you enable it, so the following section will not be relevant.

If we attempt to migrate at this stage, we’ll most likely encounter this error:

Error: db error: ERROR: type "geometry" does not exist
   0: sql_migration_connector::apply_migration::apply_migration
             at migration-engine/connectors/sql-migration-connector/src/apply_migration.rs:9
   1: migration_core::state::SchemaPush
             at migration-engine/core/src/state.rs:349

That’s because the PostGIS extension needs to be created in the database before we can use its types and functions. To do that, run the following command:

prisma migrate dev --create-only

This will create a SQL migration without applying it, thus allowing you to modify it. The migration file will look like this:

-- AlterTable
ALTER TABLE "Location"
ADD COLUMN "coords" geometry(Point, 4326);
-- CreateIndex
CREATE INDEX "location_idx" ON "Location" USING GIST ("coords");

Add the following statement on top:

-- create postgis extension
CREATE EXTENSION postgis;
-- AlterTable
[...]

You can now apply the migration:

prisma migrate dev

And that’s it! Your can now send PostGIS-enabled raw queries to your database. The development experience is far from what we’re used to with Prisma, but while we wait for native support, it’s better than nothing.

Why I chose Gatsby (again) for my developer blog

Thu, 19 May 2022 00:00:00 GMT

Working on a side project, I encountered some technical problems that would make for interesting blog posts. I wrote them, but didn’t want to publish on my website as it looked and felt outdated to me.

I built it in 2019, and it didn’t change much since then. A makeover was long overdue.

The framework rabbit hole

The previous iteration of my website used Gatsby, but the blog itself relied on an external theme that wasn’t maintained anymore. This time, I wanted control over my blog platform.

In an attempt to ship without delaying my side project, I spun up a repo based on my twin-macro-next-boilerplate template. I knew that comparing all different frameworks would be a waste of time, so I went with what I use most frequently.

But something felt off.

I like building web apps with Next.js due to its flexibility, but for a static blog, it’s not ideal.

Filesystem routing with Markdown files isn’t that great if you want a different structure in the repo than on the blog. The alternative would be to use the Next.js data fetching functions to parse Markdown manually and generate slugs, which isn’t a big deal, but again, not ideal.

What about using astro instead, a fairly new static site generator (SSG) which promises “peak performance”?

I seriously considered it until I generated the blog starter. I was faced with the prospect of learning yet another framework, and either starting from scratch or customizing a bloated starter. And to be fair to other SSGs, there’s no perceptible difference in load times unless you’re on a slow 3G connection.

Not what I was looking for, so I briefly explored using Remix, but felt it was overkill for a simple static site. All I really needed was a Markdown-based blog so I could get back to my side project.

You see where this is going. I fell into the trap I was trying to avoid: analysis paralysis. When all options seem equally good, with different tradeoffs, it can be hard to make a decision.

So what’s the solution?

A familiar ally

A thought remained in the back of my mind as I was exploring all these frameworks: just use Gatsby again. I like its GraphQL data loader, its performance is great, it handles the developer blog scenario well, and most of all: I know how it works.

Here’s a quick rundown of its benefits in case you’re in the same paralysed boat:

Why Gatsby

At first glance, Gatsby can look more limited that other options because of its approach to data loading.

While other frameworks such as Next.js provide a completely flexible loader, Gatsby hands you a large set of lifecycle hooks that allow you to customize its GraphQL-based data loader.

This “limited” architecture is exactly its strength. It enables the community to share plugins, and developers to inspect all available data at any time through the GraphiQL explorer.

Out of the box, Gatsby does a lot for you. The blog starter is easy to understand and customize, and the plugin ecosystem makes adding common and non-trivial functionality easy.

For example, here’s all the code this blog needs for build-time syntax highlighting compatible with VSCode themes:

// under `gatsby-transformer-remark` plugins:
{
  resolve: `gatsby-remark-vscode`,
  options: {
    theme: {
      default: 'Eva Light Bold',
      dark: 'Eva Dark',
    },
    extensions: ['Eva-Theme/VSCode', 'vscode-graphql'],
  },
},

I’d say Gatsby’s good enough.

There’s value in doing R&D and exploring all different options, but sooner or later a decision has to be made. If the end result would be similar with all options, familiarity with a technology should be taken into account.

How to throw an error from an invoked child machine to a parent in xstate

Sun, 24 Apr 2022 00:00:00 GMT

The basic syntax for invoking a child machine is the same as for invoking promises or any other service:

// ...
current_state: {
  invoke: {
    src: childMachine,
    data: {}, // optional initial context
    onDone: {
      target: 'next_state',
      actions: 'someAction',
    },
    onError: {
      target: 'error',
      actions: 'printError',
    }
  },
},

When you invoke a promise, an error thrown inside will automatically trigger the onError block. You could expect the same thing to happen when invoking a child machine and throw an error like so:

// ...
states: {
  fetch: {
    invoke: {
      src: 'fetchSomething',
      onDone: { target: 'upsert', actions: 'someAction' },
      onError: {
        actions: (_, event) => {
          throw event.data
        },
      },
    },
  },
  upsert: {
    // ...
  },
  success: {
    type: 'final',
  },
},

The problem

However, this doesn’t work, and the “Invoking services” docs only mention sendParent as a way to communicate from child to parent machine.

You could use sendParent to solve the issue, but you’d need to send a custom event from your child machine and handle it in the parent, outside of the onError block:

// ... child machine
actions: {
  throwError: sendParent((_, event) => ({
    type: 'CHILD_ERROR',
    data: event.data,
  })),
},

// ... parent machine
current_state: {
  invoke: {
    src: childMachine,
    data: { /* ... */ },
    onDone: { /* ... */ },
  },
  on: {
    CHILD_ERROR: {
      target: 'error',
      actions: 'printError',
    },
  },
},

That’s actually what I did until a friendly discord user pointed me in the right direction.

The solution

Turns out the answer was in the “Actions” page of the docs, under the escalate action, which “escalates an error by sending it to the parent machine.” Exactly what we need.

Here’s how you’d refactor the throwError action so that it would trigger the onError block of the parent:

// ...
throwError: escalate((_, event) => ({
  data: event.data,
})),

How to test xstate machines invoking async code in Jest

Fri, 22 Apr 2022 00:00:00 GMT

I’m writing a complex state machine which invokes a number of promises. Those promises are calls to an external API or to the database.

The tests use msw to mock API calls, and a test database which is seeded and torn down before and after each test.

Since my state machine moves from one state to another sequentially, I opted to test that my implementation was correct at each step. Here’s an example, adapted from the xstate docs:

describe('call_locations_api', () => {
  it('should save locations to context on success and go to compare step', (done) => {
    interpret(updateLocationsMachine)
      .onTransition((state) => {
        if (state.matches('compare')) {
          expect(state.context.locations).toStrictEqual(locations);
          done();
        }
      })
      .start();
  });
});

I actually used an async/await variation, but for the sake of this article I’m using the done() callback as presented in the docs. The result is the same.

The problem

While tests fail or succeed as expected, the machine continues until it reaches a final state, logging a bunch of database errors to the console or worst, making API calls after the msw listener closes.

Calling done() only ends the test, not the machine itself.

The solution

Hidden under the “Interpreting machines” page of the xstate docs is a section about waitFor, which contains the following snippet:

const myFunc = async () => {
  const actor = interpret(machine).start();

  const doneState = await waitFor(actor, (state) => state.matches('done'));

  console.log(doneState.value); // 'done'
};

Huh, this is quite similar to the test code. Two key differences:

We keep a reference to the interpreted machine (actor).
The asynchronous nature of the code is explicit.

Adapting that to a test function, we can refactor our code:

import { waitFor } from 'xstate/lib/waitFor';

describe('call_locations_api', () => {
  it('should save locations to context on success and go to compare step', async () => {
    const actor = interpret(updateLocationsMachine).start();

    const state = await waitFor(actor, (state) => state.matches('compare'));

    expect(state.context.locations).toStrictEqual(locations);

    actor.stop();
  });
});

Keeping a reference to the machine (actor) allows us to stop it at the end of the test.

This solves the problem by preventing the state machine from persisting and, as a bonus, it makes the code more readable by extracting the assertion from the interpret block.

How to whitelist dynamic Tailwind classes in PurgeCSS

Fri, 13 Dec 2019 00:00:00 GMT

I was building an array of colorful tags to use in my PortfolioCard components.

Since many cards could share the same tags, I didn’t want to declare colors in my data. It would have led to repetition that would be problematic if I ever needed to change them.

I opted instead to use Gatsby’s Node APIs to transform my array of tag names into an array of objects at build time.

I’d maintain an object whose keys correspond to the tag names in my data, and whose values are an array, where the first item is a background color and the second is a text color:

const TAG_COLORS = {
  javascript: ['bg-yellow-vivid-400', 'text-gray-900'],
  react: ['bg-blue-400', 'text-gray-900'],
  gatsby: ['bg-purple-700', 'text-purple-100'],
  ...
};

So this JSON data:

"tags": ["javascript", "react", "gatsby", "jest"]

is converted into this JavaScript array to be consumed by my Tags component:

[
  { name: 'javascript', color: ['bg-yellow-vivid-400', 'text-gray-900'] },
  { name: 'react', color: ['bg-blue-400', 'text-gray-900'] },
  { name: 'gatsby', color: ['bg-purple-700', 'text-purple-100'] },
  { name: 'jest', color: ['bg-red-vivid-800', 'text-white'] },
];

Here’s what the rendered component looks like:

The problem

Since my CSS classes are injected into the component at build time, PurgeCSS isn’t aware of them.

const Tag = ({ name, color }) => (
  <span className={`${color[0]} ${color[1]} inline-block rounded-lg ...`}>
    {name}
  </span>
);

See how these two color classes are variables as opposed to others classes who are static?

That’s why I needed to use the whitelist configuration option. But there’s no way I would be copy pasting classes around and manually managing a whitelist.

The solution

We need to get all the TAG_COLORS values and convert them to an array of strings that the PurgeCSS whitelist option will accept.

A simple function does the trick:

const whitelistedClasses = Object.values(TAG_COLORS).reduce(
  (whitelistedColors, currentColors) => [
    ...whitelistedColors,
    ...currentColors,
  ],
  [],
);

Object.values(TAG_COLORS) does what its name implies and returns an array of values.

Those values are arrays themselves, so we need to reduce everything to a single array. No need to worry about duplicates, PurgeCSS is smart enough to either filter or ignore them.

All we need to do now is import whitelistedClasses into our config and the problem is solved!

I’m using the Gatsby plugin so here’s how to do it in gatsby-config.js:

const { whitelistedClasses } = require('./src/utils/tags');

module.exports = {
  plugins: [
    ...,
    {
      resolve: `gatsby-plugin-purgecss`,
      options: {
        tailwind: true,
        whitelist: whitelistedClasses,
      },
    },
  ],
};

So there you go, now you don’t have to worry about copy pasting classes around every time you update a list of colors.

Of course, this is a pretty specific issue to encounter. But the idea behind this post can be applied to many situations.

Manually managing duplicate data is inefficient and can lead to buggy code if this data isn’t kept in sync. Instead, make sure that your data flows from one place to the other.

How to source images and data from JSON files in Gatsby

Sun, 01 Dec 2019 00:00:00 GMT

When I started building the portfolio section of my personal site, I encountered a small problem.

I was building cards that contained both data and image and I wanted everything to appear under the same GraphQL node. Turns out there’s no way for Gatsby to recognize a path to an image in a JSON file by default.

Additionally, I needed to do some processing on the tag data before it could be usable so I started searching for a solution that would handle both cases.

Here’s what a card looks like:

The problem

I wanted to achieve two things:

Process the tag array and turn it into a usable array of objects
Have Sharp process the image and get the resulting node in the same tree

My first reflex was to go for gatsby-transformer-json, but I quickly realized that this transformer wouldn’t understand that I had image paths in my data, much less process them using Sharp.

On top of it, I couldn’t preprocess my tag array nor give a specific shape to my PortfolioCard node.

Back to the docs. I knew that I needed to source images from the filesystem so I started there. The documentation was helpful in that regard.

I recommend you have a read if you’ve never done this, but here’s a summary of what you need to do:

Install the following plugins with yarn:

yarn add gatsby-image gatsby-source-filesystem gatsby-plugin-sharp gatsby-transformer-sharp

or using npm:

npm install gatsby-image gatsby-source-filesystem gatsby-plugin-sharp gatsby-transformer-sharp

Add the plugins to your gatsby-config.js:

const path = require(`path`);

module.exports = {
  ...
  plugins: [
    `gatsby-transformer-sharp`,
    `gatsby-plugin-sharp`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        // provide the path to your image folder here:
        path: path.join(__dirname, `src`, `assets`),
      },
    },
    ...
  ],
};

Now if you go to your GraphiQL IDE (by default Gatsby serves it on http://localhost:8000/___graphql) you’ll see an allImageSharp field which you can use to query your images processed by Sharp.

That’s great, but not exactly what I wanted.

These image nodes should appear under the corresponding PortfolioCard tree with the rest of the associated data. Not on a top-level node that I would have to query separately using the name of the image obtained in a previous query.

The solution

With some research, I ended up on sourceNodes in the Gatsby Node APIs docs.

I understood that using this API, I could grab data from the filesystem, transform it and build a node in the shape that suited my needs.

Here’s the result of my work in a step-by-step format. I’ll be using code examples from my own website so feel free to browse the source code on GitHub should you need to.

Sourcing the data

The first thing we need to do is to get the JSON data in the gatsby-node.js file.

If we were to write a plugin handling a number of use cases, we’d need to read from the filesystem using Node to source the data. But because we’re targeting a specific use case, hard coding the paths to our JSON files is the simplest thing to do:

const path = require('path');
const portfolio = require('./src/data/portfolio.json');
const colors = require('./src/data/tag_colors.json');

// relative path from `gatsby-node.js`
const IMAGE_PATH = './src/assets/';

For reference, here’s portfolio.json:

[
  {
    "title": "NessIA.ca",
    "category": "Business website",
    "description": "Built for a client operating in the Business Intelligence space...",
    "technology": "The tool of choice these days for blazing fast websites is Gatsby...",
    "link": "https://nessia.ca/en",
    "image": "nessia.png",
    "alt": "NessIA homepage",
    "tags": ["javascript", "react", "gatsby", "bulma"]
  },
  ...
]

and tag_colors.json:

{
  "javascript": "bg-yellow-vivid-400 text-gray-900",
  "react": "bg-blue-400 text-gray-900",
  "gatsby": "bg-purple-700 text-purple-100",
  ...
}

Now that we have access to our data, we need to build a node by adapting the code example from the docs to fit our objects.

In this example, we need to iterate over an array and build a node for each portfolio card, so all our code will be written inside a forEach loop:

exports.sourceNodes = ({ actions, createNodeId, createContentDigest }) => {
  portfolio.forEach((card) => {
    // 1. Extract the card data.
    const { title, category, description, technology, link, image, alt, tags } =
      card;

    // 2. Build the PortfolioCard node. Note that most fields simply correspond to
    //    to our JSON data.
    const node = {
      title,
      category,
      description,
      technology,
      link,
      image, // <----- Problem here
      alt,
      tags, // <------ and here
      id: createNodeId(`card-${title}`),
      internal: {
        type: 'PortfolioCard',
        contentDigest: createContentDigest(card),
      },
    };

    // 3. Create the node
    actions.createNode(node);
  });
};

That’s a good start. Our data now exists in a top-level node called allPortfolioCard. But what happens if we query it?

query {
  allPortfolioCard {
    nodes {
      alt
      category
      description
      image
      link
      tags
      technology
      title
    }
  }
}

As expected, we have a couple of issues. Both image and tags need to be processed before they can be usable.

{
  "data": {
    "allPortfolioCard": {
      "nodes": [
        {
          "alt": "NessIA homepage",
          "category": "Business website",
          "description": "Built for a client operating in the Business Intelligence space...",
          "image": "nessia.png",
          "link": "https://nessia.ca/en",
          "tags": ["javascript", "react", "gatsby", "bulma"],
          "technology": "The tool of choice these days for blazing fast websites is Gatsby...",
          "title": "NessIA.ca"
        },
        ...
      ]
    }
  }
}

Let’s start with our tags array.

Processing JSON data

Right now, we have an array of strings that needs to be transformed into an array of objects with the properties name and color:

[
  {
    "name": "javascript",
    "color": "bg-yellow-vivid-400 text-gray-900"
  },
  ...
]

This is a fairly simple fix. We have the color data already imported in our gatsby-node.js file. All we need to do is to map over the tag array when building our node and return an object:

const colors = require('./src/data/tag_colors.json');

exports.sourceNodes = ({ actions, createNodeId, createContentDigest }) => {
  portfolio.forEach((card) => {
    // ...

    const node = {
      // ...
      tags: tags.map((name) => ({
        name,
        color: colors[name],
      })),
      // ...
    };

    actions.createNode(node);
  });
};

The following query will now be possible:

query {
  allPortfolioCard {
    nodes {
      tags {
        color
        name
      }
    }
  }
}

And will return the following data:

{
  "data": {
    "allPortfolioCard": {
      "nodes": [
        {
          "tags": [
            {
              "color": "bg-yellow-vivid-400 text-gray-900",
              "name": "javascript"
            },
            {
              "color": "bg-blue-400 text-gray-900",
              "name": "react"
            }
            // ...
          ]
        }
        // ...
      ]
    }
  }
}

As you can see, when building a custom node, we can do whatever we want with the data. We can pass it down as it is or transform it into a desired shape.

But what about the image field?

Transforming an image path into a `childImageSharp` node

Now that’s the tricky part.

It took a bit of digging, but I learned from this Stack Overflow answer that in order for Sharp to transform an image, it needs to be a File node.

So all we need to do is to create such a node by giving it the required fields.

gatsby-transformer-sharp only checks if a node has the field ‘extension’ and — if it is one of the valid file types — processes it. Derek Nguyen on Stack Overflow

The whole answer is worth reading to deepen your understanding of how Gatsby operates under the hood. Let’s go ahead and implement it.

exports.sourceNodes = ({ actions, createNodeId, createContentDigest }) => {
  portfolio.forEach((card) => {
    // ...

    // 1. name, extension and absolute path are required to build a File node
    const { name, ext } = path.parse(image);
    const absolutePath = path.resolve(__dirname, IMAGE_PATH, image);

    // 2. Build a data shape that corresponds to a File node that Sharp can process
    const data = {
      name,
      ext,
      absolutePath, // <-- required
      extension: ext.substring(1), // <-- required, remove the dot in `ext`
    };

    // 3. Build the image node using our data
    const imageNode = {
      ...data,
      id: createNodeId(`card-image-${name}`),
      internal: {
        type: 'PortfolioCardImage',
        contentDigest: createContentDigest(data),
      },
    };

    // 4. Create the node. When imageNode is created,
    //    Sharp adds childImageSharp to the node
    actions.createNode(imageNode);

    const node = {
      // ...
      // 5. Add the image node to our tree
      image: imageNode,
      // ...
    };

    actions.createNode(node);
  });
};

Now when you go back to your Graph Explorer, your should see a childImageSharp node under the image field.

You can then query for it and use it in conjunction with gatsby-image.

Here’s what the final query looks like:

query {
  allPortfolioCard {
    nodes {
      image {
        childImageSharp {
          fluid(maxWidth: 384) {
            ...GatsbyImageSharpFluid
          }
        }
      }
      alt
      category
      description
      technology
      link
      tags {
        color
        name
      }
      title
    }
  }
}

Gatsby is pretty powerful out of the box, and even more once you start understanding how it works. I’m still barely scratching the surface but the more I play with it, the more I’m amazed with what it can do.

The key takeaway here is that whether you need to process your data before sending it to your GraphQL tree, or you need images processed by gatsby-plugin-sharp under a specific node, using the sourceNodes API in conjunction with the createNode action will help you achieve your goals.

Master Git, not the command line

Sat, 12 Oct 2019 00:00:00 GMT

Learning Git isn’t about memorizing commands. It’s about understanding version control. I suggest using a graphical user interface (GUI) instead of a command line interface (CLI) to do that.

The idea that using the command line exclusively makes you a better developer, or worse, a real developer™ , is misleading for newbies and even for more experienced developers. I’ve seen people from all levels carry this assumption, and I’ve seen this assumption limit the developer’s abilities every time.

Such a thought, when religiously adhered to by developers, is limiting their ability to do great work, to seek the best solution to the problem and to avoid basic mistakes. This can be adapted to any other area where developers tend to become zealous, but in my experience, Git and version control has been a good example.

That’s because there are amazing GUI tools for Git. I personally use GitKraken but any Git client with the same features would do the trick.

The main difference between the command line and a GUI is usability. Let’s examine using screenshots.

Here’s the interface when you use autocompletion on the command line. A list of all possible Git commands. Not so user friendly.

What ends up happening is that, rather than learning Git concepts, you end up memorizing specific commands and stay at the most basic level. Pull, push, branch, add, commit. That’s pretty much it.

But Git is more powerful than that. The issue with the command line is that you don’t see what’s available.

That “Fix typo” commit could have been squashed with the previous one before pushing. That “Saving changes” commit is cluttering the git history and is meaningless to anybody else but you at that exact point in time (try remembering what that commit was about a month later). Stashing your work in progress is what you’re most likely trying to do.

Here’s the difference when using a Git GUI with an intuitive interface. What’s interesting is that only relevant commands are displayed. And the interface adapts to your actions. It shows you what commands are available for a specific commit, or for a list of commits, or for a single file, or for many files… you get the idea.

What’s more is that it even makes you a better CLI Git user. Why? Because a GUI like GitKraken doesn’t hide anything from you. The command names are the same as the CLI. Not only will you learn Git concepts but you’ll learn the commands.

I won’t go on about what the GUI can do so if you want to know more, check out GitKraken’s feature page.

The purpose of this post was to show you that dogmatism in software development rarely leads to effectiveness and efficiency and to point out that what’s most important is to understand what you’re doing before trying to memorize how to do it.

If you want to start using GitKraken, feel free to use my invite link.

freddydumont's blog

How to add Custom Locations in Nginx Proxy Manager

Basic Setup

Adding WebSocket Custom Locations

Configure the Basic Fields

Configure Advanced Settings

Coolify example

For /app WebSocket:

For /terminal/ws WebSocket:

Troubleshooting

Generate D2 PNG diagrams in GitHub Actions

How to generate NixOS LXC templates in GitHub Actions

Solution

How to configure Vite to include additional folders

The solution

Explanation

Radix Themes vs Primitives

Background

How to use unstyled components

Radix Themes

Radix Themes in practice

Conclusion

Separation of concerns

Components in other languages

Presentation as a specific concern

Conclusion

How to prevent Theme UI color mode flash

How to use PostGIS with Prisma

Requirements

PostGIS basics

What SRID should I use?

Installing PostGIS

Adding PostGIS support to Prisma

Why I chose Gatsby (again) for my developer blog

The framework rabbit hole

A familiar ally

Why Gatsby

How to throw an error from an invoked child machine to a parent in xstate

The problem

The solution

How to test xstate machines invoking async code in Jest

The problem

The solution

How to whitelist dynamic Tailwind classes in PurgeCSS

The problem

The solution

How to source images and data from JSON files in Gatsby

The problem

The solution

Sourcing the data

Processing JSON data

Transforming an image path into a childImageSharp node

Master Git, not the command line

For `/app` WebSocket:

For `/terminal/ws` WebSocket:

Transforming an image path into a `childImageSharp` node