Building your own platform

Most of the time you build a site on a platform your host already gave you — you just pick it from a drop-down. But some hosted plans let you go one step further: bring your own Drupal codebase, build it right inside your account, and register it as a platform of your own. Then you create sites on it exactly like any other.

This page walks you through the whole thing, start to finish, from your own shell. You never need root and you never touch the server itself. Everything here happens as you: in your oN.ftp shell and in your Aegir control panel.

Whether you're allowed to add your own platform depends on your account's permissions. If the Add platform option isn't there for you, it's one your host controls — ask them if you'd like it enabled. If you're not sure what a platform even is yet, read Choosing and managing platforms first; this page is the hands-on "build one yourself" companion to it.

The big picture

A platform is just a folder containing one Drupal codebase. Turning your own codebase into a platform is three steps:

  1. Build the codebase in your account with Composer (or drop in code you already have).
  2. Register it as a platform in your Aegir control panel, pointing at where you put it.
  3. Create sites on it from the same control panel.

The important idea to hold onto: Composer is a build-time tool here. You run it before Aegir knows the codebase exists. Once a platform has live sites on it, you treat that folder as finished — you don't keep running Composer inside it. When you want newer code, you build a fresh platform next to it and move sites across. More on that below.

Where your platforms live

Your account has a dedicated folder for codebases you bring yourself:

~/static/platforms/

In full, that's /data/disk/o1/static/platforms/ (with your own instance name in place of o1). Anything you put here is yours: BOA upgrades never overwrite ~/static/platforms/. That's the whole point of it — it's your space, safe from the automatic codebase updates that manage your host's own platforms.

So a codebase you're about to register goes in a folder of its own under there, for example:

~/static/platforms/mysite/

Step 1 — Build the codebase with Composer

Connect to your account over SSH as your oN.ftp shell user (see Connecting: shell and SFTP if you haven't set that up), then move into your platforms folder:

cd ~/static/platforms/

Now build a fresh Drupal project. For a current Drupal, composer create-project does the whole thing in one command:

composer create-project drupal/recommended-project:^10 mysite

That creates a mysite/ folder with Drupal 10 and all its dependencies already installed. Swap :^10 for :^11 for Drupal 11, or pin an exact release like :10.4.10 if you need a specific version.

Then move into it and add whatever your site needs:

cd mysite
composer require drupal/module_name
composer require drush/drush

drush/drush is worth adding — it's what lets you run database updates on the finished sites later.

When you're happy with the mix, make sure everything is installed cleanly:

composer install --no-interaction --optimize-autoloader

That's it — you now have a complete Drupal codebase sitting in ~/static/platforms/mysite/, ready to become a platform.

Bringing code you already have? You don't have to build from scratch. If your codebase already exists in git, just clone it into the same place and let Composer fetch its dependencies:

cd ~/static/platforms/
git clone https://github.com/you/mysite.git mysite
cd mysite
composer install --no-interaction --optimize-autoloader

Or upload a finished codebase over SFTP into ~/static/platforms/mysite/. Whichever way the code arrives, the registration in Step 2 is the same.

A note on the docroot (Drupal 8 and newer)

Modern Composer-built Drupal puts the actual website — the index.php, core/, modules/, themes/ and sites/ — inside a sub-folder, not at the top of the project. So a composer create-project layout looks like this:

~/static/platforms/mysite/
  ├── composer.json
  ├── composer.lock
  ├── vendor/
  └── web/              ← the Drupal docroot lives here
      ├── index.php
      ├── core/
      ├── modules/
      ├── sites/
      └── themes/

Good news: you don't have to worry about this. When Aegir verifies the platform it looks for the real docroot automatically. If your project has no index.php at the top, Aegir checks for a docroot/, html/ or web/ sub-folder (in that order) and uses whichever it finds — web/ is the usual one for a composer create-project layout, but the other two are handled just the same. Older Drupal 7-style codebases keep their index.php right at the top of the project and need no sub-folder at all. Either way you can point the platform at the project folder itself and let Aegir sort out the docroot.

Step 2 — Register it as a platform

Now switch to your Aegir control panel (the web UI) and turn that folder into a platform:

  1. Go to Platforms and click the Add platform tab.

  2. Fill in the form:

    • Platform Path — the full path to the codebase you just built. Point it at the project folder:

      /data/disk/o1/static/platforms/mysite

      (Use your own instance name in place of o1.) This works for both layouts: Aegir finds the docroot for you, so you don't need to add /web for a modern Composer/Drupal 10+ codebase. If you prefer to be explicit you can point straight at the web/ sub-folder (…/static/platforms/mysite/web) — but it's optional, not required.

    • Platform Name — a friendly label so you can recognise it in the drop-down later, e.g. mysite.
    • Deploy from makefile — leave this alone. That section is only for when you want Aegir to build the codebase for you from a Drush make file. You've already built yours by hand, so skip it entirely.
  3. Save. Aegir queues a Verify task.

The Verify task is Aegir checking over the codebase: it works out which Drupal version you brought, reads the modules and themes it can see, and makes sure it can write where it needs to. A minute or two later the platform is verified and ready.

Aegir finds the docroot for you. You don't have to worry about the web/ sub-folder — pointing Platform Path at the project folder is enough, and Verify auto-detects the real docroot (docroot/, html/ or web/). If Verify reports it can't find Drupal, or the platform shows as an unknown version, the usual cause is a broken or incomplete build — re-run composer install in the codebase and check that an index.php really exists (at the top for Drupal 7, or under web/ for a modern Composer layout) before verifying again.

Step 3 — Create sites on your platform

Once the platform shows as verified, it behaves exactly like any platform your host provided. To build a site on it:

  1. Go to Sites and start a new site (the Add site form).
  2. In the Platform drop-down, choose the platform you just registered.
  3. Fill in the rest of the form and save.

Aegir queues an Install task, creates the database, writes the site's settings, and runs the Drupal install — all automatically. When it finishes, you get a one-time link to log in as the new site's admin. The full walkthrough of the site form lives in Managing your sites.

You can put many sites on one platform — that's what platforms are for. They all share the one core/, modules/ and themes/ you built; only each site's own sites/<domain>/ folder is separate. That's what makes a shared platform cheap to run.

Keeping the code up to date the safe way

Here's the rule that saves people the most grief:

Once a platform has live sites on it, don't run Composer inside it again. Aegir treats a platform with sites as fixed. Running composer update in a folder that's serving real sites can overwrite core/ and vendor/ underneath those sites and break them in ways that are hard to unpick.

When you want newer code — a Drupal core update, a module security release — do this instead:

  1. Build a fresh platform next to the old one, with the newer code:

    cd ~/static/platforms/
composer create-project drupal/recommended-project:^10 mysite-new
cd mysite-new
composer require drupal/module_name drush/drush
composer install --no-interaction --optimize-autoloader

  2. Register mysite-new as a new platform (Step 2 again).

  3. Move a test site across first. Aegir's migrate task moves a site from the old platform to the new one — try it on a throwaway or staging site and check it works.

  4. Once you're confident, migrate the rest, then retire the old platform.

Moving sites between platforms is its own topic — see Cloning and migrating sites for the click-by-click. This build-new-then-migrate rhythm is the whole reason platforms are worth the small extra effort: your live sites never change underneath themselves, and you can always roll back by migrating a site back to the old platform if something's off.

If you do need to run a database update or clear caches on a single Composer-managed site after code changes, that's done with vdrush from your shell — covered in Drush basics.

Gotchas worth knowing

Composer uses your instance's PHP version. When you run composer in your oN.ftp shell, it runs against whichever PHP version your instance is set to. A newer Drupal or distribution may need a newer PHP than your default, and if the two don't match you'll get puzzling Composer errors that look like broken packages. If you hit that, set your instance's PHP version first — that's a small control file in your own account, explained in Choosing your PHP version — then run Composer again.

Run Composer as oN.ftp, not the plain oN login. Your account has a special limited shell (oN.ftp) that wires up the right PHP and tools for you. Connecting as the plain oN user instead can make composer and vdrush pick the wrong PHP and produce errors that look like bugs but aren't. Always use your oN.ftp shell for this work — Connecting: shell and SFTP shows how.

Composer is build-time only. Worth repeating because it's the one that bites: Composer belongs before a platform has sites. After that, build fresh and migrate. Treat a platform folder with live sites as read-only.

A custom Drush command file inside your platform won't be picked up. If you drop a *.drush.inc command file into your codebase under ~/static/platforms/, Aegir deliberately doesn't load it during its background tasks — it's a safety measure. Your sites still serve normally; only that one kind of custom Drush command, run during Aegir's own tasks, is affected. Most people never hit this; it's here so it doesn't surprise you if you do.

When something needs your host

A few things around your own platforms sit on the server side, where you have no access — and that's fine, they're your host's job:

  • A PHP version that isn't installed on the server at all. Setting your instance's PHP version (above) only picks from what's installed. If your codebase needs a PHP version your server doesn't have, installing it is something your host or operator does — open a support request and say which version you need.
  • Unlocking a platform your host deliberately locked, or anything that needs a change on the server itself.

None of these have a tenant-side workaround, and you shouldn't go looking for one. Open a support request, say what you were trying to do, and let your host handle the server side.

Where to go next