Performing a Nextcloud upgrade via the command line is the recommended method for large installations. While the web-based upgrade wizard is convenient for small instances, it is prone to failure in larger environments due to server timeout limits (such as PHP execution time or Nginx/Apache request timeouts). These timeouts can interrupt the upgrade process mid-way, potentially leaving your instance in a broken state.

The command-line approach using the OCC tool allows the upgrade to run without these web-server time limits, ensuring the process completes successfully even if it takes a significant amount of time.

Prerequisites

Before beginning, ensure you have:

• SSH access to your server.
• The necessary permissions to run commands as the web server user (commonly www-data, nginx, httpd, or www).
• A recent backup of your Nextcloud data and database.

Step-by-Step Upgrade Process

1. Download the Update (Web Interface) First, download the new version via the Nextcloud web interface as you normally would. This ensures the files are present on the server. However, do not proceed with the upgrade through the browser.

2. Check Files and Prerequisites Ensure the downloaded files are correct and the system is ready. You can verify the integrity of the installation by checking the Nextcloud status or logs, but the primary preparation is ensuring the backup is complete.

3. Take a Backup Always create a full backup before making system changes. This should include:

• The Nextcloud data directory.
• The Nextcloud database.
• The Nextcloud configuration file (config.php).

4. Enable Maintenance Mode Put Nextcloud into maintenance mode to prevent users from accessing the system during the upgrade. This avoids data corruption and ensures a clean upgrade.

sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --on

Note: Replace www-data with your specific web server user (e.g., nginx, apache, httpd).

5. Perform the Upgrade Run the upgrade command. This updates the database schema and core files.

sudo -u www-data php /var/www/nextcloud/occ upgrade

6. Repair the Installation Run the repair command to fix any potential issues with file permissions, database indices, or app states that may have arisen during the upgrade.

sudo -u www-data php /var/www/nextcloud/occ maintenance:repair

7. Sync System Address Book If you use the system address book, sync it to ensure contacts are up to date.

sudo -u www-data php /var/www/nextcloud/occ dav:sync-system-addressbook

8. Scan Files Scan the file system to ensure the database accurately reflects the files on disk. This is crucial for large instances to identify any missing or orphaned files.

sudo -u www-data php /var/www/nextcloud/occ files:scan --all

9. Disable Maintenance Mode Once all commands have completed successfully, take Nextcloud out of maintenance mode so users can access the system again.

sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off

Post Upgrade?

• Return to the web interface and be sure everything works as expected. 
• Upgrade external components like NextCloud Talk, Whiteboard, Collabora etc.