Skip to main content
Aonghus Storey

Working with Castopod – Open Source, ActivityPub-Enabled Podcast Host

All blog posts


I've been working with Castopod, which is an open source podcast platform with built-in analytics and Fediverse integration, written in PHP. It's an interesting project, and fills a gap for open source podcast hosts, particularly on the analytics side.

Castopod logo

Finding an open platform

For the Irish Left Archive Podcast we previously had used a custom set up on the main website. Since the site is built with custom content types and an XSLT frontend, this was fairly simple to do. However, the one gap was analytics, and with the complexities of partial downloads, multiple devices and streaming, trying to create a custom solution would have been, at best, painful.

Instead, we used a prefix service that met the de facto standard recommendations for analytics and offered a free tier. That didn't really sit comfortably, and sure enough, once they had captured enough free user's data, they switched to only showing 90 days of history and held that data to ransom!

I didn't want to use an external provider unless I had to, and even the compromise of an analytics prefix doesn't appear to be common – most providers seem to be integrated hosts, effectively focused on advertising – so it was great to come across the Castopod project. And having begun to look at ActivityPub, the Fediverse integration was an interesting bonus.

There are definitely still some rough edges, but the developers are active and helpful, so I'd expect to see a lot ironed out in coming releases. One issue I had was that Castopod wasn't checking the forwarding headers, so that a Docker install saw all requests as coming from localhost, affecting analytics reporting. But the development team were kind enough to offer help and to accept my merge request for this and a few other – and I should emphasise, trivial – contributions.

Castopod features

The built-in analytics are simple, but provide everything you need, with daily total downloads, and device, platform and location reports, as well as per-episode information.

Castopod also includes the option to enable OP3 analytics, which is an early-stages project to create an open prefix analytics service. It's worth noting that both Castopod's own analytics and the OP3 project rightly put a clear emphasis on listener privacy and data anonymisation, which is especially important in the case of open data. For anyone interesting in experimenting with their API, the Irish Left Archive Podcast has OP3 data enabled.

Castopod also implements the new 'Podcasting 2.0' RSS namespace, which, with more adoption, is a great improvement on the hodge-podge of itunes, google and custom provider namespaces.

One of Castopod's big features is the social integration. Each podcast is also an ActivityPub (Fediverse) account, which means you can follow the podcast directly from your Mastodon, Pleroma, Pixelfel etc. account, and comment on episodes using replies. This is a great approach, particularly with the Fediverse seeing a big increase in use, but there are still a lot of rough edges to the implementation. In it's current state, I've had quite a lot of trouble with federation when it comes to communicating with other Fediverse servers, particularly Mastodon, which, as it stands, has a high proportion of Fediverse users.

Development is ongoing, but as of the current version there remain some breaking bugs that, at least in my case, render the federation largely read-only rather than interactive. From interacting with them on tickets, I understand the developers are aware of these problems and plan to refactor the ActivityPub module entirely in a future version.

Theming Castopod

I had thought about theming Castopod to be heavily integrated with the existing site, but modifying the frontend isn't the simplest task, unfortunately. By default, there's a single frontend theme, with only a colour scheme customisation available in the settings.

Screenshot of the Irish Left Archive Podcast website
The Irish Left Archive Podcast instance of Castopod with some changes to the default theme.

While the frontend templates do sit in a themes/ directory, the styles and javascript use Tailwind and Vite, and sit within the application, so they're not so easily separated out. For the Irish Left Archive Podcast, I've mounted a copy of the themes/cp_app frontend on the docker container with some small customisations, and the existing theme fits the UX you'd expect for a podcast and microblog perfectly well.

If you want to have a look at the changes and additions made for our instance, you can see the git repository below.



  • PHP

Customisations of Castopod for the Irish Left Archive Podcast instance

View repository

Integrating with

Since re-writing the frontend to integrate into the existing Irish Left Archive site at wasn't practical, the podcast pages on the site are constructed from the podcast RSS feed. Since the frontend is templated with XSLT and external XML sources were already integrated, this was luckily a fairly simple task. That way we still have a podcast section on the main site, with episode pages and an embedded player, but without any duplication of effort.

One integration I initially thought couldn't be reproduced was the fact that previously when a podcast guest had an existing page on the site, a list of podcast episodes in which they featured could be added to the bottom of the page. But this was largely because I hadn't experimented with the 'cast/people' feature, which allows adding a list of contributors (or editors, production etc.) to each episode, which is part of the podcast: namespace additions to the RSS feed. Once the guests were added to each episode, I could include their profile on as their URL and then filter for the podcast:person element in the template.

As a result, by setting the canonical URLs on to point to the Castopod instance, it retains all the features the previous custom setup had without duplicating features or complex APIs or integrations, just by pulling the feed. (XSLT frontends won't be making a come back, I suspect, but for the curious, the code is available in the Git repository.)