[JAY]

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:Copy

.env

file) lives inside its folder:

• aaPanel Docker install:
  Code:Copy

  /www/dk_project/dk_app/billionmail/billionmail_XXXX
  (the last part is random)
  
• Script install: usually
  Code:Copy

  /opt/BillionMail

Not sure?

Code:Copy

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:Copy

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:Copy

bash bm.sh update

(or

Code:Copy

bm update

if the

Code:Copy

bm

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

Code:Copy

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

1. All containers are up:
   Code:Copy

   docker ps --format "table {{.Names}}\t{{.Status}}" | grep -i billionmail
2. You can log in to the dashboard, and the version at the top right changed.
   
3. Domain > DNS Records is still all green.
   
4. Settings > Common Settings still shows your certificate as valid.
   
5. Send a test email from a task, and one from webmail. Both arrive.
   
6. 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:Copy

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:Copy

docker-compose.yml

, which names the exact container versions, so

Code:Copy

docker compose up -d

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

Code:Copy

.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:Copy

  bash bm.sh clear
  (or
  Code:Copy

  docker image prune
  ).
  

Sources: BillionMail on GitHub · Docker Compose documentation


More BillionMail troubleshooting

• Port 25 blocked: emails not sending
  
• SSL certificate won't apply
  
• DKIM fails although the record exists
  
• Emails stuck in the send queue
  
• Can't open the dashboard
  
• Webmail (Roundcube) problems
  
• Emails going to spam
  

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