Merge pull request #13092 from nextcloud/enh/noid/standardize-occ-command

standardize occ command documentation

Author: st3iny

.github/workflows/check-occ-command.yml

@@ -0,0 +1,28 @@
+name: Check occ command syntax
+
+on:
+  pull_request:
+    paths:
+      - '**.rst'
+
+jobs:
+  check-occ-command:
+    name: Check occ command syntax
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run script
+        run: |
+          RST_FILE="$(find ./ -name '*.rst')"
+          mapfile -t RST_FILE <<< "$RST_FILE"
+          for file in "${RST_FILE[@]}"; do
+            if [ "$(grep "php occ" "$file" | grep -v "sudo -E -u www-data php occ" | wc -l)" -gt 0 ]; then
+              printf "%b%s%b\n" "\e[0;31m" "$file does not use the 'sudo -E -u www-data php occ' syntax in some places which is required." "\e[0m"
+              echo "See $(grep "php occ" "$file" | grep -v "sudo -E -u www-data php occ")"
+              FAIL=1
+            fi
+          done
+          if [ -n "$FAIL" ]; then
+            exit 1
+          fi

admin_manual/ai/app_assistant.rst

@@ -17,7 +17,7 @@ You can install the *assistant* app via the "Apps" page in Nextcloud, or by exec
 
 .. code-block::
 
-   php occ app:enable assistant
+   sudo -E -u www-data php occ app:enable assistant
 
 App store
 ---------

admin_manual/ai/app_summary_bot.rst

@@ -87,7 +87,7 @@ After cloning this app *manually* (cloned via git to your apps directory) you wi
 
 .. code-block::
 
-   sudo -u <the_user_the_webserver_is_running_as> php /path/to/your/nextcloud/webroot/occ app_api:app:unregister summary_bot
+   sudo -E -u www-data php occ app_api:app:unregister summary_bot
    
 
 5. Register the Summary Bot so that your Nextcloud instance is aware of it
@@ -96,7 +96,7 @@ After cloning this app *manually* (cloned via git to your apps directory) you wi
 
 .. code-block::
 
-   sudo -u <the_user_the_webserver_is_running_as> php ./occ app_api:app:register summary_bot manual_install --json-info '{ "id": "summary_bot", "name": "Summary Bot", "daemon_config_name": "manual_install", "version": "1.0.0", "secret": "12345", "host": "0.0.0.0", "port": 9031, "scopes": ["AI_PROVIDERS", "TALK", "TALK_BOT"], "protocol": "http"}' --force-scopes --wait-finish
+   sudo -E -u www-data php occ app_api:app:register summary_bot manual_install --json-info '{ "id": "summary_bot", "name": "Summary Bot", "daemon_config_name": "manual_install", "version": "1.0.0", "secret": "12345", "host": "0.0.0.0", "port": 9031, "scopes": ["AI_PROVIDERS", "TALK", "TALK_BOT"], "protocol": "http"}' --force-scopes --wait-finish
 
 
 6. Enable the *Summary Bot* for the selected Chatroom via the three dots menu of the Chatroom (The Bots settings are located inside the *Bots* section)

admin_manual/ai/overview.rst

@@ -218,13 +218,13 @@ It would be best to run one command per screen session or per tmux window/pane t
 
 .. code-block::
 
-   set -e; while true; do sudo -u www-data occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done
+   set -e; while true; do sudo -E -u www-data php occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done
 
 For Nextcloud-AIO you should use this command on the host server.
 
 .. code-block::
 
-   set -e; while true; do docker exec -u www-data -it nextcloud-aio-nextcloud php occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done
+   set -e; while true; do docker exec -it nextcloud-aio-nextcloud sudo -E -u www-data php occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done
 
 You may want to adjust the number of workers and the timeout (in seconds) to your needs.
 The logs of the worker can be checked by attaching to the screen or tmux session.
@@ -256,7 +256,7 @@ Systemd service
    #!/bin/sh
    echo "Starting Nextcloud AI Worker $1"
    cd /path/to/nextcloud
-   sudo -u www-data php occ background-job:worker -t 60 'OC\TaskProcessing\SynchronousBackgroundJob'
+   sudo -E -u www-data php occ background-job:worker -t 60 'OC\TaskProcessing\SynchronousBackgroundJob'
 
 You may want to adjust the timeout to your needs (in seconds).
 

admin_manual/configuration_database/bigint_identifiers.rst

@@ -9,18 +9,18 @@ and activity table has to be triggered manually by a console command.
 
 The command can safely be executed. It will show a success message when there is nothing to do::
 
-    sudo -u www-data php occ db:convert-filecache-bigint
+    sudo -E -u www-data php occ db:convert-filecache-bigint
     All tables already up to date!
 
 or otherwise ask for confirmation, before performing the heavy actions::
 
-    sudo -u www-data php occ db:convert-filecache-bigint
+    sudo -E -u www-data php occ db:convert-filecache-bigint
     This can take up to hours, depending on the number of files in your instance!
     Continue with the conversion (y/n)? [n]
 
 to suppress the confirmation message append ``--no-interaction`` to the argument list::
 
-    sudo -u www-data php occ db:convert-filecache-bigint --no-interaction
+    sudo -E -u www-data php occ db:convert-filecache-bigint --no-interaction
 
 
 .. note:: Similar to a normal update, you should shutdown your Apache or nginx server or enable maintenance

admin_manual/configuration_database/db_conversion.rst

@@ -34,7 +34,7 @@ The ``occ db:convert-type`` command handles all the tasks of the conversion. The
 
 ::
 
-  php occ db:convert-type [options] type username hostname database
+  sudo -E -u www-data php occ db:convert-type [options] type username hostname database
 
 ``type`` should be the target database type. The same values are available here as for the ``config.php`` ``dbtype`` parameter. It should be one of: ``mysql`` for MariaDB/MySQL, 
 ``pgsql`` for PostgreSQL, or ``oci`` for Oracle.
@@ -55,7 +55,7 @@ Let's convert our existing (functioning) sqlite3 installation to be MariaDB/MySQ
 
 ::
 
-  php occ db:convert-type --password="<password>" --port="3306" --all-apps mysql <username> <hostname> nextcloud
+  sudo -E -u www-data php occ db:convert-type --password="<password>" --port="3306" --all-apps mysql <username> <hostname> nextcloud
 
 .. note:: It was unnecessary to specify the port in this example because ``3306`` is already the default. We did so 
    merely for demonstration purposes and completeness in case the reader is using a non-standard port on their target 
@@ -68,7 +68,7 @@ If you are converting to a MySQL/MariaDB database, you will also want to set ``m
 
 ::
 
-   php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
+   sudo -E -u www-data php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
 
 If you like, you can view the changes that were made by looking for the ``db*`` parameters in your ``config.php`` (you could also use this command before 
 doing the conversion to compare your configuration before/after):

admin_manual/configuration_database/mysql_4byte_support.rst

@@ -43,7 +43,7 @@ The result should look like this::
 3. Open a shell, change dir (adjust ``/var/www/nextcloud`` to your nextcloud location if needed), and put your nextcloud instance in maintenance mode, if it isn't already::
 
    $ cd /var/www/nextcloud
-   $ sudo -u www-data php occ maintenance:mode --on
+   $ sudo -E -u www-data php occ maintenance:mode --on
 
 4. Change your databases character set and collation:
 
@@ -53,19 +53,19 @@ The result should look like this::
 
 5. Set the ``mysql.utf8mb4`` config to true in your config.php::
 
-    $ sudo -u www-data php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
+    $ sudo -E -u www-data php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
 
 6. Convert all existing tables to the new collation by running the repair step::
 
-    $ sudo -u www-data php occ maintenance:repair
+    $ sudo -E -u www-data php occ maintenance:repair
 
 .. note::
 
     This will also change the `ROW_FORMAT` to `DYNAMIC` for your tables.
 
 7. Disable maintenance mode::
 
-   $ sudo -u www-data php occ maintenance:mode --off
+   $ sudo -E -u www-data php occ maintenance:mode --off
 
 Now you should be able to use Emojis in your file names, calendar events, comments and many more.
 

admin_manual/configuration_files/big_file_upload_configuration.rst

@@ -159,7 +159,7 @@ Adjust chunk size on Nextcloud side
 
 For upload performance improvements in environments with high upload bandwidth, the server's upload chunk size may be adjusted::
 
- sudo -u www-data php occ config:system:set --type int --value 20971520 files.chunked_upload.max_size
+ sudo -E -u www-data php occ config:system:set --type int --value 20971520 files.chunked_upload.max_size
 
 Put in a value in bytes (in this example, 20MB). Set ``--value 0`` for no chunking at all.
 

admin_manual/configuration_files/external_storage/local.rst

@@ -17,7 +17,7 @@ are on Ubuntu Linux::
 
 Important: If you use consecutive commands, make sure, you are user ``www-data``::
 
- sudo -u www-data bash
+ sudo -E -u www-data bash
  cd /path/to/localdir
  mkdir data
 

admin_manual/configuration_files/external_storage_configuration_gui.rst

@@ -158,7 +158,7 @@ Nextcloud may not always be able to find out what has been
 changed remotely (files changed without going through Nextcloud), especially
 when it's very deep in the folder hierarchy of the external storage.
 
-You might need to setup a cron job that runs ``sudo -u www-data php occ files:scan --all``
+You might need to setup a cron job that runs ``sudo -E -u www-data php occ files:scan --all``
 (or replace ``--all`` with the user name, see also :doc:`../occ_command`)
 to trigger a rescan of the user's files periodically (for example every 15 minutes), which includes
 the mounted external storage.