Choosing and managing platforms

A platform is a codebase — one copy of Drupal (or Backdrop) that your sites run on. When you create a site, you pick the platform it lands on. This page is about that choice: how to see which platforms are available to you, how to pick one, and — if your host lets you — how to shape the list yourself or add your own.

If the words platform, site and client aren't yet second nature, start with Sites, platforms and clients and come back here.

Which platforms can I use?

When you open the Create site form in your control panel, the Platform field is a drop-down. Everything in that drop-down is a platform your host has made available to you — a ready-built Drupal (or Backdrop) codebase, already verified and waiting for sites. You don't build these or install them; you just choose one.

A few things worth knowing about that list:

  • Each entry is a specific Drupal version and flavour — a plain Drupal 10, a Drupal 11, a distribution like Commerce or Social, an older Drupal 7, and so on. Newer BOA releases add newer platforms as upstream Drupal ships them.
  • Only verified platforms appear as a choice. If your host just added one and it's still building or being checked, it won't show up until it's ready.
  • Your host decides which platforms exist on your server. That master list is a server-side setting they control — it isn't something you edit. What you can influence, on some hosted plans, is which of those platforms actually get installed into your Octopus instance. That's the platforms.info file, below.

If the platform you need — say a specific Drupal version, or a distribution you're missing — isn't in the drop-down at all, that's your host's call. Ask them to add it: it's something your host or operator does, so open a support request and say which Drupal version or distribution you need.

Picking a platform when you create a site

On the Create site form, the Platform field is where the choice happens. Pick the platform whose Drupal version and distribution match the site you're building. That decision matters, so a couple of pointers:

  • Match the platform to the site. A Drupal 10 site needs a Drupal 10 platform; a Commerce site needs a Commerce platform. The install profiles offered in the Install profile field depend on the platform you picked — change the platform and the available profiles change with it.
  • You're not stuck with it. The platform you choose at create time isn't permanent. Later on you can move the site to a different platform (for example, a newer Drupal) with the Migrate Site task. That's covered in Cloning & migrating within this topic — and the golden rule there is worth reading before you move anything: change one thing at a time.

Everything after you submit the form — the field-by-field walkthrough of Domain name, Install profile, Platform, Language and Database server — lives on the Creating and managing a site page in this topic, under Create a new site.

Shaping your own platform list: platforms.info

On a hosted BOA account you get a small, tenant-editable control file that lets you choose which platforms are installed into your Octopus instance. It lives in your own shell, at:

~/static/control/platforms.info

That's inside your Octopus account — the same account you log into over SSH/SFTP as your oN.ftp user. You edit it with your own shell tools; no root, nothing on the server itself. There's also a ~/static/control/README.txt in that same folder that summarises the control files available to you.

What goes in it

The file is a plain list of short platform keywords — the same symbols BOA uses internally for each build — separated by spaces. For example:

DE2 DX5 SOC UC7

…asks for Drupal 11.2, Drupal 10.5, Social and Ubercart 7, and only those. Or a single keyword installs everything supported:

ALL

You don't have to memorise the keywords — the exact symbol for each Drupal version and distribution is listed for you in that account README.txt, and the full set is collected in the shared Reference.

BOA reads the file leniently: it keeps only spaces, digits and capital letters, and ignores everything else, so a stray newline or lowercase note won't break it. If you save the file empty (or with nothing usable in it), BOA quietly falls back to whatever default your host set — it won't wipe your platforms.

It replaces the list, it doesn't add to it

This is the one gotcha. Your platforms.info replaces the default set your host would otherwise install — it doesn't extend it. If you write:

DE2 DX5

…you get exactly those two platforms and nothing else, even platforms your host's default would have installed, and even new platforms added in future BOA releases. If you want "the default set plus one more", the safe move is to list everything you actually want, or use ALL. When in doubt, ALL keeps you current automatically.

You don't have to worry that trimming your list will make BOA start reaping platforms behind your back. BOA does have a nightly tidy-up that can move aside a ghost platform — one whose code directory is empty or broken, with no real Drupal docroot in it — but that tidy-up is off by default: a platform is only ever moved (reversibly, into an undo folder, never deleted) if your host has deliberately switched the cleanup on, and even then only after the platform has looked empty for several nights running. A healthy platform with real code in it is never touched, whether or not it currently has sites, and whether or not you have a platforms.info file.

Making the list take effect (no root needed)

Editing platforms.info doesn't install anything on its own — it's read the next time your instance is upgraded. On a hosted account you can trigger that upgrade yourself, without root, by dropping a second, empty control file next to it:

~/static/control/run-upgrade.pid

Create that empty file (for example touch ~/static/control/run-upgrade.pid in your shell) and, within a few minutes, BOA launches an on-demand Octopus upgrade that (re)installs exactly the platforms your platforms.info lists. When it's done, BOA deletes the run-upgrade.pid for you automatically, so you don't have to clean up.

Two things to remember:

  • The trigger only works together with platforms.info. If there's no platforms.info file, the run-upgrade.pid is ignored — nothing happens.
  • Give it a little time. This isn't instant; the upgrade runs in the background and can take a while, especially the first time it installs a new platform.

If you'd rather not run it yourself, or the upgrade doesn't pick up your changes, that's a fine moment to open a support request and let your host run the upgrade for you.

Adding your own platform

Beyond the platforms your host offers, some hosted plans let you register a platform of your own — your own Drupal codebase, built however you like. Whether you're allowed to depends on your account's permissions; if the option isn't there for you, it's one your host controls.

When you can, the Add platform form gives you two ways in:

  • Platform Path — you point Aegir at a codebase directory you've already put in place (typically via SFTP or your shell), and give the platform a Platform Name. Aegir verifies the code that's already there and turns it into a platform you can install sites onto.
  • Deploy from makefile — instead of uploading the code yourself, you give Aegir a Platform Makefile (a Drush make file, by path or URL) and it builds the codebase for you into the target path. There's a Drush make option for building working copies if your makefile needs it.

Both routes end the same way: a new platform appears in your Platform drop-down on the create-site form, ready for new sites — exactly like the ones your host provided.

Getting your own code onto the server, the git workflow behind a custom codebase, and how the makefile build fits together are covered in their own topic, Deploying your own code, elsewhere in this guide. This page is just the platform side of that story: once the code is in place, this is how it becomes a platform you can build sites on.

Tuning a platform you own

Platforms carry a small settings file you're allowed to tune from your shell: boa_platform_control.ini, in the platform's sites/all/modules folder. It's the platform-level cousin of the per-site boa_site_control.ini, and it lets you adjust a handful of behaviours for every site on that platform at once. Because it applies to a whole codebase you control, it only makes sense for platforms you've added yourself. The full list of what you can tune, and how, lives in the Tuning your site & platform topic in this guide.

When it's not yours to fix

Most of the platform story is yours: choosing one at create time, shaping your platforms.info, and — where your plan allows — adding your own. A few things sit on the server side and belong to your host:

  • Which platforms exist on the server at all. The master available-platforms list is a host setting. If a Drupal version or distribution you need isn't offered, ask your host to add it.
  • Enabling an older PHP version. Some older Drupal cores or distributions need a specific PHP version installed on the server. If a platform you want won't build because its PHP version isn't there, that's a server package your host installs — mention which platform you're after when you ask.
  • Unlocking a platform your host has deliberately locked.

None of these have a tenant-side workaround, and you shouldn't hunt 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

  • New to the vocabulary? Sites, platforms and clients lays out platform, site and client in plain terms.
  • The glossary has short, plain definitions of every term you'll meet in the control panel.
  • Logging in to edit platforms.info from your own shell is covered in the shell and SFTP guide.
  • Every task name, control-file name and platform keyword is collected in the shared Reference.