ThisCalculator

Everyday

Nextcloud Backup and Restore on a VPS

Updated · Standard formula, shown below

Nextcloud Backup and Restore on a VPS

This guide walks you through backing up a Nextcloud instance running on a VPS and restoring it when something goes wrong. You’ll learn how to capture both the database and the data directory, store the backup safely, and bring everything back step by step. Before you start, make sure you have SSH access to your VPS with sudo privileges, and know your Nextcloud version and the paths to your installation, data directory, and database credentials.

What You’ll Need

  • SSH access to your VPS with sudo or root privileges
  • Nextcloud installation path (usually /var/www/nextcloud)
  • Data directory path (often /var/www/nextcloud/data or a separate mount)
  • Database type and credentials (MySQL/MariaDB or PostgreSQL)
  • Enough free disk space to store the backup archive
  • Optional: a separate backup location (another server, object storage, or external drive)

Step-by-Step

  1. Enable maintenance mode. This prevents users from making changes while you copy files. Run sudo -u www-data php /path/to/nextcloud/occ maintenance:mode --on (replace the path with your actual Nextcloud directory).
  2. Back up the config and data directories. Use rsync to copy the entire Nextcloud folder (or at least config/ and data/) to a temporary location. For example: sudo rsync -a /var/www/nextcloud /backup/nextcloud-files. If your data directory is outside the main installation, copy it separately.
  3. Back up the database. For MySQL/MariaDB, run mysqldump -u root -p --single-transaction nextcloud > /backup/nextcloud-db.sql. For PostgreSQL, use pg_dump nextcloud > /backup/nextcloud-db.sql. Replace nextcloud with your actual database name.
  4. Verify the backup files. Check that the SQL dump is not empty and that the file sizes look reasonable: ls -lh /backup/.
  5. Compress the backup. Create a single archive to save space and simplify storage: sudo tar -czf /backup/nextcloud-backup-$(date +%Y%m%d).tar.gz /backup/nextcloud-files /backup/nextcloud-db.sql.
  6. Move the archive off the server. Copy it to a different machine, object storage, or external drive. For example, scp /backup/nextcloud-backup-20250101.tar.gz user@backup-server:/backups/. This protects against disk failure on the VPS.
  7. Turn off maintenance mode. Once the backup is safely stored, run sudo -u www-data php /path/to/nextcloud/occ maintenance:mode --off.

Restoring the backup:

  1. Stop the web server. To avoid conflicts, stop Apache or Nginx: sudo systemctl stop apache2 (or nginx).
  2. Enable maintenance mode on the (broken) instance. If the instance is still partially working, run the same occ maintenance:mode --on command. If it’s completely broken, skip this.
  3. Restore the files. Extract the backup archive: sudo tar -xzf /backup/nextcloud-backup-20250101.tar.gz -C /. This will overwrite the existing files in the paths stored in the archive. If you restored to a different directory, adjust the paths accordingly.
  4. Restore the database. For MySQL/MariaDB: mysql -u root -p nextcloud < /backup/nextcloud-db.sql. For PostgreSQL: psql nextcloud < /backup/nextcloud-db.sql. Make sure the database name matches your config.
  5. Set correct file permissions. Nextcloud needs specific ownership. Run sudo chown -R www-data:www-data /var/www/nextcloud and sudo chown -R www-data:www-data /var/www/nextcloud/data (adjust paths).
  6. Restart the web server. Start Apache or Nginx again: sudo systemctl start apache2 (or nginx).
  7. Run the upgrade and repair steps. Execute sudo -u www-data php /var/www/nextcloud/occ upgrade and then sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off.
  8. Test the instance. Log in as an admin, check that files are visible and that the overview page shows no errors.

Common Mistakes

  • Only backing up the data directory and forgetting the database. Nextcloud stores file metadata, users, and shares in the database, so without it the files are unusable.
  • Not enabling maintenance mode during backup. Users may be uploading files while you copy, leading to an inconsistent backup.
  • Storing the backup on the same VPS. If the disk fails, you lose both the instance and the backup. Always move it off-site.
  • Ignoring file permissions after restore. If the web server can’t read the files, Nextcloud will show errors or blank pages.
  • Using the wrong database name when restoring. Check config/config.php for the exact database name and credentials.

Tips

  • Automate the backup with a cron job that runs the commands weekly or daily, depending on how often your users upload files.
  • Use occ maintenance:mode --on instead of stopping the web server for backups, as it’s less disruptive and still prevents writes.
  • Test your restore process on a staging server before you actually need it. A backup that has never been restored is not a backup.
  • Keep multiple backup generations (e.g., keep the last 7 daily backups) to protect against corruption that may not be noticed immediately.
  • Encrypt the backup archive if it contains sensitive user data. Use gpg -c or store it in an encrypted filesystem.

Troubleshooting

After restore, you see “Internal Server Error� or a blank page. Check the web server error log (/var/log/apache2/error.log or /var/log/nginx/error.log) and the Nextcloud log (data/nextcloud.log). The most common cause is incorrect file permissions or a missing PHP module. Re-run the chown command and ensure all required PHP extensions are installed.

The database restore fails with “Access denied�. Verify that you are using the correct database user and password. You may need to create the database first if it doesn’t exist: CREATE DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;.

Users can log in but see no files. This usually means the data directory path in config/config.php does not match where you restored the files. Update the 'datadirectory' value to the correct absolute path.

You get “There are no commands defined in the ‘maintenance’ namespace.� This indicates that the occ command is being run from the wrong directory or the PHP binary is not accessible. Run it from the Nextcloud installation directory and ensure PHP is in your PATH.

The backup archive is corrupted or incomplete. If you used tar, test the archive with tar -tzf archive.tar.gz before relying on it. If it fails, redo the backup and consider using rsync to a remote location instead of a single archive.

Frequently Asked Questions

How often should I back up Nextcloud?

It depends on how frequently files change. For most personal or small business installations, a daily backup is sufficient. For active teams, consider hourly backups of the database and nightly file backups.

Can I back up only the database and not the files?

No, the files (the actual data) are essential. The database only contains metadata, so you need both to restore a working instance.

Do I need to stop the web server for a backup?

Not necessarily. Enabling maintenance mode is enough because it prevents users from writing changes. Stopping the server is more disruptive but also works.

What if my data directory is on a separate disk?

You need to back up that disk separately. The rsync command should target the mount point, and you must include it in the archive or copy it individually.

Can I restore a backup to a different server with a different IP?

Yes, but you may need to update config/config.php with the new domain or IP address. Also, run occ maintenance:repair after the restore to fix any path issues.

How do I know if my backup is valid?

Regularly test the restore process on a staging environment. Additionally, verify that the SQL dump contains tables (e.g., oc_users) and that the file sizes are plausible.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.