Nextcloud Backups for Local

An independent, community-maintained add-on that backs up Local sites to Nextcloud over WebDAV.

It uses restic for encrypted incremental snapshots and rclone for the Nextcloud connection. Backups can be restored over an existing Local site or cloned into a new Local site.

This project is not affiliated with or endorsed by Nextcloud GmbH, WP Engine, Flywheel, or the Local product team. Nextcloud and the Nextcloud logo are trademarks of Nextcloud GmbH.

Status

Version 0.2.6 is a macOS-only beta release. Backup, restore, and clone have been tested with Local 10 on macOS. The bundled restic and rclone executables are universal binaries for both Apple Silicon and Intel Macs.

Features

• Nextcloud connection over HTTPS/WebDAV
• Dedicated Nextcloud app-password authentication
• Configurable target folder
• Connection test before saving
• Incremental and encrypted restic repositories
• Logical restore size displayed for every backup snapshot
• Editable default backup descriptions with site URL, date, and time
• Restore to an existing Local site
• Clone a backup into a new Local site
• Permanently delete an individual backup and prune unreferenced data
• Required, passphrase-encrypted recovery manifests for another computer
• Strong passphrase generator, recovery test, and recovery-kit export
• Recovery-passphrase rotation for existing repositories
• Credentials encrypted with Electron safeStorage
• Isolated package name, menu route, IPC channels, and settings keys
• Can run beside Local's built-in Backups feature

Requirements

• macOS Monterey 12 or newer
• Apple Silicon or a 64-bit Intel Mac
• Local 10 or newer
• A Nextcloud account with Files/WebDAV enabled
• A dedicated Nextcloud app password
• HTTPS, except for Nextcloud on localhost

Install a release

1. Download local-addon-nextcloud-backups-<version>.tgz from the release.
2. Open Local.
3. Open Add-ons → Installed.
4. Choose Install from disk and select the downloaded .tgz.
5. Enable Nextcloud Backups and restart Local when prompted.
6. Open a site and select Tools → Nextcloud Backups.

The package includes the required restic and rclone binaries. End users do not need Node.js, restic, rclone, or Git LFS.

Configure Nextcloud

Create a dedicated app password in Nextcloud under:

Personal settings → Security → Devices & sessions

Then enter:

• Nextcloud URL: the base URL, such as https://cloud.example.com
• Username: the actual Nextcloud login name
• App password: the dedicated app password
• Target folder: for example Local Backups
• Recovery passphrase: at least 12 characters, or use Generate strong passphrase

The add-on converts the base URL to the modern WebDAV endpoint:

https://cloud.example.com/remote.php/dav/files/USERNAME/

If Nextcloud is installed below a path, include it in the base URL:

https://example.com/nextcloud

Use Test connection, export the recovery kit to a protected location, then choose Save. After the first backup, use Test recovery for this site to verify that the portable recovery data can be decrypted.

The add-on requires a successful recovery-kit export before a new or changed recovery passphrase can be saved. This makes the separate recovery copy an explicit part of setup instead of an optional reminder.

Recovery passphrase

Why it is required

Every backup repository is encrypted by restic with an automatically generated repository password. That password is stored securely on the current Mac, but the macOS credential store is not transferred automatically to a replacement computer.

To make recovery on another Mac possible, the add-on writes local-backups-recovery.v1.json beside every repository in Nextcloud. This portable manifest contains the repository password and basic site metadata, but the complete manifest is encrypted with the recovery passphrase before upload. The recovery passphrase is therefore the portable key to the backups.

Version 0.2.0 and newer refuses to create a backup until a recovery passphrase has been configured.

The three different credentials

Credential	Purpose	Stored in Nextcloud	What to do after changing Macs
Nextcloud app password	Authorizes WebDAV access to the Nextcloud account	No	Create a new dedicated app password
Recovery passphrase	Decrypts the portable recovery manifests	No	Enter it from the exported recovery kit
Restic repository password	Encrypts the actual files, database, indexes, and snapshots	Only inside the encrypted recovery manifest	Recovered automatically after opening the manifest

The Nextcloud app password and recovery passphrase are not interchangeable. Revoking an app password does not decrypt, damage, or invalidate existing backup data.

Creating the recovery passphrase

1. Open a Local site and go to Tools → Nextcloud Backups.
2. Open Configure Nextcloud.
3. Enter the Nextcloud URL, username, dedicated app password, and target folder.
4. Choose Generate strong passphrase. The generator creates 128 bits of cryptographically random data and formats it in readable groups.
5. Alternatively, enter your own passphrase and repeat it in the confirmation field.
6. Choose Export recovery kit and save the file in a protected location.
7. Choose Save.
8. Create the first backup.
9. Reopen the configuration and choose Test recovery for this site.

Requirements for a manually chosen passphrase:

• At least 12 characters
• No mandatory mixture of uppercase, lowercase, numbers, or symbols
• Unique to this backup installation
• Preferably generated and stored by a password manager

Length and randomness are more important than artificial composition rules. The built-in generator is the recommended option.

Recovery kit

The exported Nextcloud-Backups-Recovery-Kit.txt contains:

• Nextcloud WebDAV URL
• Nextcloud username
• Target folder
• Recovery passphrase in plain text
• Short recovery instructions

It deliberately does not contain the Nextcloud app password. App passwords can be revoked and recreated in Nextcloud at any time.

Because the recovery kit contains the recovery passphrase in plain text:

• Store it in a password manager, encrypted archive, encrypted external drive, or another protected location.
• Keep at least one copy outside the Mac used for Local.
• Do not store the only copy inside the same Nextcloud account as the backups.
• Do not attach it to GitHub issues, support requests, screenshots, or emails.
• Anyone who has both the kit and access to the Nextcloud account can restore the backups.

The exported file is created with owner-only file permissions on macOS where the filesystem supports them. This does not replace secure storage or encryption of the exported file.

The setup screen requires a successful recovery-kit export before a new or changed recovery passphrase can be saved. The add-on cannot detect whether the exported file is later moved or deleted, so the user remains responsible for keeping it available.

Storage on the current Mac

For normal daily backups, the recovery passphrase is stored through Electron safeStorage and protected by macOS. Users do not need to enter it for every backup.

This local copy is not a substitute for the recovery kit. If the Mac, macOS user profile, or Local application data is lost, the locally stored value may no longer be available.

The recovery passphrase itself is never uploaded to Nextcloud. Nextcloud only receives recovery manifests encrypted with AES-256-GCM using a key derived from the passphrase.

Testing recovery

After the first backup, choose Test recovery for this site. The test:

1. Downloads the site's recovery manifest from Nextcloud.
2. Decrypts it with the recovery passphrase stored on the Mac.
3. Confirms that its repository ID and target folder match the current site.

A successful test verifies the portable recovery metadata. It does not perform a destructive restore and does not modify the WordPress site.

Run the test after:

• Creating the first backup
• Changing the recovery passphrase
• Changing the Nextcloud target folder
• Reconfiguring the Nextcloud connection

Recovering on another Mac

1. Install Local and the same or a newer version of Nextcloud Backups.
2. Create a new dedicated app password in Nextcloud.
3. Open Configure Nextcloud in any Local site.
4. Enter the Nextcloud URL, username, new app password, and the original target folder.
5. Enter the recovery passphrase from the recovery kit.
6. Choose Find recoverable backups.
7. Select the required repository with Use for this Local site.
8. Refresh the backup list.
9. Restore over the selected Local site or clone the backup into a new site.

The recovery kit does not need to contain the restic repository password. The add-on obtains it by decrypting the selected recovery manifest.

Changing the recovery passphrase

1. Open Configure Nextcloud on the original Mac.
2. Generate or enter and confirm a new recovery passphrase.
3. Export a new recovery kit.
4. Keep the old recovery kit temporarily.
5. Choose Save.
6. Check the reported number of synchronized, rotated, or failed recovery manifests.
7. Run Test recovery for this site for the relevant Local sites.
8. Only after successful tests, replace or securely delete the old recovery kit.

Saving a changed passphrase re-encrypts reachable recovery manifests. The restic repositories and their potentially large backup data are not uploaded again. If a repository was offline, moved, or could not be updated, retain the old recovery kit until that repository has been checked.

Existing installations

Installations created before recovery passphrases became mandatory are prompted to configure one. Saving the configuration creates encrypted recovery manifests for repositories still known to the local installation. Existing restic backup data remains unchanged.

After upgrading:

1. Generate a recovery passphrase.
2. Export and protect the recovery kit.
3. Save the configuration.
4. Confirm that the expected manifests were synchronized.
5. Test recovery for every important site.

If a credential is lost

• Nextcloud app password lost: revoke it in Nextcloud and create a new one. Existing backups remain usable.
• Recovery passphrase forgotten while the original Mac still works: open the configuration and export a new recovery kit, or rotate to a new passphrase and test it.
• Recovery passphrase and original Mac both lost: the encrypted recovery manifest cannot be opened. Without another preserved copy of the repository password, the backup cannot be restored.
• Nextcloud account compromised without the recovery passphrase: the restic data and portable manifests remain encrypted, but the app password should still be revoked immediately.

Storage layout

With a target folder of Local Backups, each Local site gets an independent repository:

Local Backups/
└── <repository-uuid>/
    ├── config
    ├── data/
    ├── index/
    ├── keys/
    ├── locks/
    ├── snapshots/
    └── local-backups-recovery.v1.json

These files are a restic repository and are not intended to be opened or edited individually in Nextcloud.

Build from source

Git LFS is required because the repository contains restic and rclone binaries.

git lfs install
git lfs pull
corepack enable
yarn install --frozen-lockfile
npm test
npm run build
npm run package:addon

The installable archive and SHA-256 checksum are written to dist/.

For development, clone or symlink the repository into:

• macOS: ~/Library/Application Support/Local/addons

Enable the package name local-addon-nextcloud-backups in Local.

Security

See SECURITY.md before using the add-on with important sites. Never include a real Nextcloud URL, username, app password, recovery passphrase, Local user-data directory, or backup repository in a bug report.

Attribution

This project is derived from getflywheel/local-addon-backups and retains its MIT license and copyright notice. Bundled third-party software is documented in THIRD_PARTY_NOTICES.md.

License

MIT. See LICENSE.