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.

This walk-through is the editors' pass: hand the copy to the people who will live in it and let them try real tasks, not just look. Two rules go with it — anything they change on the copy is not carried by the final fresh upgrade (the copy is a test drive, not a head start), and the short list of paths that genuinely changed (routes of modules switched off on the copy) goes into the Redirect module, which Backdrop ships in core.

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.

The rehearsal loop, and cutover day as a list

Rehearse in a loop: run the upgrade, walk the copy, fix what the walk showed (a port gap, a module switched on or off), delete the copy, run again — each copy is as clean as the first, and the original is never in the write path. When a copy has proven itself, cutover day is this list:

1. Clear any pending database updates on the Drupal 7 site, and confirm its core is current (the ground rules below).
2. Pause editing on the Drupal 7 site from the moment the final run starts until the cutover completes — an edit made after that point is not in the new site, though the retired copy still holds it.
3. Delete the proven copy, then run one last fresh upgrade — that new copy is the one that goes live.
4. Enable cron on the copy's page.
5. Run Cutover on the copy: it backs up and retires the old site, then renames the copy to your domain (if it is interrupted after the old site is gone, run it again — it completes as a plain rename).
6. Re-issue the certificate for the renamed site.
7. Re-add any extra domain aliases the old site carried.
8. Walk the live site once more, and put the short redirect list in place.

How long it takes

The conversion is one task, and the per-module report is printed before anything is created, so the calendar is your review time. Three things keep a real duration, all of them yours: the theme port, if the walk-through shows the theme needs one (this page deliberately promises nothing about how much of a theme survives); porting or replacing contrib modules that have no Backdrop version; and the cutover's own unserved window during the rename, which grows with the site's size. There is no scope sign-off to schedule, no rehearsal environment to build, no freeze measured in days, no delta sync, and — when both ends are on the same instance — no DNS change.

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 and its database updates, 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.

Where to go next

• Leaving Drupal 7: choosing your exit — the two exits side by side, what stops existing here, and who is needed when.
• Cloning and moving a site — the rename machinery this page relies on.
• Front cache and page cache — the copy runs on the same production stack that will serve the result, so what is already on is what your visitors get.