Skip to content

docs: show CLI updater before web updater in update.rst #14939

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
skjnldsv wants to merge 1 commit into
base: master
Choose a base branch
from
+77 −79
Open

docs: show CLI updater before web updater in update.rst #14939

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 77 additions & 79 deletions admin_manual/maintenance/update.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,83 @@ The built-in updater performs these operations:
linked page or to the command line to finish the upgrade by executing the
migration steps.

Using the command line based updater
------------------------------------

The command line based updater performs the same steps and checks as the
Copy link
Copy Markdown
Contributor

@miaulalala miaulalala May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can move to the web updater instead

Copy link
Copy Markdown
Member Author

@skjnldsv skjnldsv May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't get it 🤔

Copy link
Copy Markdown
Contributor

@miaulalala miaulalala May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the web updater is now after the command line updater, it would make sense to add this to the web updater - i. e. "The web updater performs the same steps..."

web based updater.

1. You should see a notification at the top of any Nextcloud page when there is
a new update available. Go to the admin settings page and scroll to the
section "Version". This section has a button to open the updater. This
section as well as the update notification is only available if the update
notification app is enabled in the apps management.

.. image:: images/updater-1-update-available.png
:alt: Nextcloud admin settings Version section showing an update available notification

2. Instead of clicking that button you can now invoke the command line based
updater by going into the `updater/` directory in the Nextcloud directory
and executing the `updater.phar` as the web server user. (i.e.
``sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar``)

.. image:: images/updater-cli-2-start-updater.png
:alt: Terminal showing Nextcloud command line updater starting and displaying update information
:class: terminal-image

3. Verify the information that is shown and enter "Y" to start the update.

.. image:: images/updater-cli-3-running-step.png
:alt: Terminal showing Nextcloud command line updater executing update steps
:class: terminal-image

.. image:: images/updater-cli-4-failed-step.png
:alt: Terminal showing Nextcloud command line updater with a failed step and error feedback
:class: terminal-image

4. In case an error happens or the check failed the updater stops processing
and gives feedback. You can now try to solve the problem and re-run the
updater command. This will continue the update and re-run the failed step.
It will not re-run the previous succeeded steps.

.. image:: images/updater-cli-5-continue-update.png
:alt: Terminal showing Nextcloud command line updater ready to continue after resolving an error
:class: terminal-image

6. Once all steps are executed the updater will ask you a final question:
"Should the "occ upgrade" command be executed?". This allows you to directly
execute the command line based upgrade procedure (``occ upgrade``). If you
select "No" then it will finish with
`Please now execute "./occ upgrade" to finish the upgrade.`.

.. image:: images/updater-cli-6-run-command.png
:alt: Terminal showing Nextcloud command line updater asking whether to run the occ upgrade command
:class: terminal-image

7. Once the ``occ upgrade`` is done you get asked if the maintenance mode
should be kept active.

.. image:: images/updater-cli-7-maintenance.png
:alt: Terminal showing Nextcloud command line updater asking whether to keep maintenance mode active
:class: terminal-image

Batch mode for command line based updater
-----------------------------------------

It is possible to run the command line based updater in a non-interactive mode.
The updater then doesn't ask any interactive questions. It is assumed that if
an update is available it should be installed and the ``occ upgrade`` command
is executed as well. After finishing the maintenance mode will be turned off
except an error occurred during the ``occ upgrade`` or the replacement of the
code.

To execute this, run the command with the ``--no-interaction`` option. (i.e.
``sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar --no-interaction``)

.. image:: images/updater-cli-8-no-interaction.png
:alt: Terminal showing Nextcloud command line updater running in non-interactive batch mode
:class: terminal-image

Using the web based updater
---------------------------

Expand Down Expand Up @@ -160,85 +237,6 @@ This is how the command line based update would continue:
Maintenance mode is kept active
Reset log level

Using the command line based updater
------------------------------------

The command line based updater works in the exact same way the web based
updater works. The steps and checks are the very same.

The steps are basically the same as for the web based updater:

1. You should see a notification at the top of any Nextcloud page when there is
a new update available. Go to the admin settings page and scroll to the
section "Version". This section has a button to open the updater. This
section as well as the update notification is only available if the update
notification app is enabled in the apps management.

.. image:: images/updater-1-update-available.png
:alt: Nextcloud admin settings Version section showing an update available notification

2. Instead of clicking that button you can now invoke the command line based
updater by going into the `updater/` directory in the Nextcloud directory
and executing the `updater.phar` as the web server user. (i.e.
``sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar``)

.. image:: images/updater-cli-2-start-updater.png
:alt: Terminal showing Nextcloud command line updater starting and displaying update information
:class: terminal-image

3. Verify the information that is shown and enter "Y" to start the update.

.. image:: images/updater-cli-3-running-step.png
:alt: Terminal showing Nextcloud command line updater executing update steps
:class: terminal-image

.. image:: images/updater-cli-4-failed-step.png
:alt: Terminal showing Nextcloud command line updater with a failed step and error feedback
:class: terminal-image

4. In case an error happens or the check failed the updater stops processing
and gives feedback. You can now try to solve the problem and re-run the
updater command. This will continue the update and re-run the failed step.
It will not re-run the previous succeeded steps.

.. image:: images/updater-cli-5-continue-update.png
:alt: Terminal showing Nextcloud command line updater ready to continue after resolving an error
:class: terminal-image

6. Once all steps are executed the updater will ask you a final question:
"Should the "occ upgrade" command be executed?". This allows you to directly
execute the command line based upgrade procedure (``occ upgrade``). If you
select "No" then it will finish with
`Please now execute "./occ upgrade" to finish the upgrade.`.

.. image:: images/updater-cli-6-run-command.png
:alt: Terminal showing Nextcloud command line updater asking whether to run the occ upgrade command
:class: terminal-image

7. Once the ``occ upgrade`` is done you get asked if the maintenance mode
should be kept active.

.. image:: images/updater-cli-7-maintenance.png
:alt: Terminal showing Nextcloud command line updater asking whether to keep maintenance mode active
:class: terminal-image

Batch mode for command line based updater
-----------------------------------------

It is possible to run the command line based updater in a non-interactive mode.
The updater then doesn't ask any interactive questions. It is assumed that if
an update is available it should be installed and the ``occ upgrade`` command
is executed as well. After finishing the maintenance mode will be turned off
except an error occurred during the ``occ upgrade`` or the replacement of the
code.

To execute this, run the command with the ``--no-interaction`` option. (i.e.
``sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar --no-interaction``)

.. image:: images/updater-cli-8-no-interaction.png
:alt: Terminal showing Nextcloud command line updater running in non-interactive batch mode
:class: terminal-image

Troubleshooting
---------------

Expand Down
Loading