Running your own BOA box — Cheat Sheet

For operators: this sheet is for people with root on their own BOA server.

BOA installs the whole hardened hosting stack on one VPS or VM, and then mostly looks after itself. This page is the quick primer: installing in one line, your first panel login, the one config file you touch, keeping the box current, moving the database up for Drupal 11, and what to do when the box breaks. Everything here links to the full story.

Your box in 30 seconds

1. Three parts, one box — Barracuda installs and upgrades the stack, Octopus runs your hosting instances (o1 is yours), Ægir is the web panel. → Start here
2. A clean VM, not a customised box — a fresh VPS or VM with at least 4 GB RAM and 2 CPUs, Devuan Daedalus (or a supported Debian that BOA converts for you), and your SSH key on root. → Before you install
3. LTS or PRO is one word — in-lts or in-pro at install; LTS is free and kept 1:1 with PRO, and an LTS box can move up later without a reinstall. → Start here
4. Pick the database now — Percona 5.7 is the default; Drupal 11 needs 8.4, which is one word at install. → Install BOA
5. It looks after itself — SKYNET keeps it patched and watchdogs restart whatever falls over; your part is the occasional full upgrade. → Keeping BOA current

Install in one line

Log in as root directly (not through sudo), open screen so a dropped connection can't kill the install, fetch the installer, then run the one build command with your own hostname and email:

screen
wget -qO- https://files.boa.io/BOA.sh.txt | bash
boa in-lts public server.mydomain.org my@email o1 php-min silent

php-min installs PHP 8.5, 8.4 and 8.3; type the extra word exactly, since a mistyped one is silently taken as something else. Expect 45 to 90 minutes, long quiet stretches and a reboot along the way. It's done when boa info | grep -c Percona prints 3 — only then run boa reboot.

→ Install BOA

Running Drupal 11? One word: percona-8.4

Drupal 11 needs MySQL 8, which on BOA means Percona 8.4. Ask for it at install in the slot php-min had (you can pick only one; you still get the standard three PHP versions):

boa in-lts public server.mydomain.org my@email o1 percona-8.4 silent

On a 5.7 box nothing breaks, but nothing Drupal 11 installs, and upgrading later is a two-step in-place database upgrade — one extra word now is far cheaper.

→ Install BOA

Log in to your panel

Your instance's panel lives at your instance name in front of your hostname, https://o1.server.mydomain.org. You get in with a one-time login link, not a password — run this as root and paste the link it prints (re-run it if the link expires):

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

→ Install BOA

Your one config file: /root/.barracuda.cnf

One host-wide file, one _NAME=value line per setting; open it with nano, change only the value, save — most settings apply on the next BOA run. Check that _MY_EMAIL is an inbox you read, since alerts and upgrade notices go there, and leave _SKYNET_MODE and _SYSTEM_AUTO_SECURITY out: absent means on. Before each install or upgrade pass BOA keeps a dated copy of it in /var/backups/dragon/config/ — your undo button.

→ Essential settings

Keeping current: SKYNET, plus a full upgrade now and then

SKYNET refreshes BOA's tools every few minutes, restarts or repairs core services, and emails you when a release lands. The full upgrade by hand is root, in screen, tools refreshed first, then the pair — let the first finish before the second:

wget -qO- https://files.boa.io/BOA.sh.txt | bash
barracuda up-lts
octopus up-lts all force

(up-pro on PRO.) It usually takes the better part of an hour. Read the whole ... upgrade completed line just above the closing Bye: it says plainly whether it finished cleanly, with errors, or needs boa reboot for a new kernel; boa info confirms where you are.

→ Keeping BOA current

Upgrading a 5.7 box to 8.4 in place: two steps, never a jump

The upgrade runs on this box; nothing is migrated. Snapshot the whole box first. On a box with sites, the oldest codebase gates the upgrade, so run the readiness check and act on its verdict (READY, REVIEW or BLOCKED); then go 5.7 → 8.0 → 8.4, letting each finish:

codebasecheck --box --deep
barracuda up-lts system percona-8.0
barracuda up-lts system percona-8.4

The two-step path exists on Devuan Daedalus; Excalibur already runs 8.4.

→ Database major upgrades · Percona 8 upgrade readiness

When the box breaks: gentle first

1. Wait about five minutes — BOA checks its services several times a minute and restarts nginx, PHP or the database on its own.

2. Is it the box, or is it you? Load a site from a phone on mobile data; if it works there, your address is blocked — get in from another network or the provider's console, then clear and allow it:

   BASHCopy

   csf -dr YOUR.IP.HERE
   csf -a YOUR.IP.HERE
   

3. Disk full? df -h, then delete the oldest backup archives and old logs.

4. Last resort, least drastic first: boa reboot (never a plain reboot), then restoring a provider snapshot.

→ When the box breaks

The settings most people touch

264 host-wide settings are indexed in the Variable reference, with their families explained in the barracuda.cnf reference.

If something's weird

• boa info | grep -c Percona sits at 2 for an hour after install → the background pass never ran; run barracuda up-lts system noscreen (up-pro on PRO), then re-check for 3. Troubleshooting FAQ.
• A Drupal 11 site won't install, or its platforms never appear → the box runs Percona 5.7, the default; take the two-step upgrade above. Keeping BOA current.
• barracuda up-lts prints "BOA Skynet Agent is Inactive!" and quits → someone added _SKYNET_MODE=OFF; remove that line, wait ten minutes, retry. SELFUPGRADE / SKYNET reference.

Going deeper

• The whole guide: Self-Hosting BOA — install, keep current, recover, OS upgrades, security on your box, Drupal 12 readiness.
• Moving servers and adopting Ægir: Moving servers cheat sheet.
• Every upgrade mode and argument: Manual upgrade reference · SELFUPGRADE / SKYNET reference.
• Trying it locally first: Local development install · every host tool: Command reference.