Guide How to Update BillionMail Safely (and Roll Back if Something Breaks)

Guide How to Update BillionMail Safely (and Roll Back if Something Breaks) - Printable Version

+- AdminsForum (https://adminsforum.com)
+-- Forum: Free & open-source control panels (https://adminsforum.com/Forum-free-open-source-control-panels)
+--- Forum: aaPanel (https://adminsforum.com/Forum-aapanel)
+---- Forum: aaPanel Guides & Tutorials (https://adminsforum.com/Forum-aapanel-guides-tutorials)
+----- Forum: aaPanel BillionMail Guides (https://adminsforum.com/Forum-aapanel-billionmail-guides)
+----- Thread: Guide How to Update BillionMail Safely (and Roll Back if Something Breaks) (/Thread-guide-how-to-update-billionmail-safely-and-roll-back-if-something-breaks)

How to Update BillionMail Safely (and Roll Back if Something Breaks) - JAY - 10-23-2026

How to update BillionMail safely (and roll back if something breaks)

BillionMail gets regular updates with fixes and new features. Updating usually takes a few minutes, but your mail server holds things you can't easily recreate: mailboxes, contacts, templates, DKIM keys and SSL certificates. So the rule is simple: back up first, update second, check third.

Step 1: Check your version and read the release notes
Your version is shown at the top right of the BillionMail dashboard (for example v4.9.0). Compare it with the latest release on BillionMail's GitHub releases page and read what changed. Look for words like "breaking", "migration" or "manual step".

Step 2: Back up
Option A (easiest): a VPS snapshot. Most providers offer snapshots in their control panel. One click saves the whole server; restoring it puts everything back exactly as it was.

Option B: back up the BillionMail folder. Everything BillionMail stores (database, mailboxes, configuration, keys, certificates and the

Code:

.env

file) lives inside its folder:

aaPanel Docker install:
Code:
/www/dk_project/dk_app/billionmail/billionmail_XXXX
(the last part is random)
Script install: usually
Code:
/opt/BillionMail

Not sure?

Code:

ls -d /www/dk_project/dk_app/billionmail/billionmail_* /opt/BillionMail 2>/dev/null

shows it.

Stop BillionMail so the database is written cleanly, copy the folder, start it again:

Code:

cd /www/dk_project/dk_app/billionmail/billionmail_XXXX   # your folder
docker compose stop
tar -czf /root/billionmail-backup-$(date +%F).tar.gz .
docker compose start
ls -lh /root/billionmail-backup-*.tar.gz

Mail is paused for the minute or two this takes; other servers retry, so nothing is lost. Copy the backup file off the server (aaPanel's Files page can download it).

Step 3: Update
aaPanel Docker install: open Docker in aaPanel and look at the installed BillionMail app. If an update is offered there, use it.

Script install (git based): run the built-in updater from the BillionMail folder:

Code:

bash bm.sh update

(or

Code:

bm update

if the

Code:

bm

command exists). The updater only works in a folder that was installed with git. If it says

Code:

The .git does not exist

, your copy wasn't installed that way; update through aaPanel instead, or ask in this section.

Step 4: Check that everything works

All containers are up:
Code:
docker ps --format "table {{.Names}}\t{{.Status}}" | grep -i billionmail
You can log in to the dashboard, and the version at the top right changed.
Domain > DNS Records is still all green.
Settings > Common Settings still shows your certificate as valid.
Send a test email from a task, and one from webmail. Both arrive.
Check Settings > Send Queue after a few minutes. It should be empty or nearly empty.

Step 5: Roll back if something broke
From a snapshot: restore it in your provider's panel. Done.

From the folder backup:

Code:

cd /www/dk_project/dk_app/billionmail/billionmail_XXXX
docker compose down
cd .. && mv billionmail_XXXX billionmail_XXXX.broken
mkdir billionmail_XXXX && cd billionmail_XXXX
tar -xzf /root/billionmail-backup-YYYY-MM-DD.tar.gz
docker compose up -d

The backup contains the old

Code:

docker-compose.yml

, which names the exact container versions, so

Code:

docker compose up -d

starts the old version with your old data. Once everything works again, delete the

Code:

.broken

folder.

Mail received after the backup (between backup and rollback) stays in the broken copy. If that matters, ask in this section before deleting it.

Good habits

Update when you're not in the middle of a big campaign.
Keep at least one recent backup off the server.
Clean old Docker images now and then to save disk space:
Code:
bash bm.sh clear
(or
Code:
docker image prune
).

Sources: BillionMail on GitHub · Docker Compose documentation

More BillionMail troubleshooting

Applies to BillionMail 4.9 installed through aaPanel or the install script, October 2026.