Local development — Cheat Sheet

Your hosted site can come home to your own machine in one pull: the ddev-boa add-on brings its database and files into a DDEV project, through the shell login and SSH key you already have. This page is the quick primer: install, point it at your site, pull, keep a reset point — and the heavier option of running BOA itself on a spare VM. Everything here links to the full story.

Local development in 30 seconds

ddev-boa is a public DDEV add-on — it brings your hosted site's database and public files into the DDEV project you already have for its code. → Local development with DDEV
It uses your own login — your oN.ftp account and SSH key, with nothing to switch on server-side. → Before you start
One way only — from the server to your machine: it never changes the hosted site, never pulls code, and has no push. → Pull the database and files
It reproduces your site, not the server — database, files, PHP and Drupal version, docroot; there's no control panel locally. → What this does and does not do
Want the whole stack? boa in-lts local installs full BOA on a spare VM (for operators). → Local development install

Install the add-on and point it at your site

In the DDEV project for your site's codebase:

BASH

ddev add-on get omega8cc/ddev-boa

Then set three values in .ddev/providers/boa.yaml — your own shell login, your server, and the site's Drush alias without the @, in its dotted form:

YAML

environment_variables:
  BOA_SSH_USER: o1.ftp
  BOA_HOST: server.example.com
  BOA_ALIAS: mysite.example.com

ddev boa-aliases prints the exact alias names from the server. Use your own oN.ftp login: developer sub-accounts have no Drush to run the pull (Extra accounts).

→ Install the add-on · Point it at your site

Match your project to the site

ddev boa-config reads the site's PHP version, Drupal version and docroot from what the server reports, and writes them to .ddev/config.boa.yaml — review it, then restart. The site's database engine arrives as a commented, opt-in line; if you want it, uncomment it before your first ddev start, because DDEV can't switch engines once the database exists.

BASH

ddev boa-config
ddev restart

→ Match your project to the site

Pull the database and files

BASH

ddev auth ssh      # make your SSH key available inside DDEV, once per session
ddev pull boa      # download the database and public files

The database is dumped on the server, where Drush supplies the credentials, so no database password is copied to your machine; files that BOA keeps behind symlinks arrive as real files. Only the public files directory comes over — copy private files yourself when you need them. Locally, use the site's own Drush through DDEV: ddev drush cr, ddev drush updb.

→ Pull the database and files · the by-hand export

Keep a reset point

A pulled database holds your live users' real data, so keep every snapshot in .ddev/db_snapshots — which DDEV keeps out of Git — and never force-add one. With DDEV v1.25.4 or newer, take a seed snapshot right after the first pull; from then on one command returns to it without another pull:

BASH

ddev snapshot --name=seed             # right after your first ddev pull boa
ddev restart --reset-database -Oy     # back to the seed, any time

→ Keep a reset point

Want the whole stack? BOA on a spare VM

boa in-lts local installs the full BOA stack — Nginx, PHP-FPM, Percona, the Ægir control panel and one Octopus tenant — on a VM or container guest, at the private hostname aegir.local, with no public IP, no DNS and no licence. Keep the guest on a private or NAT network: a local box is not built to face the internet.

BASH

wget -qO- https://files.boa.io/BOA.sh.txt | bash
boa in-lts local my@email

The install is ready when boa info | grep -c Percona reports three lines; then open https://aegir.local/user (expect a self-signed certificate warning).

→ Local development install (for operators)

The settings most people touch

Setting (`.ddev/providers/boa.yaml`)	What it is	Default
`BOA_SSH_USER`	Your own shell login, not a sub-account	(empty), e.g. `o1.ftp`
`BOA_HOST`	Your server's hostname	(empty), e.g. `server.example.com`
`BOA_ALIAS`	The site's Drush alias without the `@`, dotted form	(empty), e.g. `mysite.example.com`
`BOA_FILES_PATH`	The site's files directory, only if the pull asks for it	(empty — found automatically)

Three you must set, one optional — all on Local development with DDEV.

If something's weird

ddev boa-aliases shows nothing → aliases reach your shell account every few minutes, and only for registered, live sites; on a brand-new site wait a few minutes, then check it's verified and enabled. If something doesn't work.
The pull stops with a "files path" error → by design: it refuses to fall back to the docroot, which would copy code and settings.php; set BOA_FILES_PATH and pull again. If something doesn't work.
The seed snapshot won't restore after you switched the database engine → a snapshot restores only into the engine it was taken on; decide the engine before your first ddev start, then pull and take the seed. Keep a reset point.

Going deeper

The whole workflow: Local development with DDEV — requirements, matching the project, pulling, the reset point, local Drush, troubleshooting.
By hand, or everything home: Shell & Drush cheat sheet · Exporting your site.
Debugging on the hosted site instead of a copy: the .dev. preview URL.
A whole BOA server on your own VM (for operators): Local development install.