Some things to document

[joshtrichards]

Troubleshooting

• occ maintenance:repair (clear steps stuck)

System Requirements

• Memory (RAM):
  • At the bare minimum, currently a PHP memory_size (for Web and CLI PHP) of 256MB is required. This is subject to change as the Archive size grows.
• Disk space
  • At a bare minimum, currently enough space to fully back up the existing Nextcloud installation folder (excluding data) is required + the extracted size of the latest Archive + space for the downloaded Archive zip (currently ~220MB and it'll get deleted just after extraction however) + ? TBD

Known Issues & Bugs

• The verifyIntegrity() step requires the host system and PHP have a RAM allocation equal to the target Archive file's size (compressed fortunately) (e.g. In low memory setups, the updater fails at step 5 #505). As the Archive grows so do our memory requirements.
  • Points of reference:
    • v28.0.4 currently requires 214MB)
    • Looks like we crossed over the 100MB mark ~v18.0.0)
  • Indications:
    • In Web mode, there aren't currently any direct clues other than this step never finishes or stops
    • In Command Line mode, if the PHP memory ceiling is hit, the standard PHP memory allocation failure error is generated and the updater crashes
  • Workaround for low memory environments:
    • Perform a manual update
• We traverse the datadirectory if it's located within the installation folder even though we exclude it. This happens in both createBackup and deleteOldFiles. This makes the Updater slow - and increasingly slower as file count grows. I have a working solution that needs to be polished. Separately, knce that is merged (and field tested), since the memory requirements for using iterator_to_array() will then as a bonus be limited, we can test memory usage against current Server installation folder contents and decide whether we can also address compatibility with FreeBSD NFS and some other oddball environments.

Mysterious issues

These are occasionally reported matters without any discernable cause that seem to arise in some reasonable installations. Enough to pop up from time to time, but no clear idea what %:

• core/shipped.json is missing already when the Updater gets to deleteOldFiles()
  • Theory: manually forced reruns (i.e. .step is removed or similar to fully restart Updater run after at least once run has already gotten past this step; though not sure how really)

Ideas for improving the Updater

• We should probably check that memory_limit is >= 256M since there's no point in proceeding since we'll fail; at least by checking ahead of time we can give the error a more useful error message so they know why (e.g. In low memory setups, the updater fails at step 5 #505)
  • Really important for the Web mode since the "Allowed memory size... exhausted" message from PHP won't appear to the user so they'll just see a random failure otherwise
• We should probably check for some reasonable disk space availability before we let the Updater run rather than erring later on (e.g. Not enough disc space #154 Available disk space check #523 Update fails when there is not enough disk space #175 Error Updater 17.0.0 Extracting Error during unpacking zipfile: No error - and now another Error #248)
• We should review all the spots where we use isDir / isFile (or is_dir / is_file - same situation) to make sure we're catching sym links beforehand (or that it's a spot where we're okay with sym links slipping through)
• If the Updater is started and an existing .step is detected we should make that clearer by giving the user messaging to that effect
• We should tell people about - then also remind them about - the dedicated updater.log
• Allow to specify a version to update to #336 / Add option "--no-major" to CLI updater #319 + probably Manually override staged roll out #382
• Error reporting for filesystem matters #524

Ideas for refactoring for easier maintenance or readability

• Make this more like this
  • This is sent to https://github.com/nextcloud-releases/updater_server/blob/dfee88bd34642e3dd7908a797ac6b38815710800/src/Request.php#L163-L199

README

• Installing box: https://github.com/box-project/box/blob/main/doc/installation.md#composer