Subscribe

Serving ads.txt from Caddy without touching the Ghost theme

A few weeks after moving my Ghost blog to Docker, AdSense said earnings were at risk because ads.txt was missing. Here is the small Caddy block that serves it, and how I checked and reloaded it without SSH.

Serving ads.txt from Caddy without touching the Ghost theme

Not long after I moved this blog to a new server, AdSense put a red banner on the dashboard. "Earnings at risk. You need to fix some ads.txt file issues." I opened https://fenixara.com/ads.txt and got a 404.

That one was on me. During the migration I copied the Ghost database and the content folder, and nothing else. Whatever served ads.txt on the old box stayed on the old box, and the old box was already terminated. Nobody notices a missing text file until Google does.

The new setup is Docker Compose with Caddy in front of Ghost (the full story is in the post on migrating a Ghost-CLI blog to Docker Compose). In this blog we will look at serving ads.txt straight from Caddy, checking it, and reloading Caddy without a restart.

What the file needs to be

ads.txt is a plain text file at the root of your domain. It lists who is allowed to sell ads on your site. For AdSense it's one line with your publisher ID, the word DIRECT and Google's fixed certification ID.

google.com, pub-XXXXXXXXXXXXXXXX, DIRECT, f08c47fec0942fa0

Replace the pub-XXXXXXXXXXXXXXXX with your own publisher ID. AdSense shows the exact line to copy on the ads.txt page in its dashboard, so copy it from there and don't type it.

It has to be at /ads.txt on the domain AdSense knows, return 200 and be plain text. That's it.

Why not the Ghost theme

My first thought was to put the file in the theme. Ghost doesn't work like that though. Theme files are served under /assets/, and only a couple of special root files like robots.txt can come from the theme, as far as I could find. And even if it did work, I'd have to remember to carry it over every time I update or change the theme. That's the same kind of thing that lost the file in the first place.

You could also upload the file somewhere in Ghost and add a redirect for /ads.txt. I didn't like that. A redirect is one more thing for a crawler to follow, and I'd rather give it a plain 200.

Caddy is already in front of everything. So it can just answer that one path itself, and Ghost never sees the request.

The Caddy block

Here is the apex site block with the new part in it.

fenixara.com {
    encode zstd gzip

    handle /ads.txt {
        header Content-Type "text/plain; charset=utf-8"
        respond "google.com, pub-XXXXXXXXXXXXXXXX, DIRECT, f08c47fec0942fa0
"
    }

    reverse_proxy ghost:2368
}

handle /ads.txt only matches that exact path. Inside it, respond writes the body and ends the request, so it never reaches reverse_proxy. Caddy sorts directives in its own fixed order, and handle runs before reverse_proxy whatever order you write them in. I still put it above, it reads better.

I set the Content-Type myself instead of trusting a default. Crawlers are picky about this file, and text/plain is what everyone expects.

The closing quote sits on the next line on purpose. That puts a real newline at the end of the body. A text file without a final newline is usually fine, but I'd rather the file look like a normal file than find out some crawler cares.

The www and blog hostnames already 301 everything to the apex, including /ads.txt, so there is nothing to add for them.

Checking the config before reloading

A typo in the Caddyfile and a full restart is how you take the whole blog down for a text file. So validate first. Caddy runs inside the container, and the Caddyfile is bind mounted in, so the commands go through docker compose exec.

cd /opt/ghost
docker compose exec -T caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile

It prints "Valid configuration" when it's happy. Then reload.

docker compose exec -T caddy caddy reload --config /etc/caddy/Caddyfile --adapter caddyfile

caddy reload pushes the new config through Caddy's admin API inside the container. No restart, no dropped connections, and the certificates are untouched.

Getting the file onto the server without SSH

Port 22 is closed on this host. I use SSM for anything on the box. So the Caddyfile went up base64 encoded inside an SSM command, then validate, then reload, all in one go.

B64=$(base64 < ghost/Caddyfile | tr -d '\n')

jq -n --arg b "$B64" '{commands: [
  "set -e",
  "cd /opt/ghost",
  "echo \($b) | base64 -d > Caddyfile",
  "docker compose exec -T caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile",
  "docker compose exec -T caddy caddy reload --config /etc/caddy/Caddyfile --adapter caddyfile"
]}' > /tmp/ssm-params.json

aws ssm send-command \
  --instance-ids i-0123456789abcdef0 \
  --document-name AWS-RunShellScript \
  --comment "caddy: serve ads.txt" \
  --parameters file:///tmp/ssm-params.json \
  --query 'Command.CommandId' --output text

Then read the output with the command ID it printed.

aws ssm get-command-invocation \
  --command-id <command-id> \
  --instance-id i-0123456789abcdef0 \
  --query '[Status, StandardOutputContent, StandardErrorContent]' --output text

AWS-RunShellScript puts all the lines into one shell script, so the set -e at the top makes it stop at the first failure. A bad config never gets reloaded.

There is one Docker gotcha here worth knowing. The Caddyfile is bind mounted as a single file, and Docker binds the file's inode, not its name. Writing with > truncates the same file in place, so the container sees the change. Tools that write a new file and rename it over the old one (sed -i, a lot of editors) leave the container looking at the old inode. Then caddy reload happily reloads the old config (or tells you nothing changed), and you sit there wondering why nothing changed. If that happens, docker compose restart caddy picks up the new file.

Checking it from outside

Last step, ask for it like crawler would.

curl -si https://fenixara.com/ads.txt

You want HTTP/2 200, content-type: text/plain; charset=utf-8 and your one line. To see the trailing newline is really there, look at the raw bytes.

curl -s https://fenixara.com/ads.txt | od -c | tail -3

The last character before the offset line should be \n. And a quick check that the redirect host works too.

curl -sIL https://www.fenixara.com/ads.txt | grep -i -E "^HTTP|^location"

That should show a 301 to the apex and then a 200.

The AdSense warning don't go away right away. Google has to crawl the file again, and that can take a few days. There's nothing to click, you just wait. The real fix for next time is that the line now lives in the Caddyfile in git, so the next server move takes it along.