Install BOA

This is the whole install, start to finish. You will copy in a few commands, then mostly wait and watch. The installer does the hard part — it builds the web server, the database, PHP, the firewall and your Ægir control panel for you.

You do not need to understand any of that yet. Follow the steps in order, don't skip ahead, and don't reboot until the page tells you to.

Roughly how long: about five minutes to type the commands, then 45 to 90 minutes for BOA to finish on its own (build, a background pass, and a reboot). Set aside an unhurried hour.

Before you begin

You should already have your box prepared: a clean server, a root password set (your provider-console lifeline — many VM images ship with the root account locked), root SSH-key access, your hostname chosen, and DNS pointing at it. If any of that is unfamiliar, stop here and work through Before you install first — that page is the checklist, this page assumes it's done.

Two safety rules that matter for the whole install:

• Log in as root directly. Do not prefix these commands with sudo from a normal user. BOA expects a real root login. (Your SSH key is how you'll get back in — BOA is built around key-based root login. The root password you set earlier is untouched by the install; it stays your provider-console lifeline.)
• Never interrupt a running phase. No Ctrl-C, no closing the window, no reboot, until you reach the finish check. Long silent stretches are normal — that's BOA working through a phase, not a freeze.

Step 1 — Open a screen session

screen keeps the install running even if your connection drops. If your laptop sleeps or your Wi-Fi hiccups mid-install without it, the install dies with the connection. With it, you just log back in and re-attach.

screen

Your prompt comes back looking almost the same — that's fine, you're now inside screen. If you do get disconnected later, log back in as root and run screen -r to return to where you were.

Step 2 — Fetch the BOA installer

This one line downloads BOA's installer commands and drops them into place. It does not install anything on your server yet — it just gives you the boa command to run in the next step.

wget -qO- https://files.boa.io/BOA.sh.txt | bash

When it finishes you'll have the boa command available. Check the built-in help if you like — it's the authoritative, always-current list of options:

boa help

Step 3 — Start the install

This is the one command that builds everything. Replace the two placeholders with your own values:

• server.mydomain.org → your server's hostname (the subdomain you set up)
• my@email → your real email address (used for system notices and for your free Let's Encrypt SSL certificate)

boa in-lts public server.mydomain.org my@email o1 php-min silent

That's the recommended happy-path install. Here's what each part means, left to right — you don't need to change any of it except the hostname and email:

The php-min slot can also carry one other install-time choice instead — swap it in where php-min sits (you can pick only one):

• A different PHP set: php-8.5, php-8.4 or php-8.3 installs just that one version (the fastest install), and php-max installs every supported version. These work exactly the same on a public install as on the local one. Type the token exactly — a mistyped value (php8.5, phpmax, or an unsupported version like php-8.2) is not an error: the installer silently treats it as a New Relic licence key and you get the default PHP set. When you swap in one of these, you get that PHP choice instead of the standard three versions.
• percona-8.0 or percona-8.4 installs that database version rather than the default 5.7 — for example boa in-lts public server.mydomain.org my@email o1 percona-8.4. (You still get the standard three PHP versions.)
• A New Relic license key in that slot turns on New Relic monitoring from the first build (put the key where php-min sits).
• nodns skips BOA's start-up DNS and SMTP reachability checks. Only reach for it when you already know DNS or outbound mail isn't ready yet but want to install anyway — normally you want those checks to run.

If none of that applies to you, leave the command exactly as shown.

Advanced (root): want to watch everything the installer does? Run touch /root/.debug-boa-installer.cnf before the boa in-lts command and the whole install runs with verbose output (debug mode) instead of discarding most step output — invaluable if an install fails and you need something to read, or to send when asking for help. Recipes and caveats: verbose install output.

One more optional choice can ride at the very end of the command: [email protected] (an address different from my@email). Your my@email becomes the client-level control panel account; the separate admin-level account normally uses a derived root@<your-hostname> address whose notices stay in the server's local root mailbox — fine for most self-hosted setups, since you log into the panel with a one-time link either way (Step 7). Pass admail= only if you want that admin account on a real mailbox instead. Skipped it and changed your mind later? That's one edit, not a reinstall: set _MY_OCTO_EMAIL in /root/.<username>.octopus.cnf — details.

On Debian? If your server is still on Debian rather than Devuan, don't worry — you don't have to convert it first. When you run the command above, BOA notices, records your command, converts the OS for you (rebooting once or twice on its own), and then re-runs your install command automatically. You'll get an email when the whole thing is done. If you'd rather do the OS conversion as its own explicit step first, see Debian to Devuan.

Press Enter, and the install begins.

Step 4 — Watch it work (and don't panic)

BOA now runs a chain of phases by itself. You'll see plenty of output scroll by, then long quiet stretches where nothing appears to happen for several minutes — that is completely normal. It's installing and configuring the stack — the heavy components arrive as ready-made prebuilt packages rather than compiling on your box — and the detail goes to its logs, not your screen. Leave it alone.

Roughly, in order, BOA will:

1. Install the core system stack and your Ægir Master control panel.
2. Run a second pass to finish the system setup.
3. Install your first hosting instance (the o1 you named).
4. Fetch a free Let's Encrypt SSL certificate so your panel is https://.

You'll watch phases 1–4 in your terminal. Then the visible part finishes — but you are not done yet. There is one more phase.

Do not reboot here. Even though the terminal looks finished, a final background pass still has to run.

Step 5 — Wait for the background pass

About 30 minutes after the terminal part finishes, BOA runs one last pass on its own (from its scheduler, in the background) to install the CSF firewall and the DNS cache. This is the part people reboot too early and break — so don't.

There's a simple, reliable way to know it's truly finished. Run:

boa info | grep -c Percona

• If it prints 3 → everything is finished. You're ready for the reboot.
• If it prints anything less → the background pass hasn't finished yet. Wait a few more minutes and run it again. Don't touch anything else meanwhile.

Keep re-running that one command every few minutes until it says 3.

The 3 here is a done-signal we read from BOA's live status output, not a fixed number in the code — once the full stack is up, three lines of boa info mention Percona. Don't be tempted to change the 3; it's counting real output.

Step 6 — Reboot

Once — and only once — the check above returns 3, reboot the server so it comes up on the correct kernel:

boa reboot

This is BOA's own reboot command (a faster, cleaner shutdown than a plain reboot). Your SSH session will drop as the box restarts; give it a minute or two, then log back in as root.

Step 7 — Log in to your control panel

Your Ægir control panel — the Octopus instance panel, where you'll create and manage your sites — lives at your instance's subdomain: the o1 you named, in front of your hostname. So for server.mydomain.org it's:

https://o1.server.mydomain.org

You get in with a one-time login link, not a password. When the install finished it printed the exact command to generate that link. It looks like this (replace o1 if you named your instance something else):

su -s /bin/bash o1 -c "drush @hm uli"

Run that as root. It prints a long one-time URL — paste it into your browser and you're logged into Ægir as the admin. From there you can set a real password.

If the link ever expires before you use it, just run that same command again to mint a fresh one.

Step 8 — Meet your one config file

The install left you a single file that's yours to edit:

/root/.barracuda.cnf

This is where you turn BOA's knobs — nothing else needs hand-editing to run a healthy server. You don't have to touch it today; the defaults are sensible. When you're ready to adjust things (which PHP versions to keep, database version, and so on), see Essential settings — it walks through the handful of settings a self-hoster actually changes, with safe values.

What success looks like

You're done when all of these are true:

• boa info | grep -c Percona prints 3.
• You've rebooted with boa reboot and logged back in.
• https://o1.server.mydomain.org loads with a valid padlock (SSL).
• The one-time login link logs you into Ægir.

That's a fully working BOA server. From here:

• Keep it current → Keeping BOA current — BOA can auto-update itself, and this shows how to check and run upgrades by hand.
• Adjust the basics → Essential settings.
• Need to look up a helper tool or backend command later? → Command reference.

Going further

The happy path above gives you a secure, firewalled server out of the box — you don't need to configure the firewall yourself to be safe. But if you later want to tune it (open extra ports, adjust rules), that's root-level operator territory:

Advanced (root required): Operating → CSF firewall — full firewall configuration and tuning, for when you've outgrown the defaults.