Microsoft Ergonomic Keyboard Acting Weird

2026-03-05T00:00:00+00:00

Here’s something that’s happened to me enough times that I’m writing about it:

My MS Ergo Sculpt keyboard is acting funny. It double types, or misses key strokes, adds unexpected tildes, flashes my terminal, or messes up my keyboard shortcuts, such as PasteBot’s cmd-shift-v.

In my many years of using this device I have found two solutions to the various ways my favorite keyboard acts up:

RF interference—my most common problem

Try moving the little USB dongle closer to the keyboard closer to the keyboard. Also try a regular USB-2 port if possible (i.e. not a blue-colored port, if available). Ever since I started connecting the dongle with a cheap USB extension cable, things have been great

A stuck key

I’m embarrassed to admit that each time this has happened, it’s taken me far too long to figure out. This usually happens to me when I have just cleaned my desk and wiped off my keyboard with a damp towel. The half-height function keys on this keyboard are easily jammed. Check each one to see if they are free. I seem to be really good at getting the F5 key stuck.

When one of those is jammed, my computer acts very strangely. When this happened today it took writing a quick little keylogger to figure out what was happening.

I wrote this:

#!/usr/bin/env python3

import Quartz
import sys

def key_callback(proxy, type_, event, refcon):
    if type_ == Quartz.kCGEventKeyDown:
        keycode = Quartz.CGEventGetIntegerValueField(
            event, Quartz.kCGKeyboardEventKeycode
        )

        chars = Quartz.CGEventKeyboardGetUnicodeString(event, 10, None, None)
        # chars returns tuple(count, string)
        if chars and chars[1]:
            text = chars[1]
        else:
            text = ""

        print(f"keycode={keycode} text='{text}'", flush=True)

    return event

def main():
    tap = Quartz.CGEventTapCreate(
        Quartz.kCGSessionEventTap,
        Quartz.kCGHeadInsertEventTap,
        Quartz.kCGEventTapOptionDefault,
        Quartz.CGEventMaskBit(Quartz.kCGEventKeyDown),
        key_callback,
        None,
    )

    if not tap:
        print("Failed to create event tap. Grant Accessibility permissions.", file=sys.stderr)
        sys.exit(1)

    runloop_source = Quartz.CFMachPortCreateRunLoopSource(None, tap, 0)
    Quartz.CFRunLoopAddSource(
        Quartz.CFRunLoopGetCurrent(),
        runloop_source,
        Quartz.kCFRunLoopCommonModes,
    )

    Quartz.CGEventTapEnable(tap, True)
    print("Listening for global key presses...")
    Quartz.CFRunLoopRun()

if __name__ == "__main__":
    main()

And ran it with this:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install pyobjc-framework-Quartz
python ./keylogger.py

The first time you run it, you’ll need to approve it in Accessibility settings. Then run it again.

Then hammer the keyboard until the weirdness happens. In my case it immediately went nuts:

ckeycode=9 text='v'
vkeycode=7 text='x'
xkeycode=8 text='c'
ckeycode=9 text='v'
keycode=96 text=''
v^[[15~keycode=96 text=''
^[[15~keycode=96 text=''
^[[15~keycode=96 text=''
^[[15~keycode=96 text=''
^[[15~keycode=96 text=''
^[[15~keycode=96 text=''
^[[15~keycode=96 text=''

# ...lots of repeating, without me pressing anything

Then I looked up keycode 96 and saw it was F5. Sure enough, that key was jammed.

I was pretty close to buying a new keyboard 😮‍💨.

Crudely capture working files

2026-02-27T00:00:00+00:00

We recently had a situation where a tool was:

Creating a work directory, e.g. job-1234 (randomly generated)
Doing some stuff there
Deleting the work directory

That middle step wasn’t working quite right so we wanted to inspect it before it vanished. For complicated reasons, it was tricky to pause the tool before step 3 so here’s what we did:

Watch for the working folder and just clone it every 1 second:

# PowerShell script to backup directories with timestamp extensions
# Usage: 
#   cd C:\path\to\directory
#   .\monitor-folder.ps1

# Use current working directory where the script is run from
$TargetDirectory = Get-Location

Write-Host "Monitoring directory: $TargetDirectory" -ForegroundColor Green
Write-Host "Backing up directories every 1 second..." -ForegroundColor Green
Write-Host "Press Ctrl+C to stop..." -ForegroundColor Yellow
Write-Host ""

while ($true) {
    $timestamp = Get-Date -Format "HH.mm.ss"
    
    # Get all directories directly in the target directory (not recursive)
    $directories = Get-ChildItem -Path $TargetDirectory -Directory
    
    foreach ($dir in $directories) {
        # Skip directories that are already backups
        if ($dir.Name -like "*.bak") {
            continue
        }
        
        $backupName = "$($dir.Name).$timestamp.bak"
        $backupPath = Join-Path $TargetDirectory $backupName
        
        try {
            # Copy directory recursively - continue even if some files are in use
            Copy-Item -Path $dir.FullName -Destination $backupPath -Recurse -Force -ErrorAction Continue
            Write-Host "[$(Get-Date -Format 'HH:mm:ss')] Backed up: $($dir.Name) -> $backupName" -ForegroundColor Cyan
        }
        catch {
            Write-Host "[$(Get-Date -Format 'HH:mm:ss')] WARNING: Partial backup of $($dir.Name) (some files may be skipped)" -ForegroundColor Yellow
        }
    }
    
    Start-Sleep -Seconds 1
}

With that running, the job came and went, and left behind what we needed:

- job-1234-10.57.12.bak
- job-1234-10.57.13.bak
- job-1234-10.57.14.bak
- job-1234-10.57.15.bak
- job-1234-10.57.16.bak
- job-1234-10.57.17.bak

There are lots of ways to solve this problem, but this one was good enough for what we needed and extremely simple to generate and execute.

Drain Octopus Deploy workers for patching

2025-03-11T00:00:00+00:00

If you reboot a Linux Octopus worker while a deploy is running, that deploy will fail. It’s better to decluster it during routine patching/maintenance. The following Ansible tasks do that:

- name: Patch octopus workers
  hosts: workers
  gather_facts: false
  vars:
    api_url: "https://octopusserver"
    api_key: "TODO"

  tasks:
    - name: Get worker status
      uri:
        url: "{{ api_url }}/api/workers/{{ octopus_id }}"
        method: GET
        headers:
          X-Octopus-ApiKey: "{{ api_key }}"
        body_format: json
        status_code: 200
      register: worker_status

    - name: Determine if worker requires draining
      set_fact:
        is_draining_required: "{{ worker_status.json.IsDisabled == false }}"

    - name: Is draining required?
      debug:
        msg: "Draining required: {{ is_draining_required }}"

    - name: Disable worker
      when: is_draining_required
      uri:
        url: "{{ api_url }}/api/workers/{{ octopus_id }}"
        method: PUT
        headers:
          X-Octopus-ApiKey: "{{ api_key }}"
        body: "{{ worker_status.json | combine({'IsDisabled': true}) | to_json }}"
        body_format: json
        status_code: 200

    - name: Wait for worker to drain
      when: is_draining_required
      block:
        - name: Check for active leases
          uri:
            url: "{{ api_url }}/api/Spaces-1/workertaskleases?skip=0&take=1000"
            method: GET
            headers:
              X-Octopus-ApiKey: "{{ api_key }}"
                status_code: 200
          register: lease_status
          # if you have jmespath installed this can be improved
          until: "not lease_status is search(octopus_id)"
          retries: 60
          delay: 15

    # do patching
    - name: Sleep to simulate patching
      pause:
        seconds: 5

    - name: Enable worker
      when: is_draining_required
      uri:
        url: "{{ api_url }}/api/workers/{{ octopus_id }}"
        method: PUT
        headers:
          X-Octopus-ApiKey: "{{ api_key }}"
        body: "{{ worker_status.json | combine({'IsDisabled': false}) | to_json }}"
        body_format: json
        status_code: 200

Example inventory:

workers:
  hosts:
    worker1a:
      octopus_id: Workers-1

This attempts to leave the worker status in the same state it finds it, but that handling could be improved to better handle failures.

Download GEO IP Maxmind Database with Powershell or Bash on Windows/Mac/Linux

2025-03-11T00:00:00+00:00

Here’s a tiny shell script for downloading a Maxmind database if you can use something scrappy:

LICENSE_KEY='YOUR_LICENSE_KEY'

# GeoLite2-City, GeoLite2-Country, GeoIP2-City, GeoIP2-Country"
DATABASE_TYPE='GeoIP2-Country'

MAXMIND_URL="https://download.maxmind.com/app/geoip_download?edition_id=$DATABASE_TYPE&license_key=$LICENSE_KEY&suffix=tar.gz"
CURL_OPTIONS="-Ls --fail"
TAR_OPTIONS="-Ozx --no-anchored $DATABASE_TYPE.mmdb"

curl $CURL_OPTIONS "$MAXMIND_URL" | tar $TAR_OPTIONS > "$DATABASE_TYPE.mmdb"

Here’s a fuller version with more bells and whistles:

#!/bin/bash

# exit on error
set -eo pipefail

# Usage message
usage() {
  echo "Usage: $0 <license_key> <database_type> [output]"
  echo "  license_key: Your MaxMind license key"
  echo "  database_type: One of: GeoLite2-City, GeoLite2-Country, GeoIP2-City, GeoIP2-Country"
  echo "  output: Optional. Path to save the downloaded database file"
  exit 1
}

# Check for license_key argument
if [ -z "$1" ]; then
  echo >&2 "Error: MaxMind license key is required"
  usage
fi

license_key="$1"
database_type="$2"
output="$3"

# Validate database type if provided
if [ -n "$database_type" ]; then
  case "$database_type" in
    "GeoLite2-City"|"GeoLite2-Country"|"GeoIP2-City"|"GeoIP2-Country")
      # Valid option
      ;;
    *)
      echo >&2 "Error: Invalid database type '$database_type'"
      usage
      ;;
  esac
fi

# Set default output if not provided
if [ -z "$output" ]; then
  output="$database_type.mmdb"
fi

# check requirements
if ! type curl > /dev/null 2>&1; then
  echo >&2 "curl is required but was not found"
  exit 1
fi

echo "Downloading $database_type database..."

MAXMIND_URL="https://download.maxmind.com/app/geoip_download?edition_id=$database_type&license_key=$license_key&suffix=tar.gz"
CURL_OPTIONS="-Ls --fail"
TAR_OPTIONS="-Ozx --no-anchored $database_type.mmdb"

curl $CURL_OPTIONS "$MAXMIND_URL" | tar $TAR_OPTIONS > "$output"

echo "Saved to $output"

If you save that to update-db.sh (and run chmod +x update-db.sh), then you can invoke it like this:

./update-db.sh 'your-license-key' GeoIP2-Country bash-country.mmdb

And here’s a Powershell version, which works on Server 2019+ or Windows 10+ (earlier versions of Windows require you to install tar yourself):

function Get-MaxMindDatabase {
    <#
    .SYNOPSIS
        Downloads a MaxMind GeoIP database, extracts the .mmdb file, and saves it to the specified location.
    
    .DESCRIPTION
        This function downloads a MaxMind database using a license key, extracts the .mmdb file
        and saves it to the specified output file.
    
    .PARAMETER LicenseKey
        Your MaxMind license key.
    
    .PARAMETER DatabaseType
        The type of database to download. Must be one of: GeoLite2-City, GeoLite2-Country, GeoIP2-City, GeoIP2-Country.
    
    .PARAMETER OutputFile
        The path where the extracted .mmdb file should be saved.
    
    .EXAMPLE
        Get-MaxMindDatabase -LicenseKey "your_license_key" -DatabaseType "GeoLite2-City" -OutputFile "C:\GeoIP\GeoLite2-City.mmdb"
    #>
    
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]$LicenseKey,
        
        [Parameter(Mandatory = $true)]
        [ValidateSet("GeoLite2-City", "GeoLite2-Country", "GeoIP2-City", "GeoIP2-Country")]
        [string]$DatabaseType,
        
        [Parameter(Mandatory = $true)]
        [string]$OutputFile
    )
    
    try {
        # Create temporary files
        $tempArchiveFile = [System.IO.Path]::Combine([System.IO.Path]::GetTempPath(), "$([System.Guid]::NewGuid().ToString()).tar.gz")
        $tempDirectory = [System.IO.Path]::Combine([System.IO.Path]::GetTempPath(), [System.Guid]::NewGuid().ToString())
        
        # Create the download URL
        $downloadUrl = "https://download.maxmind.com/app/geoip_download?edition_id=$DatabaseType&license_key=$LicenseKey&suffix=tar.gz"
        
        Write-Host "Downloading from $downloadUrl to $tempArchiveFile"
        
        # Download the file
        $webClient = New-Object System.Net.WebClient
        $webClient.DownloadFile($downloadUrl, $tempArchiveFile)
        
        # Create a temporary directory for extraction
        New-Item -Path $tempDirectory -ItemType Directory -Force | Out-Null
        Write-Host "Extracting tar.gz file to $tempDirectory"
        tar -xzf $tempArchiveFile -C $tempDirectory

        # Check if the extraction was successful
        if ($LASTEXITCODE -ne 0) {
            throw "Failed to extract the downloaded archive."
        }

        # Find the .mmdb file
        $mmdbFile = Get-ChildItem -Path $tempDirectory -Recurse -Filter "*.mmdb" | Select-Object -First 1
        if ($null -eq $mmdbFile) {
            throw "No .mmdb file found in the downloaded archive."
        }
        
        Write-Host "Found .mmdb file: $($mmdbFile.FullName)"
        
        $outputDirectory = [System.IO.Path]::GetDirectoryName($OutputFile)
        if (-not [string]::IsNullOrEmpty($outputDirectory) -and -not (Test-Path -Path $outputDirectory)) {
            throw "Output directory '$outputDirectory' not found."
        }
        
        # Copy the file to the output location
        Copy-Item -Path $mmdbFile.FullName -Destination $OutputFile -Force
        
        Write-Host "Database saved to $OutputFile"
        
        # Return the path to the output file
        return $OutputFile
    }
    catch {
        Write-Error "Failed to download and extract MaxMind database: $_"
        throw
    }
    finally {
        # Clean up temporary files
        if (Test-Path -Path $tempArchiveFile) {
            Remove-Item -Path $tempArchiveFile -Force
        }
        
        if (Test-Path -Path $tempDirectory) {
            Remove-Item -Path $tempDirectory -Recurse -Force
        }
    }
}

You can dot-include it, and then run it, like this:

# include the function
. ./Get-MaxmindDatabase.ps1

$licenseKey = 'your-license-key'

# download database
Get-MaxmindDatabase -LicenseKey $licenseKey -DatabaseType GeoIP2-Country -OutputFile ./country.mddb

Note: these mddb endpoints only support the suffix .tar.gz. There are also csv endpoints that support zip, but you can’t uze zip here.

Note: at the time of this writing, those databases are approximately this big:

GeoIP2-City.mmdb: 117 MB
GeoLite2-City.mmdb: 58 MB

and:

GeoIP2-Country.mmdb: 8.6 MB
GeoLite2-Country.mmdb: 8.7 MB (yes, bigger than the non-lite database!)

Command line server TLS certificate inspector

2025-03-05T00:00:00+00:00

I can never remember this command to inspect a remote server’s certificate from bash/shell/terminal:

openssl s_client -connect example.com:443 < /dev/null | openssl x509 -noout -text

So I wrapped it in a function and stuck it into my ~/.bash_profile like this:

cert () 
{ 
    openssl s_client -connect $1:443 < /dev/null | openssl x509 -noout -text
}

And now I just have to remember cert [hostname], like this:

$ cert github.com
Connecting to 140.82.112.3
...
        Issuer: C=GB, ST=Greater Manchester, L=Salford, O=Sectigo Limited, CN=Sectigo ECC Domain Validation Secure Server CA
        Validity
            Not Before: Feb  5 00:00:00 2025 GMT
            Not After : Feb  5 23:59:59 2026 GMT
        Subject: CN=github.com
...

And if you’re looking for something in particular, you can just grep for it:

$ cert github.com | grep github
        Subject: CN=github.com
                DNS:github.com, DNS:www.github.com

Very handy.

Automatic dog food status light

2025-01-04T00:00:00+00:00

The goal: feed the dogs 2x/day

Ideally my two pups would be fed roughly the right amount of food at roughly the right time, twice a day.

And we’d all be sure that it happened.

The problem: did someone feed the dogs?

We faced uncertainty nearly every day. With humans coming and going to various things, it was often difficult to know and this surely led to under- and over-feeding.

This is a classic systems/process problem (with perhaps a dash of volunteer’s dilemma): the way we managed dog feeding was designed to ellicit bad outcomes, and eliminating those bad outcomes (i.e. under/over feeding) requires a change to the system. “Trying harder” won’t cut it. (More on this at the end.)

Some ideas

As a family we talked about possible solutions to this problem:

Designate one caretaker as the person responsible for making sure the dogs get fed each day
Make a note when they’re fed
Pre-measure their food for the week, and pour it out of the day’s marked container each day
Change nothing (the dogs will tell us when we forget!)

We tried all of these things and they all helped a little. But they all had significant shortcomings:

Each person is busy and has a relatively chaotic schedule
People forget, and it’s hard to fill in the gaps without knowing if the gap exists or not
Keeping notes and/or pre-measuring is extra work and isn’t necessarily reliable
My pups are unreliable witnesses

A real solution

I knew about medicine bottles that show time-since-last-open and thought something like that would be wonderful. What we have finally arrived at is a solution that completely solves our problem with the following results:

We have a status light that anyone can read at a glance: it turns red when the dogs need fed, and turns green when they’ve recently beed fed
The status light updates automatically with no extra work (very important!)

It’s basically an andon light/stack light, powered by Home Assistant and two components: an open/close sensor on the dog food container and a smart RGB night light.

Build details

I used an Aqara door/window sensor ($15) attached to the lid of my dog food container, and an RGB smart night light ($30). Then I set up an automation in Home Assistant to do the following:

Turn the light on, set to RED 🔴, at breakfast and dinner time
Set the light GREEN 🟢 when a feeding occurs
Turn the light OFF ⚪️ two hours after a feeding

Here’s the heavily annotated yaml:

alias: Set dog food status
description: ""
trigger:
    # trigger in the morning and evening so we can turn
    # the light ON and RED for breakfast and dinner
    - alias: Morning
      platform: time
      at: "07:00:00"
      id: morning
    - alias: Evening
      platform: time
      at: "18:00:00"
      id: evening
      # trigger when the dog food container changes to
      # "closed" so we set the light to GREEN
    - platform: state
      entity_id:
          - binary_sensor.open_close_xs_sensor_window_door_is_open_3
      to: "off"
      alias: Fed
      id: fed
action:
    # I found that changing the light was more reliable if
    # I always turned it off first
    - service: light.turn_off
      metadata: {}
      data: {}
      target:
          entity_id: light.dog_food_status_light_light
      alias: Light off
    - if:
          # if trigger=fed, i.e. food container was just closed,
          # set the light to GREEN...
          - condition: trigger
            id:
                - fed
      then:
          - alias: Turn light green
            service: light.turn_on
            metadata: {}
            data:
                rgb_color:
                    - 0
                    - 249
                    - 0
                brightness_pct: 25
            target:
                entity_id: light.dog_food_status_light_light
          # ...and wait 2 hours...
          - delay:
                hours: 2
                minutes: 0
                seconds: 0
                milliseconds: 0
          # ...then turn it off. This way humans can tell long
          # after feeding time that everything is cool
          - service: light.turn_off
            metadata: {}
            data: {}
            target:
                entity_id: light.dog_food_status_light_light
      else:
          # else, the trigger is the breakfast or dinner timer
          # so just turn it red
          - alias: Turn light red
            service: light.turn_on
            metadata: {}
            data:
                rgb_color:
                    - 255
                    - 38
                    - 0
                brightness_step_pct: 100
            target:
                entity_id: light.dog_food_status_light_light
mode: single

I cannot express just how helpful this has been 😊. And since it’s all in Home Assistant, it shows up on my dashboard. Here you can see that they were last fed an hour ago, and keeps history, though that’s not really necessary:

Happy humans and happy pups.

An aside on systemic problems

My most important professional skill is identifying and solving systemic problems. As W. Edwards Deming explains in Out of the Crisis, issues that occur within a system need to be addressed by changing the system:

Eighty-five percent of the reasons for failure are deficiencies in the systems and process rather than the employee. The role of management is to change the process rather than badgering individuals to do better

And L. David Marquet writes in Leadership Is Language:

We need to always remember that the organization is perfectly tuned to deliver the behavior we see, and people’s behaviors are the perfect result of the organization’s design. As individuals, we should embrace our responsibility for being the best we can be within the design of the organization. But as leaders, our responsibility is to design the organization so that individuals can be the best versions of themselves.

The Adobe Lightroom backup story is terrible

2025-01-03T00:00:00+00:00

Backing up an Adobe Lightroom catalog is a bit of a pain. If you have local storage large enough to hold all your photos then you can tell Lightroom to save a copy of every photo there, and then you can backup that location. That’s better than nothing. But when you don’t have enough space (largely thanks to Apple’s exorbinate storage upgrade prices), backing up everything, including what gets offloaded to Adobe’s cloud is difficult. As far as I can tell, there’s no straightforward way to do this, especially not repeatedly.

To be clear: the cloud storage Adobe uses for Lightroom is exceptionally convenient, but it is not a backup. I want a backup that will survive account compromise, loss of access, or a major technical issue with the provider.

It’d be nice if I could restore the backup without much disruption, but I’ll settle for an inconvenient, incomplete copy of everything.

Here’s what I settled on:

Get a large external USB hard drive ($99)
Use the Adobe Lightroom Downloader to download all the photos to it (25 hours)
Repeat periodically

I’m disappointed that this doesn’t give me the high-fidelity backup I want, and that I have to manually do it every month or two, and that it’s wildly inefficient to re-download all the photos every time, but it’s all I have.

Things I wish I could do instead

I wish I could use a web service to automatically backup photos to a 3rd party, e.g. Google Photos, S3, B2, etc.

I wish I could run a script or service on my home Linux server to download just the changes periodically and automatically.

I wish the Lightroom Downloader had a “sync” feature so it didn’t have to download all 125k+ photos every time.

I wish the backup options didn’t lose so much data along the way, e.g. album strcuture, and I wish backups could be easily restored.

Expose self-hosted Home Assistant to the internet (and companion app) with Cloudflare Tunnels and Docker Compose

2024-12-29T00:00:00+00:00

Prerequisites

This guide assumes you have the following:

A Cloudflare account (free)
A domain name (bought from Cloudflare or elsewhere; $10/yr), set up in Cloudflare
A linux server with docker, which can be the same one where you run Home Assistant, but doesn’t need to be

The general idea

Web users connect to Cloudflare, and instead of Cloudflare reaching into our network, we run a service inside the network that reaches out to Cloudflare:

We are not opening any ports, e.g. http/https from our server to the local network or internet. We are not messing with dynamic dns stuff. We don’t need to set up TLS.

An example with Docker Compose

Create the tunnel config at Cloudflare

First create your tunnel in the Cloudflare dashboard > Zero Trust > Networks > Tunnels:

Choose cloudflared
Name it whatever you want, e.g. homelab
Click the “docker” installation instructions just to grab the token
Don’t actually install anything

Copy that token for the next section.

On your homelab server

Create docker-compose.yaml like this, with the token you copied above:

version: "3.3"

services:
    tunnel:
        image: cloudflare/cloudflared
        restart: unless-stopped
        command: tunnel run
        environment:
            - TUNNEL_TOKEN=***insert CF Tunnel token here***

Start up the containers:

docker compose up -d

Tail the logs:

docker compose logs -f

Back in the Cloudflare dashboard

At this point, the Cloudflare dashboard should show your tunnel as healthy. If not, read those logs carefully for errors and fix it before continuing.

Add a public hostname to your tunnel:

subdomain: anything you want (this DNS record will be added for you)
domain: pick the domain you already set up in Cloudflare
service: choose http, and set url to the internal IP and port of your Home Assistant inac name of your docker service. E.g. http://192.168.1.100:8123
additional application settings: none

With that done, you should be able to browse to the subdomain you set up, and the response will be tunneled over from your homelab server. You’ll probably get a 400 error. Don’t fret—you’re almost done.

Now you need to tell Home Assistant that the Cloudflare tunnel is allowed to proxy it. You can see the exact IP you need in the Home Assistant error log, e.g.:

“A request from a reverse proxy was received from 172.21.0.8, but your HTTP integration is not set-up for reverse proxies”

That exact IP could change when your cftunnel container restarts, but the first two parts of the network probably won’t, so you can just trust the whole thing like this, in HA configuration.yaml:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.21.0.0/16 # add the actual IP of your cftunnels container, or the network it's on

(And restart your HA instance.)

You can also find the anticipated proxy IP by checking the network details, too. First, list your docker networks:

docker network ls

NETWORK ID     NAME                     DRIVER    SCOPE
37c19c0df841   bridge                   bridge    local
da9f58733dc9   home-assistant_default   bridge    local
587ff440738c   host                     host      local
30a44b8290f3   none                     null      local
0e1df72bc30c   sites_default            bridge    local

Then pick the one where you’re running your cftunnels container (not the one running your HA instance!). In my case, it’s in a folder called sites, so I need the last one. Inspect it:

// docker network inspect sites_default 

[
    {
        "Name": "sites_default",
        "IPAM": {
            "Config": [
                {
                    "Subnet": "172.21.0.0/16", // <-- this is what you want
                    "Gateway": "172.21.0.1"
                }
            ]
        },
        "Containers": {
            "6626c238...": {
                "Name": "sites-tunnel-1",
                "IPv4Address": "172.21.0.8/16"
            }
        }
    }
]

Do I need to do TLS, HTTP compression, etc.?

No. Cloudflare handles TLS and HTTP compression for you. The tunnel is encrypted so no additional TLS is necessary for that leg.

I’m still getting a `400` error, or something else isn’t working

Check the logs!

A dash of whimsy with a tiny loading animation

2024-12-19T00:00:00+00:00

It’s neat how a teensy little animation can add a little whimsy to an otherwise boring thing like loading a bunch of contact cards:

This is achieved with pretty much the most naive code you can imagine. I’m using JS to add the elements with opacity: 0, and then schedule their reveal with a random delay:

// ...
document.getElementById('output').appendChild(el);

setTimeout(() => {
    el.classList.add('show'); // sets `opacity: 1;`
}, Math.random() * 500);

This would work just as well for elements already in the DOM, too.

Easy self-hosting websites with Cloudflare and Docker Compose

2024-12-19T00:00:00+00:00

Prerequisites

This guide assumes you have the following:

A Cloudflare account (free)
A domain name (bought from Cloudflare or elsewhere; $10/yr), set up in Cloudflare
A linux server with docker

The general idea

Web users connect to Cloudflare, and instead of Cloudflare reaching into our network, we run a service inside the network that reaches out to Cloudflare:

We are not opening any ports, e.g. http/https from our server to the local network or internet. We are not messing with dynamic dns stuff. We don’t need to set up TLS.

An example with Docker Compose

Create the tunnel config at Cloudflare

First create your tunnel in the Cloudflare dashboard > Zero Trust > Networks > Tunnels:

Choose cloudflared
Name it whatever you want, e.g. homelab
Click the “docker” installation instructions just to grab the token
Don’t actually install anything

Copy that token for the next section.

On your homelab server

Create docker-compose.yaml like this, with the token you copied above:

version: "3.3"

services:
    tunnel:
        image: cloudflare/cloudflared
        restart: unless-stopped
        command: tunnel run
        environment:
            - TUNNEL_TOKEN=***insert CF Tunnel token here***

    web:
        image: nginx:latest

Start up the containers:

docker compose up -d

Tail the logs:

docker compose logs -f

Back in the Cloudflare dashboard

At this point, the Cloudflare dashboard should show your tunnel as healthy. If not, read those logs carefully for errors and fix it before continuing.

Add a public hostname to your tunnel:

subdomain: anything you want (this DNS record will be added for you)
domain: pick the domain you already set up in Cloudflare
service: choose http, and set url to the name of your docker service. In the above example it’s web
additional application settings: none

With that done, you should be able to browse to the subdomain you set up, and the response will be tunneled over from your homelab server. Good job ✨

Adding another website

You can add another container to the docker compose file like this:

version: "3.3"

services:

  tunnel:
    image: cloudflare/cloudflared
    restart: unless-stopped
    command: tunnel run
    environment:
      - TUNNEL_TOKEN=<insert sensitive token here>

  web:
    image: nginx:latest
    restart: unless-stopped

  whoami:
    image: traefik/whoami
    restart: unless-stopped

And add a public hostname mapping in your tunnel:

subdomain: anything you want (this DNS record will be added for you)
domain: pick the domain you already set up in Cloudflare
service: choose http, and set url to the name of your docker service. This time it’s whoami
additional application settings: none

Do I need to do TLS, HTTP compression, etc.?

No. Cloudflare handles TLS and HTTP compression for you. The tunnel is encrypted so no additional TLS is necessary for that leg.

I suggest setting up a global redirect rule in Cloudflare to handle http->https.

Can I build my own containers?

Sure, that’s pretty easy. Your docker compose service can just point to a folder that itself contains a Dockerfile like this:

# ...
  web:
    build: ./web
    restart: unless-stopped

When you do docker compose up -d it will build the image for you and then start it.

…and run this to rebuild the image as needed: docker compose up -d --build web

Why don’t I need a load balancer like Traefik?

Often we’d carefully expose containers within docker to something outside of docker by configuring ports and proxying traffic through a load balancer like nginx or traefik. We’re not actually accepting connections to our containers from outside of docker so we don’t need to do that.

By default, docker compose containers can see each other and connect by service name (i.e. web, whoami, etc.). When you configure the tunnel to resolve a public hostname to the internal docker service name, the tunnel container just uses the docker network to talk to it. And the tunnel container can reach out of the docker network to connect to Cloudflare. If your container is listening on port 80, you’re done—you don’t need to expose it to the host network.

Troubleshooting

See logs from your containers, including the cloudflare tunnel (read those error messages carefully!):

docker compose logs -f

See if the tunnel state is healthy in the Cloudflare dashboard

See if your containers are running:

docker container ls

Microsoft Ergonomic Keyboard Acting Weird

Microsoft Ergonomic Keyboard Acting Weird

RF interference—my most common problem

A stuck key

Crudely capture working files

Drain Octopus Deploy workers for patching

Download GEO IP Maxmind Database with Powershell or Bash on Windows/Mac/Linux

Command line server TLS certificate inspector

Automatic dog food status light

The goal: feed the dogs 2x/day

The problem: did someone feed the dogs?

Some ideas

A real solution

Build details

An aside on systemic problems

The Adobe Lightroom backup story is terrible

Things I wish I could do instead

Expose self-hosted Home Assistant to the internet (and companion app) with Cloudflare Tunnels and Docker Compose

Prerequisites

The general idea

An example with Docker Compose

Create the tunnel config at Cloudflare

On your homelab server

Back in the Cloudflare dashboard

Do I need to do TLS, HTTP compression, etc.?

I’m still getting a 400 error, or something else isn’t working

A dash of whimsy with a tiny loading animation

Easy self-hosting websites with Cloudflare and Docker Compose

Prerequisites

The general idea

An example with Docker Compose

Create the tunnel config at Cloudflare

On your homelab server

Back in the Cloudflare dashboard

Adding another website

Do I need to do TLS, HTTP compression, etc.?

Can I build my own containers?

Why don’t I need a load balancer like Traefik?

Troubleshooting

I’m still getting a `400` error, or something else isn’t working