.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
The upgrade to 32 was supposed to take twenty minutes. Instead the updater died halfway through a migration, occ answered every command with "Nextcloud or one of the apps require upgrade - only a limited number of commands are available" and it was past 1 AM with the family calendar and a client's project files inside. What saved that Sunday (well, the following Sunday, the incident itself still ate one) was boring: a database dump from 01:30 that morning, an rsync copy of the data directory and a config folder in the restic repo. Restore, resync, back online before breakfast. I've cared about Nextcloud backups in a different way since.
This is the playbook I settled on. It's not clever. It's four things captured on a schedule, pushed offsite and restored twice a year as a drill.
The four things a Nextcloud backup must capture
The official backup documentation and my own scars agree on the list. First, the config/ folder, tiny and irreplaceable, because config.php holds the instance ID, the salt and the passwords that make your database and data directory belong to each other. Second, the data directory itself, which on my install is /srv/nextcloud-data (yours may be inside the webroot, check datadirectory in config.php). Third, the database, where shares, users, calendars, contacts and the file metadata cache live. Fourth, anything custom in apps/ or themes/, since a stock app can be re-downloaded but your patched theme can't.
The Nextcloud application directory itself doesn't make the list. It's a tar.bz2 on the mirror, identical for everyone running the same version. I still note the exact version next to each backup, because restoring a 34.0.3 database into a 34.0.1 tree is an argument you don't want to have at 2 AM.
There's also a fifth category no list mentions: the server config around Nextcloud. My Apache vhost, the PHP pool settings I've tuned and the www-data crontab all took real time to get right, so /etc/apache2/sites-available/ and a crontab -l -u www-data dump ride along in the same backup set. Rebuilding a server from a backup that contains everything except the config you spent an evening tuning is a special kind of annoying.
Consistent dumps with maintenance mode
Files and database describe each other, so backing them up at different moments creates a copy where the database mentions files that don't exist yet. For the nightly automated run I accept that tiny drift. For the weekly full backup, and always before upgrades, I flip maintenance mode on so nothing writes during the copy:
sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --onThen dump the database with the flag that preserves 4-byte characters (emoji in file names are real, ask anyone with teenagers syncing a phone):
mysqldump --single-transaction --default-character-set=utf8mb4 \
-u nextcloud -p nextcloud > nextcloud-db_$(date +%Y%m%d).sqlPostgres users swap in pg_dump and SQLite users copy one file, the docs show the exact equivalents. Afterwards, occ maintenance:mode --off brings the instance back. If it ever refuses to come back and clients keep seeing the maintenance page, that has its own set of causes and fixes, which I've collected in the guide to a Nextcloud stuck in maintenance mode.
Copying the data directory with rsync
For the file side, rsync with archive flags keeps ownership and permissions intact and only moves what changed since last night:
sudo rsync -aHx --delete /srv/nextcloud-data/ /backup/nextcloud-data/The trailing slashes matter, they're the difference between syncing contents and nesting a directory one level deeper every night. The --delete flag keeps the mirror honest; without it, files users deleted months ago pile up in the backup forever. One caveat: if you configured S3 as primary storage, your files aren't in a local directory at all and this section doesn't apply, the bucket and the database are the backup targets, a split I go into in the Nextcloud S3 primary storage guide.
Offsite with restic
A backup on the same machine survives a botched upgrade and nothing else. My actual habit is restic to an offsite repository: encrypted, deduplicated and cheap to run daily. With around 400 GB of photos and project files, the nightly restic run usually moves a few hundred megabytes and finishes in minutes, because dedup means unchanged files cost nothing.
restic -r sftp:[email protected]:/repo backup \
/srv/nextcloud-data /var/www/nextcloud/config /backup/dumps
restic -r sftp:[email protected]:/repo forget \
--keep-daily 7 --keep-weekly 4 --keep-monthly 6 --pruneThe retention line gives me a week of dailies, a month of weeklies and half a year of monthlies, which has covered every "when did this file disappear" question I've been asked. The repository end just needs disk and SSH; a storage VPS with a few terabytes of HDD is the natural home for it, and it's where my repo has lived for two years. Big media libraries deserve the same thinking on the primary side too: bulk data on bulk disk, database and OS on NVMe.
The schedule is plain cron on the Nextcloud host. At 01:30 a script flips maintenance mode on, dumps the database and flips it back off, a window of about two minutes that nobody has ever noticed. At 02:00 restic picks up the dump directory, the data directory and the config folder. That 01:30 dump is the exact file that rescued the botched 32 upgrade in the opening of this article, which is the closest a cron job has come to earning my personal gratitude. A monthly restic check rounds it out, verifying the repository isn't quietly rotting.
What a restore looks like
The restore documentation is blunt about the requirements: without the database, the data directory and the config files, you can't complete a restoration. Assuming you have all of them, here's the sequence I ran that Sunday, on a rebuilt server with the same Nextcloud version installed (the paths match my Ubuntu install guide):
sudo rsync -aHx /backup/nextcloud-data/ /srv/nextcloud-data/
sudo rsync -aHx /backup/config/ /var/www/nextcloud/config/
sudo chown -R www-data:www-data /srv/nextcloud-data /var/www/nextcloud/configThen recreate and refill the database:
sudo mariadb -e "DROP DATABASE nextcloud; CREATE DATABASE nextcloud CHARACTER SET utf8mb4;"
sudo mariadb nextcloud < nextcloud-db_20260817.sqlTwo occ commands finish the job. The first tells sync clients the server state changed, so they re-check their files instead of trusting cached sync tokens (the docs describe it as helping clients recover as much data as possible after an older backup):
sudo -u www-data php /var/www/nextcloud/occ maintenance:data-fingerprint
sudo -u www-data php /var/www/nextcloud/occ files:scan --allThe files:scan pass is only strictly needed when files moved or the data directory changed paths, but after a restore I run it anyway; it rebuilds the file cache from what's actually on disk and takes twenty minutes on my instance. Expect desktop clients to spend a while re-checking everything after the fingerprint change. That's the mechanism working, not a bug.
AIO backups: Borg and the passphrase
If you run Nextcloud All-in-One instead of a manual stack, most of the above is built in. AIO's backup uses BorgBackup, snapshots the whole instance in a consistent state and can verify and restore from its own interface. It's genuinely good, and it has one sharp edge: the backups are encrypted with a passphrase AIO shows you at setup, and a backup you can't decrypt is a decoration. Mine would be in the password manager and printed in the drawer with the recovery codes. Anywhere except the server it protects.
Snapshots complement backups, never replace them
LVM, ZFS or provider-level VPS snapshots are wonderful for the five minutes before an upgrade: instant, whole-disk and rolled back in one command. I take one before every major, and I keep the pre-upgrade database dump for a month afterwards even though the nightly rotation would normally expire it, because upgrade damage sometimes surfaces weeks later when someone finally opens the calendar. But a snapshot usually lives on the same disk, always in the same failure domain, and it captures the database mid-write unless you quiesce it first. Treat snapshots as the undo button and restic as the actual backup, and you get the strengths of both. The night the updater died on me, the snapshot I'd skipped would have saved an hour; the offsite dump saved everything else.
Whatever you build, restore from it once before you trust it. My calendar has a recurring task in April and October: spin up a scratch VPS, restore last night's backup onto it, log in and open one photo. The whole drill takes under an hour and it's the only proof a backup ever gives you.
