Repository navigation
Backup
This page is copied from
docs/backup.mdwhenever it changes. To correct it, open a pull request on that file.
Everything CloudBank keeps lives in its data directory, /data in the
container:
-
cloudbank.db: the SQLite database. It holds every wallet, person and setting. -
attachments/: the files attached to transactions.
One thing lives outside it: CB_SECRET_KEY, if you set it. It encrypts bank
credentials, AI keys and two-factor secrets in the database. A database restored
without the same key loses those secrets, and they have to be set up again.
Keep a copy of the key somewhere safe, apart from the backups.
| Full database | Wallet backup | Copy of /data
|
|
|---|---|---|---|
| Where | Settings → Import & export → Backup & integrity → Download full database (administrators) | Settings → Import & export → Backup & integrity → Download backup | Outside CloudBank, see below |
| Holds | Every wallet, person and setting | One wallet | Everything |
| Attachments | No | Yes | Yes |
| Needs the app stopped | No | No | Yes |
| Restores | The whole server, as it was | A new wallet next to the others | The whole server, as it was |
-
What it is: a consistent snapshot of the whole database, taken while
CloudBank runs. The file is named after the moment it was taken, such as
cloudbank-20260928-101500.db. -
What it leaves out: attachments. If you attach receipts to transactions,
copy
attachments/as well, or use a copy of/datainstead.
-
What it is: one wallet in a single JSON file. It includes:
- currencies, accounts and their valuations;
- payees, categories and tags;
- transactions with their splits, transfers and attachments;
- templates, schedules, rules, budgets and goals;
- vehicles, and which transactions belong to each. Backups taken with 3.5.1 or earlier lack them.
-
What it leaves out:
- bank connections, which you connect again;
- the people, their preferences, two-factor and API tokens.
- Restoring: see One wallet, from a wallet backup. Files up to 256 MiB are accepted. Behind nginx, raise its upload limit first (the reverse-proxy guide).
Export .xhb, next to it, writes the wallet as a HomeBank file. It is your way back to HomeBank, not a backup: HomeBank has no place for what only CloudBank keeps, such as goals and attachments.
The most complete backup, and the only one you can automate outside the app.
Stop CloudBank while you copy: a SQLite database copied while it is being
written can come out inconsistent. With the
Quick start's docker-compose.yml, run this from
the directory you want the backup in:
docker compose stop cloudbank
docker run --rm --volumes-from cloudbank -v "$PWD:/backup" alpine tar czf "/backup/cloudbank-$(date +%F).tar.gz" -C /data .
docker compose start cloudbankCloudBank is down for as long as the copy takes, usually a few seconds.
-
Regularly: a copy of
/data, from a nightly scheduled job, or at least the full database each week. - Several of them. Keep a few generations, somewhere other than the machine CloudBank runs on.
-
The key. Keep
CB_SECRET_KEYsafe too, apart from the backups. - Once, a test. Restore a backup onto a spare install, before you need it for real.
A wallet backup is handy before a risky change to one wallet, such as a large import or a rule applied to everything. It is not a replacement for the above.
Knowing when. Once a day CloudBank looks up the latest published version
and, when yours is older, tells admins: a card at the foot of the menu, and the
same news in Settings → About. Its How to update button shows the steps
below. Only the version number is fetched; nothing about you is sent. Turn it
off in Settings → About, or for the whole server with
CB_UPDATE_CHECK=false.
CloudBank does not update itself. Replacing its own container would need access to the Docker socket, and whoever holds that socket controls the whole host. If you want updates to happen on their own, a tool outside CloudBank, such as Watchtower, can pull new images for you.
-
Read what changed: the release notes on GitHub, or CHANGELOG.md.
-
Back up, as above.
-
Pull the new image and restart:
docker compose pull docker compose up -d
At startup, CloudBank updates the database to the new version by itself. There is nothing to run by hand.
Which image you run is set by its tag. :main is the latest stable release;
:latest is the nightly build, which can break. Pin a version, such as
:v3.5.1, to upgrade only when you choose. See
Container images and tag convention.
Going back to an older version is not supported. The database only moves forward, and an older CloudBank is not guaranteed to work on a database a newer one has updated. To go back, restore the backup you took before upgrading, together with the older image.
In Settings → Import & export → Backup & integrity, choose the .json file
under Restore. The restore creates a new wallet, and never overwrites an
existing one. If the new wallet replaces an old one, delete the old one
afterwards, under Delete wallet at the bottom of the same page.
Afterwards, reconnect the wallet's banks, which the wallet backup does not hold.
Put the downloaded file in the current directory, and use its name in the second command:
docker compose stop cloudbank
docker run --rm --volumes-from cloudbank -v "$PWD:/backup" alpine sh -c 'rm -f /data/cloudbank.db-wal /data/cloudbank.db-shm && cp /backup/cloudbank-20260928-101500.db /data/cloudbank.db && chown 65532:65532 /data/cloudbank.db'
docker compose start cloudbank-
rmremoves the old database's pending changes, which would otherwise be replayed on top of the snapshot. -
chowngives the file to the user CloudBank runs as.
Everything goes back to the moment of the snapshot: every wallet, person and setting.
docker compose stop cloudbank
docker run --rm --volumes-from cloudbank -v "$PWD:/backup" alpine sh -c 'rm -rf /data/* && tar xzf /backup/cloudbank-2026-09-28.tar.gz -C /data && chown -R 65532:65532 /data'
docker compose start cloudbankCopy /data as above, restore it on the new machine, and give the new install
the same CB_SECRET_KEY.
Settings → Import & export → Backup & integrity → Run check looks through the current wallet for anything inconsistent. For example, a reconciled transaction dated in the future. Each finding comes with a suggested Fix.
Start here
Using CloudBank
- Using CloudBank, page by page
- Importing transactions
- Automatic bank sync
- Bank mails
- Notifications
- The AI, and what it sees
- CloudBank in Home Assistant
- Adding from your phone
- Ask your data
- Schedules in your phone's calendar
Running CloudBank
Extending CloudBank
Project