Deploying your own code

Everything in the Sites & platforms topic assumed the code was already there. This topic is about bringing your own code: a Composer-built Drupal, a Git-tracked codebase, a Backdrop project, or a distribution that BOA doesn't hand you out of the box. You build it in your own account, tell Aegir where it is, and then run sites on top of it — all without touching the server.

If you're a Drupal developer, this is the part of BOA that feels most like home. You get a normal shell (as your oN.ftp user), you run composer and git and drush the way you always have, and the only new idea is how you hand the finished codebase to Aegir. That last step is a single form in the web UI.

The one rule to keep in mind

BOA treats a platform's codebase as frozen once sites are running on it. That's not a limitation to fight — it's what keeps your live sites from breaking underneath you. So the shape of every job here is the same:

  1. Build a fresh codebase somewhere in your account.
  2. Register it as a new platform.
  3. Move a test site onto it and check it works.
  4. Only then move your live sites.

You never composer update a platform that already has live sites on it. When you want newer code, you build a new platform beside the old one and migrate across — the same safe "one thing at a time" move covered under Cloning & migrating.

Where your code lives

Your account gives you two homes for platform code, and they behave very differently:

  • ~/static/platforms/ — this is yours. Drop a Composer project, a Git checkout, or any Drupal/Backdrop codebase here and BOA will never overwrite it during an upgrade. This is where your own platforms belong.
  • ~/distro/ — these are the platforms BOA builds and maintains for you. Treat them as read-only; BOA rewrites them on its own schedule, so anything you put there can be wiped on the next upgrade.

Aegir looks in both when it offers you a list of platforms to install a site on, but only ~/static/platforms/ is a safe place to keep code you care about.

In this topic

  • Building your own platform — the full path from an empty directory to a running site: build a codebase with Composer (or drop in a Git checkout) under ~/static/platforms/, register it in the web UI with Platform Path (or let Aegir build it for you with Deploy from makefile), then add sites on it. Includes the docroot gotcha for modern web/-style Composer layouts.
  • Developing your site — the day-to-day developer loop once a site is live: turning on Twig / theme debugging, quieting the caches (Drupal's own plus BOA's Redis/Valkey) so your changes show up, and the golden rule of settings files — what you may edit and what BOA regenerates every time it verifies your site.

What's yours to edit, and what isn't

Inside your account, the codebase is yours. You can edit modules, themes, and templates under a platform in ~/static/platforms/ freely, and commit them to Git however you like. The one file to leave alone is a site's settings.php: BOA owns it and rewrites it every time Aegir verifies the site. Put your own overrides in the site's local.settings.php instead — BOA leaves that file for you and loads it automatically. The Developing your site page covers this in detail.

When it needs the server

Almost all of this happens in your shell and the web UI. A couple of things don't, because they belong to the machine you don't manage:

  • Creating a platform in a directory your account isn't allowed to write to, or on a path that's locked to the server.
  • Installing system-level packages, or changing server-wide PHP or Nginx settings that a build of yours depends on.

If you run into one of these, don't hunt for a workaround from your shell — it's something your host or operator does. Open a support request and say what you were trying to build.

Where to go next

  • The safe way to move a site onto a platform you've just built is under Cloning & migrating.
  • The drush commands you'll lean on while developing are collected in Using Drush.
  • Per-site and per-platform settings you're allowed to tune live in Tuning your site.
  • Exact task names, form fields, and control-file names are gathered in the shared Reference.