Upgrading from Drupal 7

Backdrop CMS is the natural landing place for a Drupal 7 site: the same content model, the same editorial habits, modern PHP underneath — and BOA turns the move into a single control-panel task built around one promise: your existing Drupal 7 site is never touched.

How the upgrade works

The Upgrade to Backdrop task doesn't convert your site in place. It:

1. takes a fresh backup of your live site (it stays online — no maintenance window);
2. restores that backup as a copy at a new domain on a Backdrop platform, with its own database and its own files;
3. converts the copy to Backdrop using Backdrop's own upgrade machinery;
4. brings the copy online next to your original.

Your Drupal 7 site keeps serving your visitors the whole time, before, during and after. If anything about the result isn't right, the copy is simply discarded and the upgrade re-run — there is nothing to roll back on your live site, ever.

The task is administrative: if your panel login doesn't show it on the site's page, ask your host to run it for you — the inputs are just the new domain name and which Backdrop platform to use.

Pick a test-copy name for that new domain — dev. as the first label, for example dev.example.com. On protected labels, self-identifying crawlers and bots are served a 404, so search engines never see the copy while you review it — and unlike deeper test labels, a first-label dev. name can still get a real HTTPS certificate if you enable Encryption on the copy. The full list of protected labels is on Cloning and moving a site. The real domain arrives later, at cutover.

The module compatibility report

Backdrop folded many of Drupal 7's most-used modules into core — Views, Date, Entity reference, Link, Redirect, CKEditor and more — and replaced others (the Admin menu becomes core's admin bar). Your contributed modules fall into three groups, and the task prints a per-module report in its log before anything is created:

• Now part of Backdrop core — nothing to do; core takes over.
• Available as a Backdrop port — works if the port is present on the Backdrop platform; otherwise the module is disabled on the copy.
• No Backdrop version — disabled on the copy. Its database tables are kept, so no data is lost; the feature is simply off until you find a replacement.

The report is advice, not a gate — and because it appears before the copy is even created, reading it costs nothing. A port gap it names isn't a dead end either: filling one on the copy afterwards is a short, supported routine — delete the carried Drupal 7 copy, download the port, enable it and run the updates, and the kept tables convert from where Drupal 7 left off. The worked example is on Adding modules to your Backdrop site.

One thing you may notice over SFTP afterwards: a directory named sites/<yourdomain>/modules-preupgrade-quarantine inside the copy. That's where the task moves aside (never deletes) your site-local copies of modules Backdrop absorbed into core, so they can't shadow the core versions. Everything in it is kept — leave it alone unless you know a specific file you still need.

Your theme on the copy

The conversion carries your theme along with everything else: a site-local theme travels into the copy's own sites/<yourdomain>/themes, and your site's theme choice carries into Backdrop's configuration — the copy is not silently re-dressed in a stock Backdrop theme. What the conversion can't do is vouch for the theme itself: a Drupal 7 theme doesn't declare Backdrop compatibility, so the copy records it as disabled even while serving it as the default. How much of it works as-is depends on the theme — simple, stylesheet-driven themes can render just fine, while a theme that leaned on Drupal 7's page template and regions meets Backdrop's layout system, which took over exactly that job. The module report above doesn't cover themes, so the walk-through below is where you judge it: if the copy looks right, keep going; if it doesn't, the theme needs its Backdrop port — Backdrop stays close to the Drupal 7 theme layer, so that's an adaptation (declare backdrop = 1.x, adopt a layout where the page template did the arranging), not a rewrite from scratch. Ask your host when the walk-through shows you need one.

Your site's install profile maps across the same way: standard stays standard, minimal stays minimal. If your Drupal 7 site used a custom install profile that the Backdrop platform doesn't carry, the copy is simply recorded as standard and the task logs a warning — the conversion never re-runs an install profile, so this only changes the label in the panel, never your content.

What to check on the copy

The conversion carries your content — posts, comments, users, tags, files, URL paths, custom fields, menus, and your saved views (Views is part of Backdrop core, so listings built in Views keep working rather than needing a rebuild) — and moves your site's settings into Backdrop's configuration. Before pointing your domain at it, walk through:

• a handful of real pages, including ones with images and custom fields;
• your forms (contact and any webforms), views listings, and menus;
• the admin screens for anything the module report flagged.

One timing fact to keep in mind while you review: the copy is a point-in-time conversion — it was built from the backup taken when the task started, so content edits made on the Drupal 7 site afterwards are not in it. There is no delta-sync step, and none is needed, because re-running is cheap: when the copy has proven itself, run one last fresh upgrade at a quiet moment — content edits paused briefly — and cut that newest copy over.

The copy starts with cron and HTTPS certificates switched off on purpose, so it never sends mail or runs background jobs while you're still comparing it against the original. When you're satisfied, cron is enabled on the copy's page, a certificate is issued for the new name, and you cut over when ready. If the old site lives on the same instance, the Cutover task on the copy's page does it in one step: it backs up and retires the old site, then renames the copy to your real domain (re-issue the certificate for it afterwards — renaming switches HTTPS off). Any extra domain aliases the old site carried are not brought across, so re-add them on the renamed site. The domain is unserved only during the rename itself — a window that grows with the site's size. And if a cutover is interrupted after the old site has already been backed up and removed, just run Cutover again: with nothing left holding the domain, it completes as a straight rename of the copy — re-running is the recovery path, and it never double-deletes or loses your copy. If the old site lives elsewhere, the cutover is just DNS: point your domain when ready, and keep the old site around as long as you like.

Three ground rules

• Update Drupal 7 core first. The upgrade requires a current Drupal 7 core and refuses to start otherwise (before creating anything). If your site is behind, run your normal core update, then upgrade. Precisely, "current" here means a system schema of 7078 or newer — the point past which Backdrop's own upgrade stops silently skipping Drupal 7's system updates; any Drupal 7 core from 7.28 on clears it.
• Convert 3-byte utf8 databases first. A site imported from an older server may still store text as MySQL's original 3-byte utf8; upgrading such a site can surface illegal mix of collations errors on the copy. The conversion task fixes that in one step — and reports an honest "nothing to convert" when your database is already fine.
• Drupal 6 needs two steps. Backdrop upgrades from Drupal 7 only — that's Backdrop's own rule. The first step is a built-in task of its own, with the same never-touch-the-original shape as this one: see Upgrading from Drupal 6.