WordPress to ClassicPress

2025-02-18

As I mentioned in my recent Blog Questions Challenge, I recently switched my blog from WordPress, which it had been running on for over 20 years of its 26 year history, to ClassicPress.[1] I'm aware that I'm not the only person for whom ClassicPress might be a better fit than WordPress[2], so I figured I should share the process by which I undertook the change.

Switching from WordPress to ClassicPress

Switching from WordPress to ClassicPress should be a non-destructive, 100% reversible process, but (even though I've got solid backups) I wasn't ready to trust that, so I decided to operate on a copy of my site. I'm glad I did, because there were a couple of teething issues I needed to tackle before I could launch.

1. Duplicating the site

I took a simple approach to duplicating the site: (1) I copied the site directory, and (2) I copied the database, and (3) I set up a new subdomain to use for testing. Here's how I did each step:

1.1. Copying the site directory

This should've been simple, but a du -sh revealed that my /wp-content/uploads directory is massive (I should look into that) and I didn't want to clone it. And I didn't want r need to clone my /wp-content/cache directory either. So I ran:

rsync -av --exclude=wp-content ./old-site-directory/ ./new-site-directory/ to copy everything except wp-content, and then
rsync -av --exclude=uploads --exclude=cache ./old-site-directory/wp-content/ ./new-site-directory/wp-content/ to copy wp-content except the uploads and cache subdirectories, and then finally
ln -s ./old-site-directory/wp-content/uploads ./new-site-directory/wp-content/uploads to symlink the uploads directory, sharing it between the two sites

1.2. Copying the database

I just piped mysqldump into mysql to clone from one database to the other:

mysqldump -uUSERNAME -p --lock-tables=false old-site-database | mysql -uUSERNAME -p new-site-database

I edited DB_NAME in wp-config.php in the new site's directory to point it at the new database.

1.3. Setting up a new subdomain

My DNS is already configured with a wildcard to point (almost) all \*.danq.me subdomains to this server already. I decided to use the name classicpress-testing.danq.me as my temporary/test domain name. To keep any "changes" to my cloned site to a minimum, I overrode the domain name in my wp-config.php rather than in my database, by adding the following lines:

define('WP_HOME','https://classicpress-testing.danq.me');
define('WP_SITEURL','https://classicpress-testing.danq.me');

Because I use Caddy/FrankenPHP as my webserver[3], configuration was really easy: I just copied the relevant part of my Caddyfile (actually an include), changed the domain name and the root, and it just worked, even provisioning me out a LetsEncrypt SSL certificate. Magical[4].

2. Switching the duplicate to ClassicPress

Now that I had a duplicate copy of my blog running at https://classicpress-testing.danq.me/, it was time to switch it to ClassicPress. I started by switching my wp-admin colour scheme to a different one in my cloned site, so it'd be immediately visually-obvious to me if I'd accidentally switched and was editing the "wrong" site[5].

ClassicPress provides a migration plugin which checks for common problems and then switches your site from WordPress to ClassicPress, so I installed it and ran it. It said that everything was okay except for my (custom) theme and a my self-built plugins, which it understandably couldn't check compatibility of. It recommended that I install Twenty Seventeen - the last WordPress default theme to not require the block editor - but I didn't do so: I was confident that my theme would work anyway... and if it didn't, I'd want to fix it rather than switch theme!

And then... it all broke.

3. Fixing what broke

After swiftly doing a safety-check that my live site was still intact, I started trying to work out why my site wasn't broken. Debugging a ClassicPress PHP issue is functionally identical to debugging a similar WordPress issue, for obvious reasons: check the logs, work out what's broken, realise it's a plugin, disable that plugin while you investigate further, etc.

In my case, the "blocking" issues were:

Jetpack: this plugin does not play nicely with ClassicPress, presumably because it fails if it's unable to register a block. Fortunately, I wasn't actually using Jetpack for anything other than for VaultPress (which has saved my butt on at least one occasion and whose praises I sing), so I uninstalled Jetpack and installed the standalone plugin version of VaultPress instead, which worked fine.
EWWW Image Optimizer: I use this plugin to pregenerate WebP variants of my images, which I then serve using webserver rules. It's not a complex job, and I should probably integrate the feature into my theme at some point, but for now I use this plugin. Version 8.0.0 of the plugin doesn't work on ClassicPress 2.3.1, so I used WP-CLI to downgrade to the last version that does (7.7.0), and then it worked fine.
Dan's Geocaching Log Reposter: a self-made plugin that copies my logs from geocaching websites stopped working properly, which I think is because ClassicPress is doing a more-aggressive job than WordPress at nonce validation on admin REST endpoints? I put a quick hack into my plugin to work around it, but I'll need to look into this properly at some point.
Some other bits of my stack, e.g. CapsulePress (my Gemini/Spartan/Nex server - through which you're reading this post right now!), have their own copies of my database credentials, because I've been too lazy to centralise them into environment variables, and needed updating (but not until live switchover time).

Everything else worked fine, as far as I've determined in the weeks that have followed. My other plugins, which include Advanced Editor Tools (I should probably look into Enriched Editor), Antispam Bee, Google Authenticator, IndieAuth, Post Kinds, Post Snippets, Regenerate Thumbnails, Syndication Links, Webmention, WebSub, and WP-SCSS all "just worked".

4. Completing the switchover

I ran the two sites in-parallel for a couple of weeks, with the ClassicPress one as a "read only" version (so I didn't pollute my uploads directory!), but it was pretty unnecessary because it all worked pretty seamlessly, despite my complex stack of custom code. When I wanted to switch for-real, all I needed to do was swap the domain names over in my Caddyfile and edit the wp-config.php of my ClassicPress installation: step 1.3, but in reverse!

If you hadn't been told, you probably wouldn't have even known I'd made a change: I suppress basically all infrastructure-identifying headers from my server output as a matter of course, and ClassicPress and WordPress are functionally-interchangeable from a front-end perspective[6].

So what's difference?

From my experience, here are the differences I've discovered since switching from WordPress to ClassicPress:

The good stuff

? ClassicPress has no Gutenberg/block editor. This would absolutely be a showstopper for many people, and that's fine: I have nothing against the block editor (I use it basically every day elsewhere!), but I've never really used it on danq.me and don't feel the need to change that! My theme, my workflow, and my custom plugins are all geared around the perfectly-good "classic" editor, and so getting a more-lightweight CMS by removing a feature I wasn't using anyway falls somewhere between neutral and a blessing.
⚡The backend is fast again! One of the changes the ClassicPress team have been working on applying to WordPress is to strip out jQuery and other redundancies from the backend, and I love how much faster and lighter my editor interface is as a result. (With caveat; see below!)
?Virtually everything "just works". With the few exceptions described above, everything works exactly as it does under WordPress. Which is what you'd hope for a fork that's mostly "WordPress, but without the block editor", right, but it's still reassuring (and, for me, an essential feature). There are a few "new" features to do with paging through posts and the media library and they're fine, I suppose, but not by themselves worth switching for (though it might be nice to backport them into WordPress!).

The bad stuff

?️ Adding tags to posts takes a step backwards. A side-effect of dropping jQuery is the partial loss of the autocomplete feature when selecting tags to add to a post. You still get a partial autocomplete, but not after typing a comma: you need to press enter to submit the tag you were writing and then start typing them next, which frankly sucks. This is because they're relying on a datalist, which isn't as full-featured as the Javascript solution WordPress employs. This bugs me almost enough to be a showstopper, but I gather it's getting fixed in a near-future version.
?️ You're in uncharted territory when things go wrong. One great benefit of WordPress is the side-effects of its ubiquity. If you have a query or a problem you can throw a stone at your favourite search engine and get a million answers... and some of them will even be right! If you have a problem in ClassicPress and it's not shared with (or you're not sure if it's shared with) WordPress... you're mostly on your own. The forums are good and friendly, but if you want a quick answer to something, you're likely to have to roll your sleeves up and open some source code. I don't mind this at all - when I first started using WordPress, this was the case, too! - but it might be a showstopper for some folks.

In summary: I'm enjoying using ClassicPress, even where there are rough edges. For me, 99% of my experience with it is identical to how I used WordPress anyway, it's relatively lightweight and fast, and it's easy enough to switch back if I change my mind.

Footnotes

[1] It saddens me that I have to keep clarifying this, but I feel like I do: my switch from WordPress to ClassicPress is absolutely nothing to do with any drama in the WordPress space that's going on right now: in fact, I'd been planning to try it out since before any of the drama appeared. I appreciate that some people making a similar switch, including folks who use this blog post as a guide, might have different motivations to me, and that's fine too. Personally, I think that ditching an installation of open-source WordPress based on your interpretation of what's going on in the ecosystem is... short-sighted? But hey: the joy of open source is you can - and should! - do what you want. Anyway: the short of it is - the desire to change from WordPress to ClassicPress was, for me, 100% a technical decision and 0% a political one. And I'll thank you for leaving any of your drama at the door if you slide into my comments, ta!

[2] Matt recently described ClassicPress as "the last decent fork attempt for WordPress", and I absolutely agree. There's been a spate of forks and reimplementations recently. I've looked into many of them and been... very much underwhelmed. Want my hot take? Sure, here you go: AspirePress is all lofty ideas and no deliverables. FreeWP seems to be the same, but somehow without the lofty ideas. ForkPress is a ghost. Speaking of ghosts, Ghost isn't a WordPress fork; they have got some cool ideas though. b2evolution is even less a WordPress fork but it's pretty cool in its own right. I'm not sure what clamPress is trying to achieve but I've not given it a serious look. So yeah: ClassicPress is, in my mind, the only WordPress fork even worth consideration at this point, and as I describe in this blog post: it's not for everybody.

[3] I switched from Nginx over the winter and it's been just magical: I really love Caddy's minimal approach to production configuration. The only thing I've been able to fault it on is that it's not capable of setting up client-side SSL certificate authentication on a path, only on an entire domain, which meant I needed to reimplement the authentication mechanism I use on a small part of my (non-blog) internal infrastructure.

[4] To be fair, it wouldn't have been hard if I'd still be using Nginx, because I'd set up Certbot to use DNS-based vertification to issue me wildcard SSL certificates. But doing this in Caddy still felt magical.

[5] I also made sure I was logged-out of my primary, live site, so I was confident I wouldn't break anything while I was experimenting!

[6] Indeed, I wouldn't have considered a switch to ClassicPress in the first place if it wasn't a closely-aligned-enough fork that I retained the ability to flip-flop between the two to my heart's content! I've loved WordPress for over two decades; that's not going to change any time soon... and if e.g. ClassicPress ceased tracking WordPress releases and the fork diverged too far for my comfort, I'd probably switch back to regular old WordPress!