Before you install

This is your pre-flight checklist. Work down it one item at a time — none of these takes long, and each one prevents a specific, common way a first install goes sideways. When every box below is ticked, you're ready to install and the rest is mostly waiting for BOA to do its thing.

Nothing here is optional-but-nice. These are the things BOA genuinely expects, and it's far easier to get them right now, on a fresh box, than to unpick them after an install has started.

1. Start with a clean, fresh box

BOA wants a freshly provisioned server that you have not touched yet. Order the plain, vanilla image your provider offers, boot it, and stop there. Don't run apt upgrade, don't install extra packages, don't enable extra repositories, and don't apply your own hardening scripts first.

Why so strict? Many cloud images ship vendor customisations — custom kernels, auto-update daemons, login banners, cloud-init tweaks — and BOA's installer makes strong assumptions about the state of the machine. Let it start from a known-clean baseline and it will set everything up the way it needs. Start layering your own changes on top and you're the one who gets to debug the collision.

If the box has already been used for something else, the safe move is to reinstall the OS image fresh rather than trying to clean up. It costs you ten minutes and saves you a great deal of guessing.

2. Use a supported operating system

BOA runs on 64-bit Devuan — Devuan is Debian without systemd, and that difference is the whole point (see box below). You have two ways to land on it:

Already on Devuan? These releases are supported:

  • Daedalus — the default and the one to pick for a new install.
  • Excalibur — supported, but only together with Percona 8.4.
  • Chimaera — supported; upgrading to Daedalus is recommended.
  • Beowulf — supported for existing boxes being upgraded.

Starting from Debian? That's fine — Debian is supported as a starting point that BOA migrates to Devuan for you. During install, BOA's autoinit step removes systemd and moves you onto Devuan automatically. Supported Debian bases are Trixie, Bookworm, Bullseye, and Buster — those are the only Debian versions autoinit will convert. Anything older (Stretch, Jessie) is not a valid fresh-install base: autoinit refuses it. If that's all you have, upgrade the box to one of the supported versions first.

Why not systemd / Ubuntu? BOA does not run on systemd-based systems. This isn't a stylistic choice — every systemd distro the BOA maintainers tested produced crashes their pre-systemd Devuan equivalents didn't. You don't have to do anything special about this: when you kick off the install on a supported Debian, BOA notices the system isn't ready, runs the autoinit conversion for you, reboots, and then continues your original install on its own. Ubuntu is no longer supported for the same reason. If your provider only offers Ubuntu, pick a different image or a different provider.

Don't overthink the codename. If your provider offers a recent Debian or Devuan image, you're in good shape.

3. Avoid environments BOA can't run on

A couple of hosting environments are known to fight BOA. Steer clear of these:

  • Amazon EC2. EC2 leans hard on systemd, which has caused recurring crashes on BOA instances — and it blocks the very Devuan migration BOA needs to perform. Even if you tolerated the crashes, you couldn't upgrade off them. Pick a standard VPS or dedicated host instead.
  • VMware vCloud Air. Ordinary VMware virtualisation (ESXi) is fine. The vCloud Air service specifically breaks things that need a site to reach its own public IP — CSS/JS aggregation, the AdvAgg module, and similar — so avoid it.

Beyond those, almost any normal virtual server works: LXC and KVM guests, Hyper-V, OpenVZ, Parallels, Red Hat KVM, VirtualBox, VMware ESXi (but not vCloud Air), VServer, and the Xen variants are all recognised. If in doubt, a plain KVM VPS from a mainstream provider is the boring, reliable choice.

One catch worth knowing up front: BOA is built for a guest VM, not for a dedicated machine running the OS directly on the hardware. If it can't detect a virtualisation layer, the installer treats that as "bare metal", warns that this is unsupported, and stops. (There's an expert override — an opt-in control file at /root/.allow.any.virt.cnf — but it's exactly that: unsupported and unsupported-with-emphasis. For a first server, install BOA inside a VM.)

4. Add your SSH key to root before you begin

This one bites people, so do it now. Add an SSH key for the root account before you run anything. Newer OpenSSH versions that BOA relies on require key-based root login, and the install hardens SSH early — if you haven't put a key in place, you can lock yourself out of your own new server.

Any modern key type works — BOA accepts RSA, ECDSA, or ed25519 — but ed25519 is the recommended one. If you don't already have an ed25519 key on your own machine, create one:

ssh-keygen -t ed25519

Then make sure its public half is in /root/.ssh/authorized_keys on the server (most providers let you paste a key in during provisioning, which is the easiest route). Confirm you can log in as root with the key before you start the install — that quick check is the difference between a smooth day and a support ticket.

You'll also want to be logged in directly as root (or sudo -i into a real root shell first). Don't run the installer through sudo command...; BOA needs a genuine root environment and root's home directory.

5. Prepare the hostname and DNS

BOA identifies your server by a fully-qualified hostname, and it needs that name to resolve on the public internet before you install.

  • Use a subdomain, not a bare domain. server.example.com is correct. example.com on its own is not — BOA expects a server-level subdomain.
  • Point a wildcard A record at your server's IP. BOA creates site addresses under your hostname, so the DNS needs to send server.example.com and anything beneath it to your box. Your DNS provider's "wildcard A record" (often written *) is what you want, pointing at the server's IPv4 address.
  • Check that it has propagated. From another machine, run: 
    host server.example.com

    You want it to return your server's IP. DNS changes can take a little while to spread; wait until this is correct before installing.

  • Set the hostname on the server too. BOA will set it for you, but set it yourself first so a cloud provider can't quietly reset it on the next reboot: 
    hostname -b server.example.com
echo server.example.com > /etc/hostname

6. Open the ports BOA needs

BOA has to reach out to the internet during install — to fetch its own sources and packages, resolve DNS, and send you a completion email. Make sure these outgoing TCP ports are open on any provider-side firewall: 25, 53, 80, and 443. Also confirm wget is installed, since BOA fetches its installer over it.

You generally don't need to pre-open incoming ports by hand: BOA installs and configures the CSF firewall for you as part of a public install, and it opens the right inbound ports (SSH, HTTP, HTTPS and the handful of services it runs). You just need the outbound path clear so the installer can do its work.

7. Check RAM and disk

BOA and Drupal are comfortable, but not featherweight. The published minimums:

  • 4 GB RAM and 2 CPUs for a normal install.
  • 8 GB RAM and 4+ CPUs if you plan to run Solr search.

Meet the minimum or, better, give yourself a little headroom — a box that's already tight on memory before any sites exist will struggle once they do. For disk, anything modern (say 40 GB and up) is a sensible starting point for a small install; more if you expect several sites or large media. Disk is easy to add later; RAM you want to get roughly right from the start.

8. Know that BOA turns IPv6 off — and that's fine

During install, BOA disables IPv6 on the server. If you were expecting IPv6, this can look alarming — it isn't. Here's the story so you don't second-guess it.

Most BOA-hosted sites publish IPv4-only DNS. If IPv6 is switched on at the server but the network path for it isn't perfectly configured, visitors' browsers try the IPv6 route first, wait for it to time out, and only then fall back to IPv4. That timeout is the single most common cause of "my site feels slow" reports on an otherwise healthy box — and it's maddening to diagnose because it only affects visitors on IPv6-capable networks, so the reports look random.

BOA's stance is simple: until every layer (DNS, routing, firewall) is correctly set up for IPv6, you're faster and more predictable on IPv4 only. So it disables IPv6 by default and you get consistent, snappy behaviour with zero tuning. For a first server, this is exactly what you want — leave it off.

Advanced (root required): BOA disables IPv6 through kernel sysctl hardening, and turning it back on is a genuine networking exercise (routed prefix, matching AAAA records, mirrored firewall rules) that isn't a supported default — see Operating → Security model for the sysctl hardening this is part of. Don't attempt it on your first install.

9. Decide on optional extras (the default is fine)

At install time BOA can add optional packages on top of the core stack, chosen by a setting called _XTRAS_LIST in its config file. As a beginner, the short answer is: you don't have to choose anything — the default is fine. A public install already gives you what a first server needs: the Aegir UI to run your sites, and the CSF firewall, which BOA installs by default in public mode.

The _XTRAS_LIST setting starts empty, and leaving it empty is the right call for a first install. A couple of the common extras, so the names aren't a mystery if you ever see them mentioned:

  • Adminer — a browser-based database manager. Not installed by default on a public server; you'd add it deliberately by listing it in _XTRAS_LIST later.
  • Image optimisation tools — small utilities Drupal can use to shrink images.

You can add extras later by editing the setting and re-running an upgrade to pick them up, so there's no pressure to get this "complete" on day one. Start minimal; grow into it.

Advanced (root required): the full catalogue of _XTRAS_LIST keywords (Solr, FTPS, Node/NPM and more, with their safety gates) belongs to operators — see Operating → _XTRAS_LIST and install modes.

10. Have a snapshot plan from day one

Before you install anything, make sure you can take a snapshot or backup image of the whole server from your provider's control panel. Most VPS providers offer this with one click.

Why now, before there's anything to protect? Because the cheapest possible way to recover from a mistake — during install or later — is to roll the whole box back to a known-good point. A snapshot taken right after a clean install is a superb safety net: if a later change goes wrong, you restore in minutes instead of rebuilding from scratch. Get comfortable with where that button is before you need it in a hurry.

BOA also has its own backup system for your sites once they exist, but that's a later chapter — the server-level snapshot is the day-one habit to build.

You're ready

If you can tick all ten, you're set:

  • Fresh, untouched box
  • Supported Devuan (or a Debian base BOA will migrate)
  • Not EC2 / vCloud Air
  • Root SSH key added and tested
  • Subdomain hostname with a wildcard A record that resolves
  • Outgoing TCP 25/53/80/443 open, wget present
  • Enough RAM and disk
  • Comfortable with IPv6 being off
  • Happy with default extras
  • A snapshot plan

Next up: Installing BOA walks you through the actual install, command by command.

Going further