Forem: Dave Cross

Writing a TOON Module for Perl

Dave Cross — Sun, 29 Mar 2026 17:46:14 +0000

Every so often, a new data serialisation format appears and people get excited about it. Recently, one of those formats is TOON — Token-Oriented Object Notation. As the name suggests, it’s another way of representing the same kinds of data structures that you’d normally store in JSON or YAML: hashes, arrays, strings, numbers, booleans and nulls.

So the obvious Perl question is: “Ok, where’s the CPAN module?”

This post explains what TOON is, why some people think it’s useful, and why I decided to write a Perl module for it — with an interface that should feel very familiar to anyone who has used JSON.pm.

I should point out that I knew about Data::Toon but I wanted something with an interface that was more like JSON.pm.

—

What TOON Is

TOON stands for Token-Oriented Object Notation. It’s a textual format for representing structured data — the same data model as JSON:

Objects (hashes)
Arrays
Strings
Numbers
Booleans
Null

The idea behind TOON is that it is designed to be easy for both humans and language models to read and write. It tries to reduce punctuation noise and make the structure of data clearer.

If you think of the landscape like this:

Format	Human-friendly	Machine-friendly	Very common
JSON	Medium	Very	Yes
YAML	High	Medium	Yes
TOON	High	High	Not yet

TOON is trying to sit in the middle: simpler than YAML, more readable than JSON.

Whether it succeeds at that is a matter of taste — but it’s an interesting idea.

—

TOON vs JSON vs YAML

It’s probably easiest to understand TOON by comparing it to JSON and YAML. Here’s the same “person” record written in all three formats.

JSON

{  
  "name": "Arthur Dent",
  "age": 42,
  "email": "arthur@example.com",
  "alive": true,
  "address": {
    "street": "High Street",
    "city": "Guildford"
   },
  "phones": [
    "01234 567890",
    "07700 900123"
  ]
}

YAML

name: Arthur Dent  
age: 42  
email: arthur@example.com  
alive: true  
address:  
  street: High Street  
  city: Guildford  
phones:  
  – 01234 567890  
  – 07700 900123

TOON

name: Arthur Dent
age: 42
email: arthur@example.com”
alive: true
address:
  street: High Street 
  city: Guildford
phones[2]: 01234 567890,07700 900123

You can see that TOON sits somewhere between JSON and YAML:

Less punctuation and quoting than JSON
More explicit structure than YAML
Still very easy to parse
Still clearly structured for machines

That’s the idea, anyway.

—

Why People Think TOON Is Useful

The current interest in TOON is largely driven by AI/LLM workflows.

People are using it because:

It is easier for humans to read than JSON.
It is less ambiguous and complex than YAML.
It maps cleanly to the JSON data model.
It is relatively easy to parse.
It works well in prompts and generated output.

In other words, it’s not trying to replace JSON for APIs, and it’s not trying to replace YAML for configuration files. It’s aiming at the space where humans and machines are collaborating on structured data.

You may or may not buy that argument — but it’s an interesting niche.

—

Why I Wrote a Perl Module

I don’t have particularly strong opinions about TOON as a format. It might take off, it might not. We’ve seen plenty of “next big data format” ideas over the years.

But what I do have a strong opinion about is this:

If a data format exists, then Perl should have a CPAN module for it that works the way Perl programmers expect.

Perl already has very good, very consistent interfaces for data serialisation:

JSON
YAML
Storable
Sereal

They all tend to follow the same pattern, particularly the object-oriented interface:

use JSON;  
my $json = JSON->new->pretty->canonical;  
my $text = $json->encode($data);  
my $data = $json->decode($text);

So I wanted a TOON module that worked the same way.

—

Design Goals

When designing the module, I had a few simple goals.

1. Familiar OO Interface

The primary interface should be object-oriented and feel like JSON.pm:

use TOON;  
my $toon = TOON->new  
               ->pretty  
               ->canonical  
               ->indent(2);  
my $text = $toon->encode($data);  
my $data = $toon->decode($text);

If you already know JSON, you already know how to use TOON.

There are also convenience functions, but the OO interface is the main one.

2. Pure Perl Implementation

Version 0.001 is pure Perl. That means:

Easy to install
No compiler required
Works everywhere Perl works

If TOON becomes popular and performance matters, someone can always write an XS backend later.

3. Clean Separation of Components

Internally, the module is split into:

Tokenizer – turns text into tokens
Parser – turns tokens into Perl data structures
Emitter – turns Perl data structures into TOON text
Error handling – reports line/column errors cleanly

This makes it easier to test and maintain.

4. Do the Simple Things Well First

Version 0.001 supports:

Scalars
Arrayrefs
Hashrefs
undef → null
Pretty printing
Canonical key ordering

It does not (yet) try to serialise blessed objects or do anything clever. That can come later if people actually want it.

—

Example Usage (OO Style)

Here’s a simple Perl data structure:

my $data = {
  name => "Arthur Dent",
  age => 42,
  drinks => ["tea", "coffee"],
  alive => 1,  
};

Encoding

use TOON;  
my $toon = TOON->new->pretty->canonical;  
my $text = $toon->encode($data);  
print $text;

Decoding

use TOON;  
my $toon = TOON->new;  
my $data = $toon->decode($text);  
print $data->{name};

Convenience Functions

use TOON qw(encode_toon decode_toon);  
my $text = encode_toon($data);  
my $data = decode_toon($text);

But the OO interface is where most of the flexibility lives.

—

Command Line Tool

There’s also a command-line tool, toon_pp, similar to json_pp:

cat data.toon | toon_pp

Which will pretty-print TOON data.

—

Final Thoughts

I don’t know whether TOON will become widely used. Predicting the success of data formats is a fool’s game. But the cost of supporting it in Perl is low, and the potential usefulness is high enough to make it worth doing.

And fundamentally, this is how CPAN has always worked:

See a problem. Write a module. Upload it. See if anyone else finds it useful.

So now Perl has a TOON module. And if you already know how to use JSON.pm, you already know how to use it.

That was the goal.

The post Writing a TOON Module for Perl first appeared on Perl Hacks.

Still on the [b]leading edge

Dave Cross — Sat, 21 Mar 2026 11:14:06 +0000

About eighteen months ago, I wrote a post called On the Bleading Edge about my decision to start using Perl’s new class feature in real code. I knew I was getting ahead of parts of the ecosystem. I knew there would be occasional pain. I decided the benefits were worth it.

I still think that’s true.

But every now and then, the bleading edge reminds you why it’s called that.

Recently, I lost a couple of days to a bug that turned out not to be in my code, not in the module I was installing, and not even in the module that module depended on — but in the installer’s understanding of modern Perl syntax.

This is the story.

The Symptom

I was building a Docker image for Aphra. As part of the build, I needed to install App::HTTPThis, which depends on Plack::App::DirectoryIndex, which depends on WebServer::DirIndex.

The Docker build failed with this error:

#13 45.66 --> Working on WebServer::DirIndex
#13 45.66 Fetching https://www.cpan.org/authors/id/D/DA/DAVECROSS/WebServer-DirIndex-0.1.3.tar.gz ... OK
#13 45.83 Configuring WebServer-DirIndex-v0.1.3 ... OK
#13 46.21 Building WebServer-DirIndex-v0.1.3 ... OK
#13 46.75 Successfully installed WebServer-DirIndex-v0.1.3
#13 46.84 ! Installing the dependencies failed: Installed version (undef) of WebServer::DirIndex is not in range 'v0.1.0'
#13 46.84 ! Bailing out the installation for Plack-App-DirectoryIndex-v0.2.1.

Now, that’s a deeply confusing error message.

It clearly says that WebServer::DirIndex was successfully installed. And then immediately says that the installed version is undef and not in the required range.

At this point you start wondering if you’ve somehow broken version numbering, or if there’s a packaging error, or if the dependency chain is wrong.

But the version number in WebServer::DirIndex was fine. The module built. The tests passed. Everything looked normal.

So why did the installer think the version was undef?

When This Bug Appears

This only shows up in a fairly specific situation:

A module uses modern Perl class syntax
The module defines a $VERSION
Another module declares a prerequisite with a specific version requirement
The installer tries to check the installed version without loading the module
It uses Module::Metadata to extract $VERSION
And the version of Module::Metadata it is using doesn’t properly understand class

If you don’t specify a version requirement, you’ll probably never see this. Which is why I hadn’t seen it before. I don’t often pin minimum versions of my own modules, but in this case, the modules are more tightly coupled than I’d like, and specific versions are required.

So this bug only appears when you combine:

modern Perl syntax + version checks + older toolchain

Which is pretty much the definition of “bleading edge”.

The Real Culprit

The problem turned out to be an older version of Module::Metadata that had been fatpacked into cpanm.

cpanm uses Module::Metadata to inspect modules and extract $VERSION without loading the module. But the older Module::Metadata didn’t correctly understand the class keyword, so it couldn’t work out which package the $VERSION belonged to.

So when it checked the installed version, it found… nothing.

Hence:

Installed version (undef) of WebServer::DirIndex is not in range ‘v0.1.0’

The version wasn’t wrong. The installer just couldn’t see it.

An aside, you may find it amusing to hear an anecdote from my attempts to debug this problem.

I spun up a new Ubuntu Docker container, installed cpanm and tried to install Plack::App::DirectoryIndex. Initially, this gave the same error message. At least the problem was easily reproducible.

I then ran code that was very similar to the code cpanm uses to work out what a module’s version is.

$ perl -MModule::Metadata -E'say Module::Metadata->new_from_module("WebServer::DirIndex")->version'

This displayed an empty string. I was really onto something here. Module::Metadata couldn’t find the version.

I was using Module::Metadata version 1.000037 and, looking at the change log on CPAN, I saw this:

1.000038 2023-04-28 11:25:40Z

- detects "class" syntax

I installed 1.000038 and reran my command.

$ perl -MModule::Metadata -E'say Module::Metadata->new_from_module("WebServer::DirIndex")->version'
0.1.3

That seemed conclusive. Excitedly, I reran the Docker build.

It failed again.

You’ve probably worked out why. But it took me a frustrating half an hour to work it out.

cpanm doesn’t use the installed version of Module::Metadata. It uses its own, fatpacked version. Updating Module::Metadata wouldn’t fix my problem.

The Workaround

I found a workaround. That was to add a redundant package declaration alongside the class declaration, so older versions of Module::Metadata can still identify the package that owns $VERSION.

So instead of just this:

class WebServer::DirIndex {
  our $VERSION = '0.1.3';
  ...
}

I now have this:

package WebServer::DirIndex;

class WebServer::DirIndex {
  our $VERSION = '0.1.3';
  ...
}

It looks unnecessary. And in a perfect world, it would be unnecessary.

But it allows older tooling to work out the version correctly, and everything installs cleanly again.

The Proper Fix

Of course, the real fix was to update the toolchain.

So I raised an issue against App::cpanminus, pointing out that the fatpacked Module::Metadata was too old to cope properly with modules that use class.

Tatsuhiko Miyagawa responded very quickly, and a new release of cpanm appeared with an updated version of Module::Metadata.

This is one of the nice things about the Perl ecosystem. Sometimes you report a problem and the right person fixes it almost immediately.

When Do I Remove the Workaround?

This leaves me with an interesting question.

The correct fix is “use a recent cpanm”.

But the workaround is “add a redundant package line so older tooling doesn’t get confused”.

So when do I remove the workaround?

The answer is probably: not yet.

Because although a fixed cpanm exists, that doesn’t mean everyone is using it. Old Docker base images, CI environments, bootstrap scripts, and long-lived servers can all have surprisingly ancient versions of cpanm lurking in them.

And the workaround is harmless. It just offends my sense of neatness slightly.

So for now, the redundant package line stays. Not because modern Perl needs it, but because parts of the world around modern Perl are still catching up.

Life on the Bleading Edge

This is what life on the bleading edge actually looks like.

Not dramatic crashes. Not language bugs. Not catastrophic failures.

Just a tool, somewhere in the install chain, that looks at perfectly valid modern Perl code and quietly decides that your module doesn’t have a version number.

And then you lose two days proving that you are not, in fact, going mad.

But I’m still using class. And I’m still happy I am.

You just have to keep an eye on the whole toolchain — not just the language — when you decide to live a little closer to the future than everyone else.

The post Still on the [b]leading edge first appeared on Perl Hacks.

Your README Is Already a Website

Dave Cross — Sat, 28 Feb 2026 17:42:48 +0000

Announcing `readme-to-index` — My First GitHub Marketplace Release 🎉

Today I published my first GitHub Action to the Marketplace.

It’s called readme-to-index, and it does something very simple:

It turns your README.md into a clean, styled index.html.

That’s it.

No Jekyll.
No Ruby.
No themes.
No _config.yml.
No implicit behaviour.

Just Markdown → HTML → Done.

Why I Built It

I have a lot of small projects.

Many of them already have good READMEs. In fact, for most of them, the README is the documentation.

So the obvious question is:

Why create a separate site when the README already exists?

GitHub Pages + Jekyll is great. But for small libraries and utilities, it can feel like overkill.

I wanted something:

Minimal
Deterministic
Easy to drop into any workflow
Friendly to CI pipelines
With zero hidden conventions

So I built a GitHub Action that does exactly one thing:

README.md → index.html

Styled using Simple.css (by default, but you can use any stylesheet you like).

What It Does

Converts README.md to index.html using Pandoc
Automatically sets the HTML <title> from the first # Heading
Applies Simple.css for clean, classless styling
Suppresses Pandoc’s injected syntax-highlighting CSS
Leaves your original README untouched

Your README remains the canonical source of truth.

Usage

Add this to your workflow:

- uses: davorg/readme-to-index@v1
  with:
    output: _site/index.html

Then deploy using the standard GitHub Pages artifact flow.

Available Options

The action supports a few optional inputs:

`readme`

Path to the Markdown source file.

Default: README.md

`output`

Path to the generated HTML file.

Default: index.html

`css_url`

CSS stylesheet to include in the generated HTML.

Default: https://cdn.simplecss.org/simple.min.css

`install_pandoc`

Whether to install Pandoc automatically using apt-get.

Default: true

Set this to false if your workflow already installs Pandoc.

`extra_pandoc_args`

Additional arguments passed directly to the Pandoc command.

Example:

- uses: davorg/readme-to-index@v1
  with:
    extra_pandoc_args: "--toc"

Enabling GitHub Pages

For this to deploy as a website, you’ll need to enable GitHub Pages in your repository settings.

Go to:

Repository → Settings → Pages → Build and deployment

Set:

Source: GitHub Actions

That’s it. The workflow will handle the rest.

Example Complete Workflow

Here’s a minimal working example:

name: Publish README to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  pages:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - uses: actions/checkout@v4

      - uses: davorg/readme-to-index@v1
        with:
          output: _site/index.html

      - uses: actions/configure-pages@v5

      - uses: actions/upload-pages-artifact@v3
        with:
          path: _site

      - id: deployment
        uses: actions/deploy-pages@v4

Why Not Just Use Jekyll?

You absolutely can.

But this approach has two real advantages:

1. Simplicity

There’s no Ruby toolchain.

There are no implicit layouts.

There are no theme conventions to understand.

It takes one Markdown file and produces one HTML file.

That’s it.

2. Pipeline-Friendly

Because it’s "just a step", you can use it:

As part of a release build
In CI pipelines
Before publishing documentation artifacts
Outside GitHub entirely

It doesn’t rely on GitHub Pages’ default behaviour.

It works wherever Pandoc runs.

A Small Milestone

Shipping something to the GitHub Marketplace feels surprisingly significant.

It’s a tiny tool.
It does one thing.
But it does it cleanly.

That’s the kind of tooling I like building.

If you’re interested:

👉 https://github.com/marketplace/actions/readme-to-index-html

Feedback welcome. Stars appreciated. Minimalism encouraged.

Treating GitHub Copilot as a Contributor

Dave Cross — Sun, 22 Feb 2026 11:51:15 +0000

For some time, we’ve talked about GitHub Copilot as if it were a clever autocomplete engine.

It isn’t.

Or rather, that’s not all it is.

The interesting thing — the thing that genuinely changes how you work — is that you can assign GitHub issues to Copilot.

And it behaves like a contributor.

Over the past day, I’ve been doing exactly that on my new CPAN module, WebServer::DirIndex. I’ve opened issues, assigned them to Copilot, and watched a steady stream of pull requests land. Ten issues closed in about a day, each one implemented via a Copilot-generated PR, reviewed and merged like any other contribution.

That still feels faintly futuristic. But it’s not “vibe coding”. It’s surprisingly structured.

Let me explain how it works.

It Starts With a Proper Issue

This workflow depends on discipline. You don’t type “please refactor this” into a chat window. You create a proper GitHub issue. The sort you would assign to another human maintainer. For example, here are some of the recent issues Copilot handled in WebServer::DirIndex:

Add CPAN scaffolding
Update the classes to use Feature::Compat::Class
Replace DirHandle
Add WebServer::DirIndex::File
Move render() method
Use :reader attribute where useful
Remove dependency on Plack

Each one was a focused, bounded piece of work. Each one had clear expectations.

The key is this: Copilot works best when you behave like a maintainer, not a magician.

You describe the change precisely. You state constraints. You mention compatibility requirements. You indicate whether tests need to be updated.

Then you assign the issue to Copilot.

And wait.

The Pull Request Arrives

After a few minutes — sometimes ten, sometimes less — Copilot creates a branch and opens a pull request.

The PR contains:

Code changes
Updated or new tests
A descriptive PR message

And because it’s a real PR, your CI runs automatically. The code is evaluated in the same way as any other contribution.

This is already a major improvement over editor-based prompting. The work is isolated, reviewable, and properly versioned.

But the most interesting part is what happens in the background.

Watching Copilot Think

If you visit the Agents tab in the repository, you can see Copilot reasoning through the issue.

It reads like a junior developer narrating their approach:

Interpreting the problem
Identifying the relevant files
Planning changes
Considering test updates
Running validation steps

And you can interrupt it.

If it starts drifting toward unnecessary abstraction or broad refactoring, you can comment and steer it:

Please don’t change the public API.
Avoid experimental Perl features.
This must remain compatible with Perl 5.40.

It responds. It adjusts course.

This ability to intervene mid-flight is one of the most useful aspects of the system. You are not passively accepting generated code — you’re supervising it.

Teaching Copilot About Your Project

Out of the box, Copilot doesn’t really know how your repository works. It sees code, but it doesn’t know policy.

That’s where repository-level configuration becomes useful.

1. Custom Repository Instructions

GitHub allows you to provide a .github/copilot-instructions.md file that gives Copilot repository-specific guidance. The documentation for this lives here:

Adding repository custom instructions for GitHub Copilot

When GitHub offers to generate this file for you, say yes.

Then customise it properly.

In a CPAN module, I tend to include:

Minimum supported Perl version
Whether Feature::Compat::Class is preferred
Whether experimental features are forbidden
CPAN layout expectations (lib/, t/, etc.)
Test conventions (Test::More, no stray diagnostics)
A strong preference for not breaking the public API

Without this file, Copilot guesses.

With this file, Copilot aligns itself with your house style.

That difference is impressive.

2. Customising the Copilot Development Environment

There’s another piece that many people miss: Copilot can run a special workflow event called copilot_agent_setup.

You can define a workflow that prepares the environment Copilot works in. GitHub documents this here:

Customizing the development environment for GitHub Copilot coding agent

In my Perl projects, I use this standard setup:

name: Copilot Setup Steps

on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
  steps:
    - name: Check out repository
      uses: actions/checkout@v4

    - name: Set up Perl 5.40
      uses: shogo82148/actions-setup-perl@v1
      with:
        perl-version: '5.40'

    - name: Install dependencies
      run: cpanm --installdeps --with-develop --notest .

(Obviously, that was originally written for me by Copilot!)

This does two important things.

Firstly, it ensures Copilot is working with the correct Perl version.

Secondly, it installs the distribution dependencies, meaning Copilot can reason in a context that actually resembles my real development environment.

Without this workflow, Copilot operates in a kind of generic space.

With it, Copilot behaves like a contributor who has actually checked out your code and run cpanm.

That’s a useful difference.

Reviewing the Work

This is the part where it’s important not to get starry-eyed.

I still review the PR carefully.

I still check:

Has it changed behaviour unintentionally?
Has it introduced unnecessary abstraction?
Are the tests meaningful?
Has it expanded scope beyond the issue?

I check out the branch and run the tests. Exactly as I would with a PR from a human co-worker.

You can request changes and reassign the PR to Copilot. It will revise its branch.

The loop is fast. Faster than traditional asynchronous code review.

But the responsibility is unchanged. You are still the maintainer.

Why This Feels Different

What’s happening here isn’t just “AI writing code”. It’s AI integrated into the contribution workflow:

Issues
Structured reasoning
Pull requests
CI
Review cycles

That architecture matters.

It means you can use Copilot in a controlled, auditable way.

In my experience with WebServer::DirIndex, this model works particularly well for:

Mechanical refactors
Adding attributes (e.g. :reader where appropriate)
Removing dependencies
Moving methods cleanly
Adding new internal classes

It is less strong when the issue itself is vague or architectural. Copilot cannot infer the intent you didn’t articulate.

But given a clear issue, it’s remarkably capable — even with modern Perl using tools like Feature::Compat::Class.

A Small but Important Point for the Perl Community

I’ve seen people saying that AI tools don’t handle Perl well. That has not been my experience.

With a properly described issue, repository instructions, and a defined development environment, Copilot works competently with:

Modern Perl syntax
CPAN distribution layouts
Test suites
Feature::Compat::Class (or whatever OO framework I’m using on a particular project)

The constraint isn’t the language. It’s how clearly you explain the task.

The Real Shift

The most interesting thing here isn’t that Copilot writes Perl. It’s that GitHub allows you to treat AI as a contributor.

You file an issue.
You assign it.
You supervise its reasoning.
You review its PR.

It’s not autocomplete. It’s not magic. It’s just another developer on the project. One who works quickly, doesn’t argue, and reads your documentation very carefully.

Have you been using AI tools to write or maintain Perl code? What successes (or failures!) have you had? Are there other tools I should be using?

Links

If you want to have a closer look at the issues and PRs I’m talking about, here are some links?

The post Treating GitHub Copilot as a Contributor first appeared on Perl Hacks.

I Built a Tiny Domain Inventory Tool (Because I Used to Buy Too Many Domains)

Dave Cross — Sun, 08 Feb 2026 12:22:22 +0000

(Or: how I stopped losing track of the domains I swore I wouldn’t buy)

I used to be a serial domain-buyer.

Not in a dramatic, “lost a fortune” way — just lots of “oh, that might be useful one day” moments spread over many years. At one point, I honestly couldn’t tell you exactly what I owned, where it was registered, or what half of it pointed at.

I’m mostly better now. Mostly.

But I still own more domains than I like to admit, and I wanted a simple, honest way to see what I’ve got without:

another SaaS subscription
a spreadsheet that immediately goes stale
or building a backend I’d then have to maintain forever

So I built this instead:

👉 https://davorg.dev/mydomains/
👉 Source code: https://github.com/davorg/mydomains

It’s a small, static, browser-only tool for keeping track of domains, their DNS, and where they’re hosted — and it turns out to be surprisingly useful.

What I wanted (and what I very deliberately didn’t)

I wanted something that:

runs entirely in the browser
stores its data locally
can be hosted as static files
gives me useful facts, not a false sense of certainty

I explicitly didn’t want:

accounts
logins
databases
background jobs
“AI-powered insights” (whatever that would even mean here)

This is a tool for me. I trust myself with my own data.

If that resonates with you, read on.

What the tool does

At its core, it’s just an inventory:

a list of domains you own
the hostnames you care about (@, www, mail, etc.)
some notes and keywords so future-you knows why you bought it

On top of that, it can enrich each domain with:

DNS data
- NS, MX, TXT for the domain
- A / AAAA / CNAME for each host
RDAP data
- registrar
- expiry date
- registration status
Best-effort guesses
- DNS provider
- hosting provider per host

Everything is opt-in and cached. Nothing happens unless you click “refresh”.

Architecture: aggressively boring (by design)

There are three files that matter:

index.html
style.css
script.js

No build step. No framework. No external dependencies beyond public HTTP APIs.

All state lives in localStorage under a single key:

const STORAGE_KEY = 'domainInventory.v1';

If you clear your browser data, it’s gone. Which is why import/export exists.

That’s not a bug — that’s the trade-off.

DNS and RDAP: best-effort, not gospel

DNS is fetched using Google’s DNS-over-HTTPS endpoint:

https://dns.google/resolve?name=example.com&type=A

RDAP is fetched via rdap.org, with a couple of TLD-specific exceptions where needed.

This immediately gives you two realities to accept:

Not everything has RDAP
CORS sometimes says no

The code treats RDAP as optional. If it works, great. If not, nothing breaks.

That pattern shows up a lot in this project.

Provider guessing (aka “useful lies”)

One of the more interesting parts was deciding how far to go with interpretation.

DNS provider detection

This is intentionally simple:

function guessDnsProvider(nsList) {
  const nsLower = (nsList || []).map(n => n.toLowerCase());

  if (nsLower.some(n => n.includes('cloudflare.com'))) {
    return 'Cloudflare';
  }
  if (nsLower.some(n => n.includes('awsdns'))) {
    return 'AWS Route 53';
  }
  if (nsLower.some(n => n.includes('gandi.net'))) {
    return 'Gandi';
  }
  return 'Unknown';
}

Is it exhaustive? No.
Is it useful for my domains? Yes.

That’s a recurring theme here.

Hosting provider detection (and Cloudflare honesty)

Hosting detection looks at:

CNAME targets
A / AAAA addresses
known IP ranges
known patterns (.github.io, .cloudfront.net, .a.run.app, etc.)

But DNS can lie — or at least obscure.

So if a host resolves to Cloudflare IPs, the tool does this:

If it recognised the origin → “GitHub Pages (via Cloudflare)”
Otherwise → “Unknown (via Cloudflare)”

If the data doesn’t support a confident claim, I’d rather say “I don’t know” than pretend.

Caching with intent

All fetched data is cached per domain, along with a timestamp:

dom.cache.lastChecked = new Date().toISOString();

But here’s the important bit: the cache is only cleared when it should be.

If you edit notes or keywords, nothing is invalidated.

If you change the domain name or host list, the cache is wiped:

if (nameChanged || hostsChanged) {
  dom.cache = {};
}

That one small decision makes the tool feel calm instead of twitchy.

What this tool is not

It is not:

an auto-discovery system
a real-time monitor
a source of legal truth about domain ownership

It assumes:

you know which domains you own
you know which hosts matter
you’ll refresh things when you care

In return, it stays small, fast, and understandable.

Possible future improvements (and non-improvements)

Things I might add:

more provider heuristics (DigitalOcean, Fly.io, etc.)
configurable IP allow-lists per provider
better handling of registrar quirks per TLD
bulk refresh with throttling

Things I probably won’t:

accounts
sync
background polling
turning this into a product

The moment it needs a backend, it stops being this tool.

Why I’m happy with it

This started as a way to get a handle on my own past enthusiasm for buying domains.

It ended up as a reminder that:

a browser is a perfectly good runtime
not every problem needs infrastructure
“good enough and honest” beats “comprehensive but fragile”

If you own more domains than you’d like to admit, you might find it useful too.

And if nothing else, it’s a nice excuse to build something small, tidy, and under your control.

App::HTTPThis: the tiny web server I keep reaching for

Dave Cross — Sun, 04 Jan 2026 13:46:13 +0000

Whenever I’m building a static website, I almost never start by reaching for Apache, nginx, Docker, or anything that feels like “proper infrastructure”. Nine times out of ten I just want a directory served over HTTP so I can click around, test routes, check assets, and see what happens in a real browser.

For that job, I’ve been using App::HTTPThis for years.

It’s a simple local web server you run from the command line. Point it at a directory, and it serves it. That’s it. No vhosts. No config bureaucracy. No “why is this module not enabled”. Just: run a command and you’ve got a website.

Why I’ve used it for years

Static sites are deceptively simple… right up until they aren’t.

You want to check that relative links behave the way you think they do.
You want to confirm your CSS and images are loading with the paths you expect.
You want to reproduce “real HTTP” behaviour (caching headers, MIME types, directory handling) rather than viewing files directly from disk.

Sure, you can open file:///.../index.html in a browser, but that’s not the same thing as serving it over HTTP. And setting up Apache (or friends) feels like bringing a cement mixer to butter some toast.

With http_this, the workflow is basically:

cd into your site directory
run a single command
open a URL
get on with your life

It’s the “tiny screwdriver” that’s always on my desk.

Why I took it over

A couple of years ago, the original maintainer had (entirely reasonably!) become too busy elsewhere and the distribution wasn’t getting attention. That happens. Open source is like that.

But I was using App::HTTPThis regularly, and I had one small-but-annoying itch: when you visited a directory URL, it would always show a directory listing - even if that directory contained an index.html. So instead of behaving like a typical web server (serve index.html by default), it treated index.html as just another file you had to click.

That’s exactly the sort of thing you notice when you’re using a tool every day, and it was irritating enough that I volunteered to take over maintenance.

(If you want to read more on this story, I wrote a couple of blog posts.)

What I’ve done since taking it over

Most of the changes are about making the “serve a directory” experience smoother, without turning it into a kitchen-sink web server.

1) Serve index pages by default (autoindex)

The first change was to make directory URLs behave like you’d expect: if index.html exists, serve it automatically. If it doesn’t, you still get a directory listing.

2) Prettier index pages

Once autoindex was in place, I then turned my attention to the fallback directory listing page. If there isn’t an index.html, you still need a useful listing — but it doesn’t have to look like it fell out of 1998. So I cleaned up the listing output and made it a bit nicer to read when you do end up browsing raw directories.

3) A config file

Once you’ve used a tool for a while, you start to realise you run it the same way most of the time.

A config file lets you keep your common preferences in one place instead of re-typing options. It keeps the “one command” feel, but gives you repeatability when you want it.

4) `--host` option

The ability to control the host binding sounds like an edge case until it isn’t.

Sometimes you want:

only localhost access for safety;
access from other devices on your network (phone/tablet testing);
behaviour that matches a particular environment.

A --host option gives you that control without adding complexity to the default case.

The Bonjour feature (and what it’s for)

This is the part I only really appreciated recently: App::HTTPThis can advertise itself on your local network using mDNS / DNS-SD – commonly called Bonjour on Apple platforms, Avahi on Linux, and various other names depending on who you’re talking to.

It’s switched on with the --name option.

http_this --name MyService

When you do that, http_this publishes an _http._tcp service on your local network with the instance name you chose (MyService in this case). Any device on the same network that understands mDNS/DNS-SD can then discover it and resolve it to an address and port, without you having to tell anyone, “go to http://192.168.1.23:7007/”.

Confession time: I ignored this feature for ages because I’d mentally filed it under “Apple-only magic” (Bonjour! very shiny! probably proprietary!). It turns out it’s not Apple-only at all; it’s a set of standard networking technologies that are supported on pretty much everything, just under a frankly ridiculous number of different names. So: not Apple magic , just local-network service discovery with a branding problem.

Because I’d never really used it, I finally sat down and tested it properly after someone emailed me about it last week, and it worked nicely, nicely enough that I’ve now added a BONJOUR.md file to the repo with a practical explanation of what’s going on, how to enable it, and a few ways to browse/discover the advertised service.

(If you’re curious, look for _http._tcp and your chosen service name.)

It’s a neat quality-of-life feature if you’re doing cross-device testing or helping someone else on the same network reach what you’re running.

Related tools in the same family

App::HTTPThis is part of a little ecosystem of “run a thing here quickly” command-line apps. If you like the shape of http_this, you might also want to look at these siblings:

https_this : like http_this, but served over HTTPS (useful when you need to test secure contexts, service workers, APIs that require HTTPS, etc.)
cgi_this : for quick CGI-style testing without setting up a full web server stack
dav_this : serves content over WebDAV (handy for testing clients or workflows that expect DAV)
ftp_this : quick FTP server for those rare-but-real moments when you need one

They all share the same basic philosophy: remove the friction between “I have a directory” and “I want to interact with it like a service”.

Wrapping up

I like tools that do one job, do it well, and get out of the way. App::HTTPThis has been that tool for me for years and it’s been fun (and useful) to nudge it forward as a maintainer.

If you’re doing any kind of static site work — docs sites, little prototypes, generated output, local previews — it’s worth keeping in your toolbox.

And if you’ve got ideas, bug reports, or platform notes (especially around Bonjour/Avahi weirdness), I’m always happy to hear them.

The post App::HTTPThis: the tiny web server I keep reaching for first appeared on Perl Hacks.

Behind the scenes at Perl School Publishing

Dave Cross — Sun, 14 Dec 2025 17:46:53 +0000

We’ve just published a new Perl School book: Design Patterns in Modern Perl by Mohammad Sajid Anwar.

It’s been a while since we last released a new title, and in the meantime, the world of eBooks has moved on – Amazon don’t use .mobi any more, tools have changed, and my old “it mostly works if you squint” build pipeline was starting to creak.

On top of that, we had a hard deadline: we wanted the book ready in time for the London Perl Workshop. As the date loomed, last-minute fixes and manual tweaks became more and more terrifying. We really needed a reliable, reproducible way to go from manuscript to “good quality PDF + EPUB” every time.

So over the last couple of weeks, I’ve been rebuilding the Perl School book pipeline from the ground up. This post is the story of that process, the tools I ended up using, and how you can steal it for your own books.

The old world, and why it wasn’t good enough

The original Perl School pipeline dates back to a very different era:

Amazon wanted .mobi files.
EPUB support was patchy.
I was happy to glue things together with shell scripts and hope for the best.

It worked… until it didn’t. Each book had slightly different scripts, slightly different assumptions, and a slightly different set of last-minute manual tweaks. It certainly wasn’t something I’d hand to a new author and say, “trust this”.

Coming back to it for Design Patterns in Modern Perl made that painfully obvious. The book itself is modern and well-structured; the pipeline that produced it shouldn’t feel like a relic.

Choosing tools: Pandoc and `wkhtmltopdf` (and no LaTeX, thanks)

The new pipeline is built around two main tools:

Pandoc – the Swiss Army knife of document conversion. It can take Markdown/Markua plus metadata and produce HTML, EPUB, and much, much more.
wkhtmltopdf – which turns HTML into a print-ready PDF using a headless browser engine.

Why not LaTeX? Because I’m allergic. LaTeX is enormously powerful, but every time I’ve tried to use it seriously, I end up debugging page breaks in a language I don’t enjoy. HTML + CSS I can live with; browsers I can reason about. So the PDF route is:

Markdown → HTML (via Pandoc) → PDF (via wkhtmltopdf)

And the EPUB route is:

Markdown → EPUB (via Pandoc) → validated with epubcheck

The front matter (cover page, title page, copyright, etc.) is generated with Template Toolkit from a simple book-metadata.yml file, and then stitched together with the chapters to produce a nice, consistent book.

That got us a long way… but then a reader found a bug.

The iBooks bug report

Shortly after publication, I got an email from a reader who’d bought the Leanpub EPUB and was reading it in Apple Books (iBooks). Instead of happily flipping through Design Patterns in Modern Perl, they were greeted with a big pink error box.

Apple’s error message boiled down to:

There’s something wrong with the XHTML in this EPUB.

That was slightly worrying. But, hey, every day is a learning opportunity. And, after a bit of digging, this is what I found out.

EPUB 3 files are essentially a ZIP containing:

XHTML content files
a bit of XML metadata
CSS, images, and so on

Apple Books is quite strict about the “X” in XHTML: it expects well-formed XML, not just “kind of valid HTML”. So when working with EPUB, you need to forget all of that nice HTML5 flexibility that you’ve got used to over the last decade or so.

The first job was to see if we could reproduce the error and work out where it was coming from.

Discovering `epubcheck`

Enter epubcheck.

epubcheck is the reference validator for EPUB files. Point it at an .epub and it will unpack it, parse all the XML/XHTML, check the metadata and manifest, and tell you exactly what’s wrong.

Running it on the book immediately produced this:

Fatal Error while parsing file: The element type br must be terminated by the matching end-tag .

That’s the XML parser’s way of saying:

In HTML,   is fine.
In XHTML (which is XML), you must use   (self-closing) or  .

And there were a number of these scattered across a few chapters.

In other words: perfectly reasonable raw HTML in the manuscript had been passed straight through by Pandoc into the EPUB, but that HTML was not strictly valid XHTML, so Apple Books rejected it. I should note at this point that the documentation for EPUB explicitly says that it won’t touch HTML fragments it finds in a Markdown file when converting it to EPUB. It’s down to the author to ensure they’re using valid XHTML

A quick (but not scalable) fix

Under time pressure, the quickest way to confirm the diagnosis was:

Unzip the generated EPUB.
Open the offending XHTML file.
Manually turn   into   in a couple of places.
Re-zip the EPUB.
Run epubcheck again.
Try it in Apple Books.

That worked. The errors vanished, epubcheck was happy, and the reader confirmed that the fixed file opened fine in iBooks.

But clearly:

Open the EPUB in a text editor and fix the XHTML by hand

is not a sustainable publishing strategy.

So the next step was to move from “hacky manual fix” to “the pipeline prevents this from happening again”.

HTML vs XHTML, and why linters matter

The underlying issue is straightforward once you remember it:

HTML is very forgiving. Browsers will happily fix up all kinds of broken markup.
XHTML is XML, so it’s not forgiving:

EPUB 3 content files are XHTML. If you feed them sloppy HTML, some readers (like Apple Books) will just refuse to load the chapter.

So I added a manuscript HTML linter to the toolchain, before we ever get to Pandoc or epubcheck.

Roughly, the linter:

Reads the manuscript (ignoring fenced code blocks so it doesn’t complain about < in Perl examples).
Extracts any raw HTML chunks.
Wraps those chunks in a temporary root element.
Uses XML::LibXML to check they’re well-formed XML.
Reports any errors with file and line number.

It’s not trying to be a full HTML validator; it’s just checking: “If this HTML ends up in an EPUB, will the XML parser choke?”

That would have caught the   problem before the book ever left my machine.

Hardening the pipeline: `epubcheck` in the loop

The linter catches the obvious issues in the manuscript; epubcheck is still the final authority on the finished EPUB.

So the pipeline now looks like this:

Lint the manuscript HTML

Catch broken raw HTML/XHTML before conversion.
Build PDF + EPUB via make_book
Run epubcheck on the EPUB

Ensure the final file is standards-compliant.
Only then do we upload it to Leanpub and Amazon, making it available to eager readers.

The nice side-effect of this is that any future changes (new CSS, new template, different metadata) still go through the same gauntlet. If something breaks, the pipeline shouts at me long before a reader has to.

Docker and GitHub Actions: making it reproducible

Having a nice Perl script and a list of tools installed on my laptop is fine for a solo project; it’s not great if:

other authors might want to build their own drafts, or
I want the build to happen automatically in CI.

So the next step was to package everything into a Docker image and wire it into GitHub Actions.

The Docker image is based on a slim Ubuntu and includes:

Perl + cpanm + all CPAN modules from the repo’s cpanfile
pandoc
wkhtmltopdf
Java + epubcheck
The Perl School utility scripts themselves (make_book, check_ms_html, etc.)

The workflow in a book repo is simple:

Mount the book’s Git repo into /work.
Run check_ms_html to lint the manuscript.
Run make_book to build built/*.pdf and built/*.epub.
Run epubcheck on the EPUB.
Upload the built/ artefacts.

GitHub Actions then uses that same image as a container for the job, so every push or pull request can build the book in a clean, consistent environment, without needing each author to install Pandoc, wkhtmltopdf, Java, and a large chunk of CPAN locally.

Why I’m making this public

At this point, the pipeline feels:

modern (Pandoc, HTML/CSS layout, EPUB 3),
robust (lint + epubcheck),
reproducible (Docker + Actions),
and not tied to Perl in any deep way.

Yes, Design Patterns in Modern Perl is a Perl book, and the utilities live under the “Perl School” banner, but nothing is stopping you from using the same setup for your own book on whatever topic you care about.

So I’ve made the utilities available in a public repository (the perlschool-util repo on GitHub). There you’ll find:

the build scripts,
the Dockerfile and helper script,
example GitHub Actions configuration,
and notes on how to structure a book repo.

If you’ve ever thought:

I’d like to write a small technical book, but I don’t want to fight with LaTeX or invent a build system from scratch…

then you’re very much the person I had in mind.

eBook publishing really is pretty easy once you’ve got a solid pipeline. If these tools help you get your ideas out into the world, that’s a win.

And, of course, if you’d like to write a book for Perl School, I’m still very interested in talking to potential authors – especially if you’re doing interesting modern Perl in the real world.

The post Behind the scenes at Perl School Publishing first appeared on Perl Hacks.

Dotcom Survivor Syndrome – How Perl’s Early Success Created the Seeds of Its Downfall

Dave Cross — Sun, 30 Nov 2025 15:50:59 +0000

If you were building web applications during the first dot-com boom, chances are you wrote Perl. And if you’re now a CTO, tech lead, or senior architect, you may instinctively steer teams away from it—even if you can’t quite explain why.

This reflexive aversion isn’t just a preference. It’s what I call Dotcom Survivor Syndrome : a long-standing bias formed by the messy, experimental, high-pressure environment of the early web, where Perl was both a lifeline and a liability.

Perl wasn’t the problem. The conditions under which we used it were. And unfortunately, those conditions, combined with a separate, prolonged misstep over versioning, continue to distort Perl’s reputation to this day.

The Glory Days: Perl at the Heart of the Early Web

In the mid- to late-1990s, Perl was the web’s duct tape.

It powered CGI scripts on Apache servers.
It automated deployments before DevOps had a name.
It parsed logs, scraped data, processed form input, and glued together whatever needed glueing.

Perl 5 , released in 1994, introduced real structure: references, modules, and the birth of CPAN , which became one of the most effective software ecosystems in the world.

Perl wasn’t just part of the early web—it was instrumental in creating it.

The Dotcom Boom: Shipping Fast and Breaking Everything

To understand the long shadow Perl casts, you have to understand the speed and pressure of the dot-com boom.

We weren’t just building websites.

We were inventing how to build websites.

Best practices? Mostly unwritten.

Frameworks? Few existed.

Code reviews? Uncommon.

Continuous integration? Still a dream.

The pace was frantic. You built something overnight, demoed it in the morning, and deployed it that afternoon. And Perl let you do that.

But that same flexibility—its greatest strength—became its greatest weakness in that environment. With deadlines looming and scalability an afterthought, we ended up with:

Thousands of lines of unstructured CGI scripts
Minimal documentation
Global variables everywhere
Inline HTML mixed with business logic
Security holes you could drive a truck through

When the crash came, these codebases didn’t age gracefully. The people who inherited them, often the same people who now run engineering orgs, remember Perl not as a powerful tool, but as the source of late-night chaos and technical debt.

Dotcom Survivor Syndrome: Bias with a Backstory

Many senior engineers today carry these memories with them. They associate Perl with:

Fragile legacy systems
Inconsistent, “write-only” code
The bad old days of early web development

And that’s understandable. But it also creates a bias—often unconscious—that prevents Perl from getting a fair hearing in modern development discussions.

Version Number Paralysis: The Perl 6 Effect

If Dotcom Boom Survivor Syndrome created the emotional case against Perl, then Perl 6 created the optical one.

In 2000, Perl 6 was announced as a ground-up redesign of the language. It promised modern syntax, new paradigms, and a bright future. But it didn’t ship—not for a very long time.

In the meantime:

Perl 5 continued to evolve quietly, but with the implied expectation that it would eventually be replaced.
Years turned into decades , and confusion set in. Was Perl 5 deprecated? Was Perl 6 compatible? What was the future of Perl?

To outsiders—and even many Perl users—it looked like the language was stalled. Perl 5 releases were labelled 5.8, 5.10, 5.12… but never 6. Perl 6 finally emerged in 2015, but as an entirely different language, not a successor.

Eventually, the community admitted what everyone already knew: Perl 6 wasn’t Perl. In 2019, it was renamed Raku.

But the damage was done. For nearly two decades, the version number “6” hung over Perl 5 like a storm cloud – a constant reminder that its future was uncertain, even when that wasn’t true.

This is what I call Version Number Paralysis :

A stalled major version that made the language look obsolete.
A missed opportunity to signal continued relevance and evolution.
A marketing failure that deepened the sense that Perl was a thing of the past.

Even today, many developers believe Perl is “stuck at version 5,” unaware that modern Perl is actively maintained, well-supported, and quite capable.

While Dotcom Survivor Syndrome left many people with an aversion to Perl, Version Number Paralysis gave them an excuse not to look closely at Perl to see if it had changed.

What They Missed While Looking Away

While the world was confused or looking elsewhere, Perl 5 gained:

Modern object systems (Moo, Moose)
A mature testing culture (Test::More, Test2)
Widespread use of best practices (Perl::Critic, perltidy, etc.)
Core team stability and annual releases
Huge CPAN growth and refinements

But those who weren’t paying attention, especially those still carrying dotcom-era baggage, never saw it. They still think Perl looks like it did in 2002.

Can We Move On?

Dotcom Survivor Syndrome is real. So is Version Number Paralysis. Together, they’ve unfairly buried a language that remains fast, expressive, and battle-tested.

We can’t change the past. But we can:

Acknowledge the emotional and historical baggage
Celebrate the role Perl played in inventing the modern web
Educate developers about what Perl really is today
Push back against the assumption that old == obsolete

Conclusion

Perl’s early success was its own undoing. It became the default tool for the first web boom, and in doing so, it took the brunt of that era’s chaos. Then, just as it began to mature, its versioning story confused the industry into thinking it had stalled.

But the truth is that modern Perl is thriving quietly in the margins – maintained by a loyal community, used in production, and capable of great things.

The only thing holding it back is a generation of developers still haunted by memories of CGI scripts, and a version number that suggested a future that never came.

Maybe it’s time we looked again.

The post Dotcom Survivor Syndrome – How Perl’s Early Success Created the Seeds of Its Downfall first appeared on Perl Hacks.

Elderly Camels in the Cloud

Dave Cross — Sun, 23 Nov 2025 16:12:23 +0000

In last week’s post I showed how to run a modern Dancer2 app on Google Cloud Run. That’s lovely if your codebase already speaks PSGI and lives in a nice, testable, framework-shaped box.

But that’s not where a lot of Perl lives.

Plenty of useful Perl on the internet is still stuck in old-school CGI – the kind of thing you’d drop into cgi-bin on a shared host in 2003 and then try not to think about too much.

So in this post, I want to show that:

If you can run a Dancer2 app on Cloud Run, you can also run ancient CGI on Cloud Run – without rewriting it.

To keep things on the right side of history, we’ll use nms FormMail rather than Matt Wright’s original script, but the principle is exactly the same.

Prerequisites: Google Cloud and Cloud Run

If you already followed the Dancer2 post and have Cloud Run working, you can skip this section and go straight to “Wrapping nms FormMail in PSGI”.

If not, here’s the minimum you need.

Google account and project
Enable billing
Install the gcloud CLI
Enable required APIs
Create a Docker repository in Artifact Registry

That’s all the GCP groundwork. Now we can worry about Perl.

The starting point: an old CGI FormMail

Our starting assumption:

You already have a CGI script like nms FormMail
It’s a single “.pl” file, intended to be dropped into “cgi-bin”
It expects to be called via the CGI interface and send mail using:

open my $mail, '|-', '/usr/sbin/sendmail -t' or die "Can't open sendmail: $!";

On a traditional host, Apache (or similar) would:

parse the HTTP request
set CGI environment variables (REQUEST_METHOD, QUERY_STRING, etc.)
run formmail.pl as a process
let it call /usr/sbin/sendmail

Cloud Run gives us none of that. It gives us:

a HTTP endpoint
backed by a container
listening on a port ($PORT)

Our job is to recreate just enough of that old environment inside a container.

We’ll do that in two small pieces:

A PSGI wrapper that emulates CGI.
A sendmail shim so the script can still “talk” sendmail.

Architecture in one paragraph

Inside the container we’ll have:

nms FormMail – unchanged CGI script at /app/formmail.pl
PSGI wrapper (app.psgi) – using CGI::Compile and CGI::Emulate::PSGI
Plack/Starlet – a simple HTTP server exposing app.psgi on $PORT
msmtp-mta – providing /usr/sbin/sendmail and relaying mail to a real SMTP server

Cloud Run just sees “HTTP service running in a container”. Our CGI script still thinks it’s on a early-2000s shared host.

Step 1 – Wrapping nms FormMail in PSGI

First we write a tiny PSGI wrapper. This is the only new Perl we need:

# app.psgi

use strict;
use warnings;

use CGI::Compile;
use CGI::Emulate::PSGI;

# Path inside the container
my $cgi_script = "/app/formmail.pl";

# Compile the CGI script into a coderef
my $cgi_app = CGI::Compile->compile($cgi_script);

# Wrap it in a PSGI-compatible app
my $app = CGI::Emulate::PSGI->handler($cgi_app);

# Return PSGI app
$app;

That’s it.

CGI::Compile loads the CGI script and turns its main package into a coderef.
CGI::Emulate::PSGI fakes the CGI environment for each request.
The CGI script doesn’t know or care that it’s no longer being run by Apache.

Later, we’ll run this with:

plackup -s Starlet -p ${PORT:-8080} app.psgi

Step 2 – Adding a sendmail shim

Next problem: Cloud Run doesn’t give you a local mail transfer agent.

There is no real /usr/sbin/sendmail, and you wouldn’t want to run a full MTA in a stateless container anyway.

Instead, we’ll install msmtp-mta , a light-weight SMTP client that includes a sendmail-compatible wrapper. It gives you a /usr/sbin/sendmail binary that forwards mail to a remote SMTP server (Mailgun, SES, your mail provider, etc.).

From the CGI script’s point of view, nothing changes:

open my $mail, '|-', '/usr/sbin/sendmail -t'
  or die "Can't open sendmail: $!";
# ... write headers and body ...
close $mail;

Under the hood, msmtp ships it off to your configured SMTP server.

We’ll configure msmtp from environment variables at container start-up , so Cloud Run’s --set-env-vars values are actually used.

Step 3 – Dockerfile (+ entrypoint) for Perl, PSGI and sendmail shim

Here’s a complete Dockerfile that pulls this together.

FROM perl:5.40

# Install msmtp-mta as a sendmail-compatible shim
RUN apt-get update && \
    apt-get install -y --no-install-recommends msmtp-mta ca-certificates && \
    rm -rf /var/lib/apt/lists/*

# Install Perl dependencies
RUN cpanm --notest \
    CGI::Compile \
    CGI::Emulate::PSGI \
    Plack \
    Starlet

WORKDIR /app

# Copy nms FormMail (unchanged) and the PSGI wrapper
COPY formmail.pl app.psgi /app/
RUN chmod 755 /app/formmail.pl

# Entrypoint script that:
# 1. writes /etc/msmtprc from environment variables
# 2. starts the PSGI server
COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

ENV PORT=8080

EXPOSE 8080

CMD ["docker-entrypoint.sh"]

And here’s the docker-entrypoint.sh script:

#!/bin/sh

set -e

# Reasonable defaults

: "${MSMTP_ACCOUNT:=default}"
: "${MSMTP_PORT:=587}"

if [-z "$MSMTP_HOST"] || [-z "$MSMTP_USER"] || [-z "$MSMTP_PASSWORD"] || [-z "$MSMTP_FROM"]; then
  echo "Warning: MSMTP_* environment variables not fully set; mail probably won't work." >&2
fi

cat > /etc/msmtprc <<EOF
defaults
auth on
tls on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
logfile /var/log/msmtp.log

account ${MSMTP_ACCOUNT}
host ${MSMTP_HOST}
port ${MSMTP_PORT}
user ${MSMTP_USER}
password ${MSMTP_PASSWORD}
from ${MSMTP_FROM}

account default : ${MSMTP_ACCOUNT}
EOF

chmod 600 /etc/msmtprc

# Start the PSGI app
exec plackup -s Starlet -p "${PORT:-8080}" app.psgi

Key points you might want to note:

We never touch formmail.pl. It goes into /app and that’s it.
msmtp gives us /usr/sbin/sendmail, so the CGI script stays in its 1990s comfort zone.
The entrypoint writes /etc/msmtprc at runtime, so Cloud Run’s environment variables are actually used.

Step 4 – Building and pushing the image

With the Dockerfile and docker-entrypoint.sh in place, we can build and push the image to Artifact Registry.

I’ll assume:

Project ID: PROJECT_ID
Region: europe-west1
Repository: formmail-repo
Image name: nms-formmail

First, build the image locally :

docker build -t europe-west1-docker.pkg.dev/PROJECT_ID/formmail-repo/nms-formmail:latest .

Then configure Docker to authenticate against Artifact Registry:

gcloud auth configure-docker europe-west1-docker.pkg.dev

Now push the image:

docker push europe-west1-docker.pkg.dev/PROJECT_ID/formmail-repo/nms-formmail:latest

If you’d rather not install Docker locally, you can let Google Cloud Build do this for you:

gcloud builds submit \
  --tag europe-west1-docker.pkg.dev/PROJECT_ID/formmail-repo/nms-formmail:latest

Use whichever workflow your team is happier with; Cloud Run doesn’t care how the image got there.

Step 5 – Deploying to Cloud Run

Now we can create a Cloud Run service from that image.

You’ll need SMTP settings from somewhere (Mailgun, SES, your mail provider). I’ll use “Mailgun-ish” examples here; adjust as required.

gcloud run deploy nms-formmail \
  --image=europe-west1-docker.pkg.dev/PROJECT_ID/formmail-repo/nms-formmail:latest \
  --platform=managed \
  --region=europe-west1 \
  --allow-unauthenticated \
  --set-env-vars MSMTP_HOST=smtp.mailgun.org \
  --set-env-vars MSMTP_PORT=587 \
  --set-env-vars MSMTP_USER=postmaster@mg.example.com \
  --set-env-vars MSMTP_PASSWORD=YOUR_SMTP_PASSWORD \
  --set-env-vars MSMTP_FROM=webforms@example.com

Cloud Run will give you a HTTPS URL, something like:

https://nms-formmail-abcdefgh-uk.a.run.app

Your HTML form (on whatever website you like) can now post to that URL.

For example:

<form action="https://nms-formmail-abcdefgh-uk.a.run.app/formmail.pl" method="post">
  <input type="hidden" name="recipient" value="contact@example.com">
  <input type="email" name="email" required>
  <textarea name="comments" required></textarea>
  <button type="submit">Send</button>
</form>

Depending on how you wire the routes, you may also just post to / – the important point is that the request hits the PSGI app, which faithfully re-creates the CGI environment and hands control to formmail.pl.

How much work did we actually do?

Compared to the Dancer2 example, the interesting bit here is what we didn’t do:

We didn’t convert the CGI script to PSGI.
We didn’t add a framework.
We didn’t touch its mail-sending code.

We just:

Wrapped it with CGI::Emulate::PSGI.
Dropped a sendmail shim in front of a real SMTP service.
Put it in a container and let Cloud Run handle the scaling and HTTPS.

If you’ve still got a cupboard full of old CGI scripts doing useful work, this is a nice way to:

get them off fragile shared hosting
put them behind HTTPS
run them in an environment you understand (Docker + Cloud Run)
without having to justify a full rewrite up front

When should you rewrite instead?

This trick is handy, but it’s not a time machine.

If you find yourself wanting to:

add tests
share logic between multiple scripts
integrate with a modern app or API
do anything more complex than “receive a form, send an email”

…then you probably do want to migrate the logic into a Dancer2 (or other PSGI) app properly.

But as a first step – or as a way to de-risk moving away from legacy hosting – wrapping CGI for Cloud Run works surprisingly well.

FormMail is still probably a bad idea

All of this proves that you can take a very old CGI script and run it happily on Cloud Run. It does not magically turn FormMail into a good idea in 2025.

The usual caveats still apply:

Spam and abuse – anything that will send arbitrary email based on untrusted input is a magnet for bots. You’ll want rate limiting, CAPTCHA, some basic content checks, and probably logging and alerting.
Validation and sanitisation – a lot of classic FormMail deployments were “drop it in and hope”. If you’re going to the trouble of containerising it, you should at least ensure it’s a recent nms version, configured properly, and locked down to only the recipients you expect.
Better alternatives – for any new project, you’d almost certainly build a tiny API endpoint or Dancer2 route that validates input, talks to a proper mail-sending service, and returns JSON. The CGI route is really a migration trick, not a recommendation for fresh code.

So think of this pattern as a bridge for legacy, not a template for greenfield development.

Conclusion

In the previous post we saw how nicely a modern Dancer2 app fits on Cloud Run: PSGI all the way down, clean deployment, no drama. This time we’ve taken almost the opposite starting point – a creaky old CGI FormMail – and shown that you can still bring it along for the ride with surprisingly little effort.

We didn’t rewrite the script, we didn’t introduce a framework, and we didn’t have to fake an entire 90s LAMP stack. We just wrapped the CGI in PSGI, dropped in a sendmail shim, and let Cloud Run do what it does best: run a container that speaks HTTP.

If you’ve got a few ancient Perl scripts quietly doing useful work on shared hosting, this might be enough to get them onto modern infrastructure without a big-bang rewrite. And once they’re sitting in containers, behind HTTPS, with proper logging and observability, you’ll be in a much better place to decide which ones deserve a full Dancer2 makeover – and which ones should finally be retired.

The post Elderly Camels in the Cloud first appeared on Perl Hacks.

Dancing in the Clouds: Moving Dancer2 Apps from a VPS to Cloud Run

Dave Cross — Thu, 13 Nov 2025 16:48:00 +0000

For years, most of my Perl web apps lived happily enough on a VPS. I had full control of the box, I could install whatever I liked, and I knew where everything lived.

In fact, over the last eighteen months or so, I wrote a series of blog posts explaining how I developed a system for deploying Dancer2 apps and, eventually, controlling them using systemd. I’m slightly embarrassed by those posts now.

Because the control that my VPS gave me also came with a price: I also had to worry about OS upgrades, SSL renewals, kernel updates, and the occasional morning waking up to automatic notifications that one of my apps had been offline since midnight.

Back in 2019, I started writing a series of blog posts called Into the Cloud that would follow my progress as I moved all my apps into Docker containers. But real life intruded and I never made much progress on the project.

Recently, I returned to this idea (yes, I’m at least five years late here!) I’ve been working on migrating those old Dancer2 applications from my IONOS VPS to Google Cloud Run. The difference has been amazing. My apps now run in their own containers, scale automatically, and the server infrastructure requires almost no maintenance.

This post walks through how I made the jump – and how you can too – using Perl, Dancer2, Docker, GitHub Actions, and Google Cloud Run.

Why move away from a VPS?

Running everything on a single VPS used to make sense. You could ssh in, restart services, and feel like you were in control. But over time, the drawbacks grow:

You have to maintain the OS and packages yourself.
One bad app or memory leak can affect everything else.
You’re paying for full-time CPU and RAM even when nothing’s happening.
Scaling means provisioning a new server — not something you do in a coffee break.

Cloud Run, on the other hand, runs each app as a container and only charges you while requests are being served. When no-one’s using your app, it scales to zero and costs nothing.

Even better: no servers to patch, no ports to open, no SSL certificates to renew — Google does all of that for you.

What we’ll build

Here’s the plan. We’ll take a simple Dancer2 app and:

Package it as a Docker container.
Build that container automatically in GitHub Actions.
Deploy it to Google Cloud Run , where it runs securely and scales automatically.
Map a custom domain to it and forget about server admin forever.

If you’ve never touched Docker or Cloud Run before, don’t worry – I’ll explain what’s going on as we go.

Why Cloud Run fits Perl surprisingly well

Perl’s ecosystem has always valued stability and control. Containers give you both: you can lock in a Perl version, CPAN modules, and any shared libraries your app needs. The image you build today will still work next year.

Cloud Run runs those containers on demand. It’s effectively a managed starman farm where Google handles the hard parts – scaling, routing, and HTTPS.

You pay for CPU and memory per request, not per server. For small or moderate-traffic Perl apps, it’s often well under £1/month.

Step 1: Dockerising a Dancer2 app

If you’re new to Docker, think of it as a way of bundling your whole environment — Perl, modules, and configuration — into a portable image. It’s like freezing a working copy of your app so it can run identically anywhere.

Here’s a minimal Dockerfile for a Dancer2 app:

FROM perl:5.42
LABEL maintainer="dave@perlhacks.com"

# Install Carton and Starman
RUN cpanm Carton Starman

# Copy the app into the container
COPY . /app
WORKDIR /app

# Install dependencies
RUN carton install --deployment

EXPOSE 8080
CMD ["carton", "exec", "starman", "--port", "8080", "bin/app.psgi"]

Let’s break that down:

FROM perl:5.42 — starts from an official Perl image on Docker Hub.
Carton keeps dependencies consistent between environments.
The app is copied into /app, and carton install --deployment installs exactly what’s in your cpanfile.snapshot.
The container exposes port 8080 (Cloud Run’s default).
The CMD runs Starman, serving your Dancer2 app.

To test it locally:

docker build -t myapp . docker run -p 8080:8080 myapp

Then visit http://localhost:8080. If you see your Dancer2 homepage, you’ve successfully containerised your app.

Step 2: Building the image in GitHub Actions

Once it works locally, we can automate it. GitHub Actions will build and push our image to Google Artifact Registry whenever we push to main or tag a release.

Here’s a simplified workflow file (.github/workflows/build.yml):

name: Build container

on:
  push:
    branches: [main]
    tags: ['v*']
  workflow_dispatch:

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

      - uses: google-github-actions/setup-gcloud@v3
        with:
          project_id: ${{ secrets.GCP_PROJECT }}
          service_account_email: ${{ secrets.GCP_SA_EMAIL }}
          workload_identity_provider: ${{ secrets.GCP_WIF_PROVIDER }}

      - name: Build and push image
        run: |
          IMAGE="europe-west1-docker.pkg.dev/${{ secrets.GCP_PROJECT }}/containers/myapp:$GITHUB_SHA"
          docker build -t $IMAGE .
          docker push $IMAGE

You’ll notice a few secrets referenced in the workflow — things like your Google Cloud project ID and credentials. These are stored securely in GitHub Actions. When the workflow runs, GitHub uses those secrets to authenticate as you and access your Google Cloud account, so it can push the new container image or deploy your app.

You only set those secrets up once, and they’re encrypted and hidden from everyone else — even if your repository is public.

Once that’s set up, every push builds a fresh, versioned container image.

Step 3: Deploying to Cloud Run

Now we’re ready to run it in the cloud. We’ll do that using Google’s command line program, gcloud. It’s available from Google’s official downloads or through most Linux package managers — for example:

# Fedora, RedHat or similar
sudo dnf install google-cloud-cli
# or on Debian/Ubuntu:
sudo apt install google-cloud-cli

Once installed, authenticate it with your Google account:

gcloud auth login
gcloud config set project your-project-id

That links the CLI to your Google Cloud project and lets it perform actions like deploying to Cloud Run.

Once that’s done, you can deploy manually from the command line:

gcloud run deploy myapp \ --image=europe-west1-docker.pkg.dev/MY_PROJECT/containers/myapp:$GITHUB_SHA \ --region=europe-west1 \ --allow-unauthenticated \ --port=8080

This tells Cloud Run to start a new service called myapp, using the image we just built.

After a minute or two, Google will give you a live HTTPS URL, like:

- https://myapp-abcdef12345-ew.a.run.app

Visit it — and if all went well, you’ll see your familiar Dancer2 app, running happily on Cloud Run.

To connect your own domain, run:

gcloud run domain-mappings create \
--service=myapp \
--domain=myapp.example.com

Then update your DNS records as instructed. Within an hour or so, Cloud Run will issue a free SSL certificate for you.

Step 4: Automating the deployment

Once the manual deployment works, we can automate it too.

Here’s a second GitHub Actions workflow (deploy.yml) that triggers after a successful build:

name: Deploy container

on:
  workflow_run:
    workflows: ["Build container"]
    types: [completed]

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}

    steps:
      - uses: google-github-actions/setup-gcloud@v3
        with:
          project_id: ${{ secrets.GCP_PROJECT }}
          service_account_email: ${{ secrets.GCP_SA_EMAIL }}
          workload_identity_provider: ${{ secrets.GCP_WIF_PROVIDER }}

      - name: Deploy to Cloud Run
        run: |
          gcloud run deploy myapp \
            --image=europe-west1-docker.pkg.dev/${{ secrets.GCP_PROJECT }}/containers/myapp:$GITHUB_SHA \
            --region=europe-west1 \
            --allow-unauthenticated \
            --port=8080

Now every successful push to main results in an automatic deployment to production.

You can take it further by splitting environments — e.g. main deploys to staging, tagged releases to production — but even this simple setup is a big step forward from ssh and git pull.

Step 5: Environment variables and configuration

Each Cloud Run service can have its own configuration and secrets. You can set these from the console or CLI:

gcloud run services update myapp \
  --set-env-vars="DANCER_ENV=production,DATABASE_URL=postgres://..."

In your Dancer2 app, you can then access them with:

$ENV{DATABASE_URL}

It’s a good idea to keep database credentials and API keys out of your code and inject them at deploy time like this.

Step 6: Monitoring and logs

Cloud Run integrates neatly with Google Cloud’s logging tools.

To see recent logs from your app:

gcloud logs read --project=$PROJECT_NAME --service=myapp

You’ll see your Dancer2 warn and die messages there too, because STDOUT and STDERR are automatically captured.

If you prefer a UI, you can use the Cloud Console’s Log Explorer to filter by service or severity.

Step 7: The payoff

Once you’ve done one migration, the next becomes almost trivial. Each Dancer2 app gets:

Its own Dockerfile and GitHub workflows.
Its own Cloud Run service and domain.
Its own scaling and logging.

And none of them share a single byte of RAM with each other.

Here’s how the experience compares:

Aspect	Old VPS	Cloud Run
OS maintenance	Manual upgrades	Managed
Scaling	Fixed size	Automatic
SSL	Let’s Encrypt renewals	Automatic
Deployment	SSH + git pull	Push to GitHub
Cost	Fixed monthly	Pay-per-request
Downtime risk	One app can crash all	Each isolated

For small apps with light traffic, Cloud Run often costs pennies per month – less than the price of a coffee for peace of mind.

Lessons learned

After a few migrations, a few patterns emerged:

Keep apps self-contained. Don’t share config or code across services; treat each app as a unit.
Use digest-based deploys. Deploy by image digest (@sha256:...) rather than tag for true immutability.
Logs are your friend. Cloud Run’s logs are rich; you rarely need to ssh anywhere again.
Cold starts exist, but aren’t scary. If your app is infrequently used, expect the first request after a while to take a second longer.
CI/CD is liberating. Once the pipeline’s in place, deployment becomes a non-event.

Costs and practicalities

One of the most pleasant surprises was the cost. My smallest Dancer2 app, which only gets a handful of requests each day, usually costs under £0.50/month on Cloud Run. Heavier ones rarely top a few pounds.

Compare that to the £10–£15/month I was paying for the old VPS — and the VPS didn’t scale, didn’t auto-restart cleanly, and didn’t come with HTTPS certificates for free.

What’s next

This post covers the essentials: containerising a Dancer2 app and deploying it to Cloud Run via GitHub Actions.

In future articles, I’ll look at:

Connecting to persistent databases.
Using caching.
Adding monitoring and dashboards.
Managing secrets with Google Secret Manager.

Conclusion

After two decades of running Perl web apps on traditional servers, Cloud Run feels like the future has finally caught up with me.

You still get to write your code in Dancer2 – the framework that’s made Perl web development fun for years – but you deploy it in a way that’s modern, repeatable, and blissfully low-maintenance.

No more patching kernels. No more 3 a.m. alerts. Just code, commit, and dance in the clouds.

The post Dancing in the Clouds: Moving Dancer2 Apps from a VPS to Cloud Run first appeared on Perl Hacks.

Easy SEO for lazy programmers

Dave Cross — Wed, 24 Sep 2025 10:22:53 +0000

A few of my recent projects—like Cooking Vinyl Compilations and ReadABooker—aim to earn a little money via affiliate links. That only works if people actually find the pages, share them, and get decent previews in social apps. In other words: the boring, fragile glue of SEO and social meta tags matters.

As I lined up a couple more sites in the same vein, I noticed I was writing very similar code again and again: take an object with title, url, image, description, and spray out the right <meta> tags for Google, Twitter, Facebook, iMessage, Slack, and so on. It’s fiddly, easy to get 80% right, and annoying to maintain across projects. So I pulled it into a small Moo role—MooX::Role::SEOTags—that any page-ish class can consume and just emit the right tags.

What are these tags and why should you care?

When someone shares your page, platforms read a handful of standardised tags to decide what to show in the preview:

Open Graph (og:*) — The de-facto standard for title, description, URL, image, and type. Used by Facebook, WhatsApp, Slack, iMessage and others.
Twitter Cards (twitter:*) — Similar idea for Twitter/X; the common pattern is twitter:card=summary_large_image plus title/description/image.
Classic SEO tags — <title>, <meta name="description">, and a canonical URL tell search engines what the page is about and which URL is the “official” one.

MooX::Role::SEOTags gives you one method that renders all of that, consistently, from your object’s attributes.

For more information about OpenGraph, see ogp.me.

What it does

MooX::Role::SEOTags adds a handful of attributes and helper methods so any Moo (or Moose) class can declare the bits of information that power social previews and search snippets, then render them as HTML.

Open Graph tags (og:title, og:type, og:url, og:image, etc.)
Twitter Card tags (twitter:card, twitter:title, twitter:description, twitter:image)
Standard SEO: <title>, meta description, canonical <link rel="canonical">
A single method to render the whole block with one call
But also individual methods to give you more control over tag placement

That’s the whole job: define attributes → get valid tags out.

Quick start

Install the role using your favourite CPAN module installation tool.

cpanm MooX::Role::SEOTags

Then, in your code, you will need to add some attributes or methods that define the pieces of information the role needs. The role requires four pieces of information – og_title, og_description, og_url and og_type – and og_image is optional (but highly recommended).

So a simple class might look like this:

package MyPage;
use Moo;
with 'MooX::Role::SEOTags';

# minimal OG fields
has og_title => (is => 'ro', required => 1);
has og_type => (is => 'ro', required => 1); # e.g. 'article'
has og_url => (is => 'ro', required => 1);
has og_description => (is => 'ro');

# optional niceties
has og_image => (is => 'ro'); # absolute URL
has twitter_card => (is => 'ro', default => sub { 'summary_large_image' });

1;

And then you create the object:

my $page = MyPage->new(
  og_title => 'How to Title a Title',
  og_type => 'article',
  og_url => 'https://example.com/post/title',
  og_image => 'https://example.com/img/hero.jpg',
  og_description => 'A short, human description of the page.',
);

Then you can call the various *_tag and *_tags methods to get the correct HTML for the various tags.

The easiest option is to just produce all of the tags in one go:

say $page->tags;

But, for more control, you can call individual methods:

say $page->title_tag;
say $page->canonical_tag;
say $page->og_tags;
# etc...

Depending on which combination of method calls you use, the output will look something like this:

<title>How to Title a Title</title>
<meta name="description" content="A short, human description of the page.">
<link rel="canonical" href="https://example.com/post/title">

<meta property="og:title" content="How to Title a Title">
<meta property="og:type" content="article">
<meta property="og:url" content="https://example.com/post/title">
<meta property="og:image" content="https://example.com/img/hero.jpg">

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="How to Title a Title">
<meta name="twitter:description" content="A short, human description of the page.">
<meta name="twitter:image" content="https://example.com/img/hero.jpg">

In many cases, you’ll be pulling the data from a database and displaying the output using a templating system like the Template Toolkit.

my $tt = Template->new;

my $object = $resultset->find({ slug => $some_slug });

$tt->process('page.tt', { object => $object }, "$some_slug/index.html");

In this case, you’d just add a single call to the

of your page template.

<head>

  <!-- lots of other HTML -->

[% object.tags %]

</head>

A note if you used my earlier Open Graph role

If you spotted MooX::Role::OpenGraph arrive on MetaCPAN recently: SEOTags is the “grown-up” superset. It does Open Graph and Twitter and standard tags, so you only need one role. The old module is scheduled for deletion from MetaCPAN.

SEO tags and JSON-LD

These tags are only one item in the SEO toolkit that you’d use to increase the visibility of your website. Another useful tool is JSON-LD – which allows you to add a machine-readable description of the information that your page contains. Google loves JSON-LD. And it just happens that I have another Moo role called MooX::Role::JSON_LD which makes it easy to add that to your page too. I wrote a blog post about using that earlier this year.

In conclusion

If you’ve got even one page that deserves to look smarter in search and social previews, now’s the moment. Pick a page, add a title, description, canonical URL and a decent image, and let MooX::Role::SEOTags spit out the right tags every time (and, if you fancy richer results, pair it with MooX::Role::JSON_LD). Share the link in Slack/WhatsApp/Twitter to preview it, fix anything that looks off, and ship. It’s a 20-minute tidy-up that can lift click-throughs for years—so go on, give one of your pages a quick SEO spruce-up today.

The post Easy SEO for lazy programmers first appeared on Perl Hacks.

Stop using your system Perl

Dave Cross — Fri, 27 Jun 2025 12:58:04 +0000

Recently, Gabor ran a poll in a Perl Facebook community asking which version of Perl people used in their production systems. The results were eye-opening—and not in a good way. A surprisingly large number of developers replied with something along the lines of “whatever version is included with my OS.”

If that’s you, this post is for you. I don’t say that to shame or scold—many of us started out this way. But if you’re serious about writing and running Perl in 2025, it’s time to stop relying on the system Perl.

Let’s unpack why.

What is “System Perl”?

When we talk about the system Perl, we mean the version of Perl that comes pre-installed with your operating system—be it a Linux distro like Debian or CentOS, or even macOS. This is the version used by the OS itself for various internal tasks and scripts. It’s typically located in /usr/bin/perl and tied closely to system packages.

It’s tempting to just use what’s already there. But that decision brings a lot of hidden baggage—and some very real risks.

Which versions of Perl are officially supported?

The Perl Core Support Policy states that only the two most recent stable release series of Perl are supported by the Perl development team [Update: fixed text in previous sentence]. As of mid-2025, that means:

Perl 5.40 (released May 2024)
Perl 5.38 (released July 2023)

If you’re using anything older—like 5.36, 5.32, or 5.16—you’re outside the officially supported window. That means no guaranteed bug fixes, security patches, or compatibility updates from core CPAN tools like ExtUtils::MakeMaker, Module::Build, or Test::More.

Using an old system Perl often means you’re several versions behind , and no one upstream is responsible for keeping that working anymore.

Why using System Perl is a problem

1. It’s often outdated

System Perl is frozen in time—usually the version that was current when the OS release cycle began. Depending on your distro, that could mean Perl 5.10, 5.16, or 5.26—versions that are years behind the latest stable Perl (currently 5.40).

This means you’re missing out on:

New language features (builtin, class/method/field, signatures, try/catch)
Performance improvements
Bug fixes
Critical security patches
Support: anything older than Perl 5.38 is no longer officially maintained by the core Perl team

If you’ve ever looked at modern Perl documentation and found your code mysteriously breaking, chances are your system Perl is too old.

2. It’s not yours to mess with

System Perl isn’t just a convenience—it’s a dependency. Your operating system relies on it for package management, system maintenance tasks, and assorted glue scripts. If you install or upgrade CPAN modules into the system Perl (especially with cpan or cpanm as root), you run the risk of breaking something your OS depends on.

It’s a kind of dependency hell that’s completely avoidable— if you stop using system Perl.

3. It’s a barrier to portability and reproducibility

When you use system Perl, your environment is essentially defined by your distro. That’s fine until you want to:

Move your application to another system
Run CI tests on a different platform
Upgrade your OS
Onboard a new developer

You lose the ability to create predictable, portable environments. That’s not a luxury— it’s a requirement for sane development in modern software teams.

What you should be doing instead

1. Use `perlbrew` or `plenv`

These tools let you install multiple versions of Perl in your home directory and switch between them easily. Want to test your code on Perl 5.32 and 5.40? perlbrew makes it a breeze.

You get:

A clean separation from system Perl
The freedom to upgrade or downgrade at will
Zero risk of breaking your OS

It takes minutes to set up and pays for itself tenfold in flexibility.

2. Use `local::lib` or `Carton`

Managing CPAN dependencies globally is a recipe for pain. Instead, use:

local::lib: keeps modules in your home directory.
Carton: locks your CPAN dependencies (like npm or pip) so deployments are repeatable.

Your production system should run with exactly the same modules and versions as your dev environment. Carton helps you achieve that.

3. Consider Docker

If you’re building larger apps or APIs, containerising your Perl environment ensures true consistency across dev, test, and production. You can even start from a system Perl inside the container—as long as it’s isolated and under your control.

You never want to be the person debugging a bug that only happens on production, because prod is using the distro’s ancient Perl and no one can remember which CPAN modules got installed by hand.

The benefits of managing your own Perl

Once you step away from the system Perl, you gain:

Access to the full language. Use the latest features without backports or compatibility hacks.
Freedom from fear. Install CPAN modules freely without the risk of breaking your OS.
Portability. Move projects between machines or teams with minimal friction.
Better testing. Easily test your code across multiple Perl versions.
Security. Stay up to date with patches and fixes on your schedule, not the distro’s.
Modern practices. Align your Perl workflow with the kinds of practices standard in other languages (think virtualenv, rbenv, nvm, etc.).

“But it just works…”

I know the argument. You’ve got a handful of scripts, or maybe a cron job or two, and they seem fine. Why bother with all this?

Because “it just works” only holds true until:

You upgrade your OS and Perl changes under you.
A script stops working and you don’t know why.
You want to install a module and suddenly apt is yelling at you about conflicts.
You realise the module you need requires Perl 5.34, but your system has 5.16.

Don’t wait for it to break. Get ahead of it.

The first step

You don’t have to refactor your entire setup overnight. But you can do this:

Install perlbrew and try it out.
Start a new project with Carton to lock dependencies.
Choose a current version of Perl and commit to using it moving forward.

Once you’ve seen how smooth things can be with a clean, controlled Perl environment, you won’t want to go back.

TL;DR

Your system Perl is for your operating system—not for your apps. Treat it as off-limits. Modern Perl deserves modern tools, and so do you.

Take the first step. Your future self (and probably your ops team) will thank you.

The post Stop using your system Perl first appeared on Perl Hacks.

Forem: Dave Cross

Writing a TOON Module for Perl

What TOON Is

TOON vs JSON vs YAML

JSON

YAML

TOON

Why People Think TOON Is Useful

Why I Wrote a Perl Module

Design Goals

1. Familiar OO Interface

2. Pure Perl Implementation

3. Clean Separation of Components

4. Do the Simple Things Well First

Example Usage (OO Style)

Encoding

Decoding

Convenience Functions

Command Line Tool

Final Thoughts

Still on the [b]leading edge

The Symptom

When This Bug Appears

The Real Culprit

The Workaround

The Proper Fix

When Do I Remove the Workaround?

Life on the Bleading Edge

Your README Is Already a Website

Announcing readme-to-index — My First GitHub Marketplace Release 🎉

Why I Built It

What It Does

Usage

Available Options

readme

output

css_url

install_pandoc

extra_pandoc_args

Enabling GitHub Pages

Example Complete Workflow

Why Not Just Use Jekyll?

1. Simplicity

2. Pipeline-Friendly

A Small Milestone

Treating GitHub Copilot as a Contributor

It Starts With a Proper Issue

The Pull Request Arrives

Watching Copilot Think

Teaching Copilot About Your Project

1. Custom Repository Instructions

2. Customising the Copilot Development Environment

Reviewing the Work

Why This Feels Different

A Small but Important Point for the Perl Community

The Real Shift

Links

I Built a Tiny Domain Inventory Tool (Because I Used to Buy Too Many Domains)

What I wanted (and what I very deliberately didn’t)

What the tool does

Architecture: aggressively boring (by design)

DNS and RDAP: best-effort, not gospel

Provider guessing (aka “useful lies”)

DNS provider detection

Hosting provider detection (and Cloudflare honesty)

Caching with intent

What this tool is not

Possible future improvements (and non-improvements)

Why I’m happy with it

App::HTTPThis: the tiny web server I keep reaching for

Why I’ve used it for years

Why I took it over

What I’ve done since taking it over

1) Serve index pages by default (autoindex)

2) Prettier index pages

3) A config file

4) --host option

The Bonjour feature (and what it’s for)

Related tools in the same family

Wrapping up

Announcing `readme-to-index` — My First GitHub Marketplace Release 🎉

`readme`

`output`

`css_url`

`install_pandoc`

`extra_pandoc_args`

4) `--host` option

Choosing tools: Pandoc and `wkhtmltopdf` (and no LaTeX, thanks)

Discovering `epubcheck`

Hardening the pipeline: `epubcheck` in the loop

1. Use `perlbrew` or `plenv`

2. Use `local::lib` or `Carton`