Skip to content
BOA Documentation

Powered by Grav

Importing an existing site

Importing an existing site

Sooner or later you'll want to bring in a site that already exists somewhere else — on a plain LAMP box, another hosting panel, or your own laptop. The good news: you can do the whole thing yourself, with your control panel and your own oN.ftp login. This page is the standard recipe.

A site, wherever it comes from, is three pieces: a codebase (Drupal core plus modules and themes), the site's own files (everything under its sites/example.com/ folder), and its database. The recipe below moves each piece in turn, and finishes with the one trick that fixes hardcoded file paths in your content.

First: is this the right page?

This recipe is for a site coming from outside the Ægir world — a standalone Drupal on ordinary hosting, a local development copy, an export from some other panel. That's exactly what it's for, and nothing here needs more than your own login.

If the site is coming from another Ægir or BOA server, there are purpose-built tools that move sites — or your whole account — far more comfortably, with the databases, files and settings carried across in one job. Those run with server access, so on a hosted account this is a support request rather than a recipe:

For everything genuinely external, read on.

The recipe at a glance

  1. Upload the site's codebase into your ~/static space.
  2. Register it as a platform in your control panel.
  3. Create a new, blank site on that platform — under the right name (this matters; see the paths section).
  4. Copy the old site's files into the new site's folder.
  5. Prepare the database dump by hand, then import it.
  6. Run Verify Site and check your site over.

If the site already runs on a current, stock Drupal core, you may not need steps 1–2 at all: create the blank site on one of the built-in platforms and start at step 3 — you'll just also upload whatever extra modules and themes the site kept at the sites/all level.

Step 1 — Upload the codebase

Upload (or rsync) the full Drupal root of your site into your own platform space, for example ~/static/platforms/mysite/. The mechanics — connecting, where the folder lives, what a healthy codebase looks like, the modern web/ docroot layout — are all covered in Building your own platform; this page only adds what's different when the code arrives from elsewhere.

After the upload, make what you brought group-writable so later tasks can work with it:

SH
chmod -R 775 ~/static/platforms/mysite

Ignore the chmod grumbles. You may see warnings like Operation not permitted from that command, and later a few yellow chmod to 2775 failed warnings in task logs on the imported site. Both are expected — some folders belong to the system user rather than your login — and both are harmless. The system re-checks ownership and permissions across your sites every night and settles anything you couldn't touch.

Importing a multisite? Empty the sites/ folder first. If your old codebase carries several sites in its sites/ tree, move them aside before the next step, and register the platform with no site folders in it. When Ægir meets a platform, it discovers every site folder it finds and tries to import each one on the spot — a full Drupal start-up that needs the site's database to already exist. Yours don't exist yet, so every discovered site would simply fail. Register the platform empty, then bring the sites in one at a time with steps 3–6.

Step 2 — Register the platform

In your control panel, add a platform pointing at the folder you just uploaded — the full path, /data/disk/o1/static/platforms/mysite (with your own account name in place of o1). The form, the Verify task that follows, and the docroot auto-detection are described step by step in Building your own platform.

Step 3 — Create a blank site

Create a new site on the freshly verified platform, exactly as you'd create any site — the walkthrough is in Creating and managing a site. Any install profile will do: this site is a placeholder, and its freshly installed database is about to be replaced by yours.

Don't pick the domain casually. For a legacy Drupal 6/7 site, the name you give here decides whether your content's hardcoded file paths get fixed automatically later — read the paths section below before you fill in the form. The short version: if your database dump references sites/yourfinaldomain.com, use the final domain now; if it references any other name (or sites/default), create the site under that name — or a working name — and plan one rename at the end. For a modern Drupal 8+ site, use the final domain right away — any literal paths get fixed in the dump instead, as the same section explains.

Step 4 — Copy the files across

The blank site has its own empty folder on the platform, named after its domain. Copy the old site's files into it. If the old files came along inside the codebase you uploaded in step 1, it's one command from your shell, run from the platform's docroot:

SH
cp -af sites/old-name.com/files/* sites/new-name.com/files/

If the files live in a separate archive or on the old server, land them in sites/new-name.com/files/ by SFTP or rsync instead — same destination, any road you like. Anything else the old site kept in its own folder (site-specific modules or themes) goes into the matching place under sites/new-name.com/ too.

Step 5 — Prepare and import the database

This is the step with rules, because Ægir is particular about what a site database looks like.

Ægir does not support table prefixes — every site gets exactly one database of its own, with bare table names, and the site's settings are generated on that assumption. Shared tables between sites are out for the same reason. If your dump uses a prefix, fix it in the dump before importing: replace every prefix_tablename with tablename in your editor of choice.

Two more things to check by hand:

  • The dump must contain the DROP TABLE IF EXISTS lines (a standard mysqldump includes them). The blank site's database is already full of freshly installed Drupal tables, and your dump has to replace them.
  • The dump must not try to create or select a database — no CREATE DATABASE, no USE. The site's database already exists; the dump is loaded straight into it.

With the dump shaped right, run it through the bundled sqlmagic tool. It reads and writes in your current directory, so put the dump in your ~/static space and run the tool from there, with a bare filename:

SH
cd ~/static
sqlmagic fix dump.sql

That writes a cleaned copy next to it, named fixed-dump.sql. Today the fix does two things: it strips MySQL DEFINER clauses (dumps taken on another server tag views and routines with that server's database user, which makes the import fail on yours), and it rewrites INSERT INTO to INSERT IGNORE INTO so a stray duplicate row doesn't abort the whole import. Note what it doesn't do: it won't remove table prefixes or sort out the DROP/CREATE lines — that preparation above is yours.

Then import the fixed dump into the site:

SH
drush @new-name.com sqlc < ~/static/fixed-dump.sql

(That's the Drush 8 spelling for legacy Drupal 6/7 sites. On a modern Drupal 8+ site, use drush11 and the hyphenated alias form — see Drush aliases.)

For a small dump you can also import through the web database browser instead — see Browsing your database (Adminer) — but a big import will crawl or time out in the browser, so the shell route above is the dependable one.

Step 6 — Verify and check

Back in the control panel, run Verify Site on the imported site. Verify re-reads the site — its modules, its settings, its actual state — and regenerates the configuration to match, which is exactly what a site whose database was just swapped out needs.

Then log in and click around: content there, images showing, admin pages loading. A cache clear (drush @new-name.com cc all on legacy Drupal, or the Clear caches button) is a sensible first move if anything looks stale.

Once you're happy, point the domain's DNS at your instance, and turn on HTTPS for the site — that's covered in HTTPS for your sites.

Getting hardcoded file paths right

Here's the part that used to be folklore, so it gets its own section.

A Drupal site's database can contain literal file paths — in body text, in custom blocks — pointing at the site's files folder as it was named on the old server: sites/old-name.com/files/..., or sites/default/files/... if the site was a standalone Drupal. On its new platform the site's folder is named after its new domain, so those old paths would point at nothing and images would quietly break.

What happens next depends on the site's Drupal generation — so open your dump, see which sites/... paths your content actually uses, and pick the matching plan below.

Legacy Drupal 6 and 7 — one rename fixes them

On a legacy site you don't fix those paths by hand. Whenever a site is renamed — a Migrate Site task with a new domain — the system rewrites the paths inside the database as part of the move, in custom block bodies and in all your content's text fields, and it rewrites both patterns at once:

  • sites/OLD-NAME/... becomes sites/NEW-NAME/..., and
  • sites/default/... becomes sites/NEW-NAME/... as well.

So the plan writes itself:

  • Dump references sites/yourfinaldomain.com (the site ran under the same name before): create the site with the final domain in step 3. The paths already match; no rename needed.
  • Dump references any other name — the old host's domain, or a local development name like mysite.local: create the blank site under that name, import everything, then run one Migrate to the final domain. The single rename rewrites the old-name paths and any sites/default paths in the same pass. (Creating under the old name first also keeps any module happy that expects that name in an include path.)
  • Dump references only sites/default: create the site under any working name and rename once to the final domain at the end.

You may find older recipes telling you to rename the site twice — away to a temporary subdomain and back again. That dance predates the sites/default rewrite and is no longer needed: one rename, planned as above, does the whole job.

One honest caveat: the rewrite covers your content and custom blocks, which is where these paths overwhelmingly live — but it can't chase every corner a module may have squirrelled a path into (a theme setting, an odd serialized blob). After the rename, spot-check a few pages with embedded images; if a straggler turns up, it's a one-line fix in that module's settings form.

Modern Drupal 8 and newer — fix the dump before importing

On a modern site, a rename does not rewrite paths inside your content — and it usually doesn't need to. Drupal 8+ records file references by scheme (public://...), which resolves to whatever the site's files folder is called now, so the folder name normally isn't embedded in your content at all. (The rename does keep the site's private-files and temporary paths pointed at the new folder name for you.)

What survives as a literal string is exactly that: a full sites/old-name.com/files/... URL somebody once pasted into body text. If your dump contains those, fix them before the import in step 5 — a search-and-replace on the dump file, turning sites/old-name.com into sites/new-name.com, in your editor or with sed in your shell. Then create the site directly under its final domain; there's nothing left for a rename to do.

Where to go next

© 2026 BOA Documentation. All rights reserved.