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 Ægir 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 Ægir. 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/ — this is yours. Drop a Composer project, a Git checkout, or any Drupal/Backdrop codebase anywhere under it and BOA will never overwrite it during an upgrade. We recommend keeping your codebases in a ~/static/platforms/ subdirectory — not because other spots are less safe, but to keep ~/static/ tidy: it's also home to the standard control/, usage, trash, files and goaccess entries, and a pile of platform folders at the top level buries them.
• ~/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.

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

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/ 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 Ægir 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.
• The configuration settings and command names used across BOA are collected in the shared Reference.