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](https://metacpan.org/pod/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:

1. It is easier for humans to read than JSON.
2. It is less ambiguous and complex than YAML.
3. It maps cleanly to the JSON data model.
4. It is relatively easy to parse.
5. 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.

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

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

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';
  ...
}

package WebServer::DirIndex;

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

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.

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 .

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?

• WebServer::DirIndex repo
• Closed issues
• Closed PRs

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

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.

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.

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 </br>.

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

• In HTML, <br> is fine.

• In XHTML (which is XML), you must use <br /> (self-closing) or <br></br>.

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 Pandoc’s EPUB creation 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:

1. Unzip the generated EPUB.

2. Open the offending XHTML file.

3. Manually turn <br> into <br /> in a couple of places.

4. Re-zip the EPUB.

5. Run epubcheck again.

6. 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:

  • empty elements must be self-closed (<br />, <img />, <hr />, etc.),

  • tags must be properly nested and balanced,

  • attributes must be quoted.

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 <br> 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:

1. Lint the manuscript HTML
   Catch broken raw HTML/XHTML before conversion.

2. Build PDF + EPUB via make_book

   • Generate front matter from metadata (cover, title pages, copyright).

   • Turn Markdown + front matter into HTML.

   • Use wkhtmltopdf for a print-ready PDF.

   • Use Pandoc for the EPUB.

3. Run epubcheck on the EPUB
   Ensure the final file is standards-compliant.

4. 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.

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.

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.

1. Google account and project

   • Go to the Google Cloud Console.

   • Create a new project (e.g. “perl-cgi-cloud-run-demo”).

2. Enable billing

   • Cloud Run is pay-as-you-go with a generous free tier, but you must attach a billing account to your project.

3. Install the gcloud CLI

   • Install the Google Cloud SDK for your platform.

   • Run:

     gcloud init


     and follow the prompts to:

     • log in

     • select your project

     • pick a default region (I’ll assume “europe-west1” below).

4. Enable required APIs

   In your project:

   gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
c  loudbuild.googleapis.com


5. Create a Docker repository in Artifact Registry

   gcloud artifacts repositories create formmail-repo \
--repository-format=docker \
--location=europe-west1 \
--description="Docker repo for CGI demos"


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:

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:

1. A PSGI wrapper that emulates CGI.

2. 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;

• 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:

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

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"]

#!/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

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

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

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

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

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

<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>

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

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:

1. Package it as a Docker container.

2. Build that container automatically in GitHub Actions.

3. Deploy it to Google Cloud Run, where it runs securely and scales automatically.

4. 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"]

• 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:

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

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

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

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:

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

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

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:

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.

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 <head> 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.

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.