HowTo: Raspberry Pi 4 default image rebuild, data upgrade from NC20 to NC25, PHP8.1, 32bit

Mods: If judged as good qualiy, could this be moved to HowTo please? I’ve not got Trust Level 2!


After many years (2018) of running NextCloud for a voluntary organisation on a RPi3 then RPi4, the uSD card corrupted requiring a complete rebuild of the OS. Given the initial install was a WDLabs NextCould Box running Ubuntu, the amount of trouble-free operation is actually really rather good, so if anything, a re-install was overdue.

Sadly, restoring a database/userdata and config backup from an older (e.g. NC20) RPi installation has several areas of “technical debt” where incremental upgrades have created incompatibilities that prevent a simple restore from working.

  • The base NCP OS has moved from 32 to 64b (would continue to be supported, but upgrade now for a longer support life)
  • The latest NC RPi images use PHP8.1, which is incompatible with restored PHP8.0 scripts, and a manual process is required to update

This is a step-by-step account of my admin tasks to perform a rebuild from NC20 to NC25, including 32bit and PHP8.1 updates, on a dedicated Raspberry Pi 4 running NextCloudPi v1.51.0 from the default release image.

  • It is not a tutorial on how/ why/ when of the steps, but my hope this will help some others as the steps documented here took about a couple of days reading to compile from the forum.
  • This HowTo was written with best efforts, but without guarantee. I cannot be held responsible for any damage to your system or data! Backup your backups…

Rebuild steps on a RPi4 with the default NCP image

Base clean build - NC25, PHP8.1, aarch64 64bit

  • Flash the latest to a uSD card
  • Login to :4443 as ncp
  • From the NCP web interface, mount and format a data USB drive (/dev/sda1 on /media/myCloudDrive)
  • Enable SSH, change user from root to pi, Enable sudo, use a temp password as force changed later
  • SSH in, forced to change the password
  • NOTE pi can sudo, but there is no access to the root account as it is disabled
    (sudo vi /etc/passwd and change the root shell from nologin to bash if you accept the risks)
  • OPTIONAL sudo apt install vim
  • OPTIONAL vi .bashrc and enable ll (add -la), add other aliases to taste

Gives a working fresh install of NC 25 using PHP8.1, and running on 64b aarch64.

Restore old data and config, revert to PHP8.0, and upgrade in stages

  • SCP nextcloud-pbk-* to USB storage, and restore the NC20 content and database.

    • NCP - nc-restore
    • NCP - nc-import-ncp
  • Current NCP RPi images (v1.51.0) are 64b and use PHP8.1, which are not compatible with pre-v24 restored databases giving an error…
    This version of Nextcloud is not compatible with > PHP 8.0. You are currently running 8.1.14.

Install PHP8.0 and switch back to get the restore a working system…

  • dpkg --get-selections | grep php - list all PHP8.1 packages, and then manually install the PHP8.0 packages (paste, then change 8.1 to 8.0)
    • apt update && apt install php8.0 php8.0-readline ....
  • update-alternatives --list php - shows 8.1 selected
  • update-alternatives --config php - switch back to 8.0 from 8.1
  • Reboot
  • (wait as unattended-upgrade may be triggered)
  • Reconfigure apache for PHP8.0 (if missed, the web interface may collapse with HTML errors everywhere)
    • a2enmod proxy_fcgi setenvif
    • a2enconf php8.0-fpm
    • systemctl reload apache2
  • Polls app failed to update, so disabled
    • sudo -u www-data /usr/bin/php8.0 /var/www/nextcloud/occ upgrade - FAILS DeleteInvalidRecords.php:142
    • sudo -u www-data /usr/bin/php8.0 /var/www/nextcloud/occ app:disable polls
    • sudo -u www-data /usr/bin/php8.0 /var/www/nextcloud/occ maintenance:mode --off

Gives a working NC / NCP v1.51.0 on PHP8.0.

Upgrade in stages from NC22 → NC25

I prefer to use the command line version as the web doesn’t show the next available version as easily. The command line version takes a bit of work to get the paths correct, but once working, is basically HIT Yes for each upgrade.

  • sudo -u www-data /usr/bin/php8.0 --define apc.enable_cli=1 /var/www/nextcloud/updater/updater.phar
  • sudo -u www-data /usr/bin/php8.0 /var/www/nextcloud/occ update:check (may fail sometimes on later versions)

My upgrade steps were:

  • => 22.2.10
  • 22.2.10 => 23.0.12
  • 23.0.12 => 24.0.10
  • 24.0.10 => 25.0.4
  • “Everything up to date” - good!

Post-upgrade fixes

  • Login as user ncp, then select “Administration Settings”, Overview, then check “Security & setup warnings”

    • Showed some database issues so fixed via:
      sudo -u www-data /usr/bin/php8.0 /var/www/nextcloud/occ db:add-missing-indices
    • Theming wanted SVG support:
      apt install libmagickcore-6.q16-6-extra php8.0-imagick
    • The PHP memory limit is below the recommended value of 512MB.
      vim /etc/php/8.0/fpm/php.ini, change memory_limit = 1G
      (was 128MB as default)
  • Backup and export config

    • Web interface, nc-backup, include data, compress

At this point you have a backup compatible with NC25, so you can either reflash the RPi with the original install image and restore the newly-converted backups, or revert the current install to PHP8.1.

Revert back from PHP8.0 to PHP8.1

N.B. Nextcloud 24 is the first major Nextcloud release to work with PHP8.1, so you need to have converted your data to at least NC24 (which is what the last few sections achieved…).

The later versions of NC support PHP8.1, so switch packages back

  • dpkg --get-selections | grep php - list all PHP8.0 packages, and then manually install the PHP8.1 packages (paste, then change 8.0 to 8.1)
  • apt install php8.1 php8.1-readline ....
  • update-alternatives --list php - shows 8.1 selected
  • update-alternatives --config php - switch back to 8.1 from 8.0
  • Reboot
  • (wait as unattended-upgrade may be triggered)
  • Reconfigure apache for PHP8.1 (if missed, the web interface may collapse with HTML errors everywhere)
    • a2enmod proxy_fcgi setenvif
    • a2enconf php8.1-fpm
    • systemctl reload apache2
  • apt remove php8.0 php8.0-readline ....
  • Redo the PHP memory limit change if needed (from 8,0 above)
    vim /etc/php/8.1/fpm/php.ini, change memory_limit = 1G

I hope this helps someone else - and thanks to the developers, supports, and community that has brought NextCloud this far!


Hi @FloatingBoater , thank you so much for your attempt to provide a working description of how to get and keep things running concerning NextCloud. Although I have not tried your recipe, yet, I can only state that something like this help for private RaspberryPi usage is really necessary.

I have been supporting various non-profit organizations by installing and trying to maintain NextCloud on RaspberryPis. But in the long run, this causes just too much trouble for me, as …

  • SD cards crash after some months / years (this obviously has nothing to do with NextCloud in the first place, but there should be a clear way for recovery)
  • clients on Raspberry Pi eventually just stop working (no way to update packages or connect to the service again, without re-installing the whole system, beforehand)
  • issues appearing after auto-updates of NC (then we go into the forums, hoping that there are people who already know the cure… trying to fix things on the local system… being anxious about possibly creating further issues by trying the suggested modifications…)

I am already recommending all people to use “Managed NextCloud” from any of the available providers. For a small amount of monthly fees, this saves so much of my time. But I am sad that I couldn’t manage to really understand how to maintain NextCloud in connection with clients and servers installed on RaspberryPis. Maybe due to the lack of somebody who really manages the respective NextCloud package.

Hope to be able to test your recipe when I have some time. Right now, I would rather give up and say: in the long run, NextCloud doesn’t seem to be manageable on the RaspberryPi. Especially not, when dealing with real and important user data.