diff --git a/.github/problem-matchers/sphinx-lint.json b/.github/problem-matchers/sphinx-lint.json new file mode 100644 index 00000000000..1f85e7e6183 --- /dev/null +++ b/.github/problem-matchers/sphinx-lint.json @@ -0,0 +1,15 @@ +{ + "problemMatcher": [ + { + "owner": "sphinx-lint", + "pattern": [ + { + "regexp": "^([^:]+\\.(?:rst|py)):(\\d+): (.+)$", + "file": 1, + "line": 2, + "message": 3 + } + ] + } + ] +} diff --git a/.github/workflows/sphinx-lint.yml b/.github/workflows/sphinx-lint.yml new file mode 100644 index 00000000000..7af4f737107 --- /dev/null +++ b/.github/workflows/sphinx-lint.yml @@ -0,0 +1,42 @@ +name: 'Sphinx Lint' + +on: + pull_request: + push: + branches: + - master + - stable* + +permissions: + contents: read + +jobs: + sphinx-lint: + name: Lint RST files + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 + with: + python-version: "3.13" + cache: "pip" + + # The workflow pins sphinx-lint directly (not via requirements.txt) to keep + # this job lightweight — requirements.txt pulls in the full Sphinx build + # stack (Pillow, rst2pdf, reportlab, …) which is not needed for linting. + # sphinx-lint is also listed in requirements.txt so local dev environments + # get the same version when running `pip install -r requirements.txt`. + - name: Install sphinx-lint + run: pip install sphinx-lint==1.0.2 + + - name: Register sphinx-lint problem matcher + run: echo "::add-matcher::.github/problem-matchers/sphinx-lint.json" + + - name: Run sphinx-lint + run: sphinx-lint admin_manual developer_manual user_manual diff --git a/admin_manual/ai/app_context_agent.rst b/admin_manual/ai/app_context_agent.rst index eceff42db48..3796e8d98ca 100644 --- a/admin_manual/ai/app_context_agent.rst +++ b/admin_manual/ai/app_context_agent.rst @@ -442,8 +442,8 @@ Known Limitations ----------------- * Make sure to test the language model you are using in concert with this app for whether they meet the use-case's quality requirements * Most models have difficulties with languages other than English. Some models sometimes answer in a different language than the one used by the user. -* Customer support is available upon request, however we can't solve false or problematic output, most performance issues, or other problems caused by the underlying model. - Support is thus limited only to bugs directly caused by the implementation of the app (connectors, API, front-end, AppAPI). We still try to optimize this as far as possible, so if you encounter any false or problematic output, you can report it `in a dedicated Github issue `_ to help us improve this app. +* Customer support is available upon request, however we can't solve false or problematic output, most performance issues, or other problems caused by the underlying model. + Support is thus limited only to bugs directly caused by the implementation of the app (connectors, API, front-end, AppAPI). We still try to optimize this as far as possible, so if you encounter any false or problematic output, you can report it `in a dedicated Github issue `_ to help us improve this app. * When multiple MCP services are configured that have tools with the same name undefined behavior will occur. * Only remote MCP services are supported (streamable_http transport). -* MCP services that require different access tokens for each user are not currently supported. \ No newline at end of file +* MCP services that require different access tokens for each user are not currently supported. diff --git a/admin_manual/ai/app_summary_bot.rst b/admin_manual/ai/app_summary_bot.rst index aaf72c4e929..9ac1bfc6650 100644 --- a/admin_manual/ai/app_summary_bot.rst +++ b/admin_manual/ai/app_summary_bot.rst @@ -88,7 +88,7 @@ After cloning this app *manually* (cloned via git to your apps directory) you wi .. code-block:: 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 @@ -125,7 +125,7 @@ Ethical AI Rating The ethical rating of the *Summary Bot*, which utilizes a model for text processing through the Nextcloud Assistant app, is significantly influenced by the choice and implementation of the underlying model. -Learn more about the Nextcloud Ethical AI Rating `in our blog`. +Learn more about the Nextcloud Ethical AI Rating `in our blog `_. Known Limitations ----------------- diff --git a/admin_manual/ai/eu_ai_act.rst b/admin_manual/ai/eu_ai_act.rst index 21ea2e68b04..f00b86442aa 100644 --- a/admin_manual/ai/eu_ai_act.rst +++ b/admin_manual/ai/eu_ai_act.rst @@ -57,4 +57,4 @@ Additional requirements when using large AI models Nextcloud's AI products are designed to be used with smaller AI models that can also run on-premise. Nextcloud's AI Act compliance efforts thus assume you are using models that were trained using less than 10^25 floating point operations. However, Nextcloud's AI products are designed (in accordance with the AI act) to be interoperable and therefore it is technically possible to use larger models. -If you decide to use larger models, this qualifies as a significant modification of the system and additional legal requirements for systemic-risk General purpose AI systems apply. Please refer to a lawyer and to `the EU AI Act `_. \ No newline at end of file +If you decide to use larger models, this qualifies as a significant modification of the system and additional legal requirements for systemic-risk General purpose AI systems apply. Please refer to a lawyer and to `the EU AI Act `_. diff --git a/admin_manual/ai/insight_and_debugging.rst b/admin_manual/ai/insight_and_debugging.rst index cb6bbb96804..1d9f6f96e34 100644 --- a/admin_manual/ai/insight_and_debugging.rst +++ b/admin_manual/ai/insight_and_debugging.rst @@ -91,4 +91,4 @@ For example { ... } - ] \ No newline at end of file + ] diff --git a/admin_manual/apps_management.rst b/admin_manual/apps_management.rst index e6381f82d00..998b9c33e19 100644 --- a/admin_manual/apps_management.rst +++ b/admin_manual/apps_management.rst @@ -100,7 +100,7 @@ For example, to enable the "files" app, run: To enable the app for specific groups, use the `--groups` option: :: - + occ app:enable files --groups=admin diff --git a/admin_manual/conf.py b/admin_manual/conf.py index cb8ee91290a..376ad1e06de 100644 --- a/admin_manual/conf.py +++ b/admin_manual/conf.py @@ -6,7 +6,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html # ## Note that additional configuration elements shared by all Nextcloud docs -## are loaded from `../conf.py`. +## are loaded from `../conf.py`. # -- Path setup -------------------------------------------------------------- @@ -119,7 +119,7 @@ 'Nextcloud', 'The Nextcloud Server Administration Manual.', 'Miscellaneous', - ), + ), ] # -- Options for todo extension ---------------------------------------------- diff --git a/admin_manual/configuration_database/bigint_identifiers.rst b/admin_manual/configuration_database/bigint_identifiers.rst index aeba768b607..44bead5c3cd 100644 --- a/admin_manual/configuration_database/bigint_identifiers.rst +++ b/admin_manual/configuration_database/bigint_identifiers.rst @@ -3,8 +3,8 @@ BigInt (64bit) identifiers ========================== Nextcloud uses big integers to store identifiers and auto-increment keys in the database. -Because changing columns on huge tables can take quite a while (up to hours or days) -depending on the number of files in the Nextcloud instance, this migration on the filecache +Because changing columns on huge tables can take quite a while (up to hours or days) +depending on the number of files in the Nextcloud instance, this migration on the filecache 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:: diff --git a/admin_manual/configuration_database/db_conversion.rst b/admin_manual/configuration_database/db_conversion.rst index f576ed3bfb1..c01a1e7188b 100644 --- a/admin_manual/configuration_database/db_conversion.rst +++ b/admin_manual/configuration_database/db_conversion.rst @@ -19,7 +19,7 @@ Conversion consists of two steps: Establishing the target database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -First create up the target (new) database (along with its associated username and password) by following the manual database configuration instructions for your chosen target database type: +First create up the target (new) database (along with its associated username and password) by following the manual database configuration instructions for your chosen target database type: * :ref:`db-config-mysql-label` * :ref:`db-config-postgresql-label` @@ -36,7 +36,7 @@ The ``occ db:convert-type`` command handles all the tasks of the conversion. The 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, +``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. The options: @@ -57,8 +57,8 @@ Let's convert our existing (functioning) sqlite3 installation to be MariaDB/MySQ sudo -E -u www-data php occ db:convert-type --password="" --port="3306" --all-apps mysql 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 +.. 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 database server. On success the converter will automatically configure the new database in your @@ -70,7 +70,7 @@ If you are converting to a MySQL/MariaDB database, you will also want to set ``m 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 +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): :: diff --git a/admin_manual/configuration_database/linux_database_configuration.rst b/admin_manual/configuration_database/linux_database_configuration.rst index f1cd63a7eed..4217b76c2fb 100644 --- a/admin_manual/configuration_database/linux_database_configuration.rst +++ b/admin_manual/configuration_database/linux_database_configuration.rst @@ -193,7 +193,7 @@ Adjust the paths to the pem files for your environment. PostgreSQL database ^^^^^^^^^^^^^^^^^^^ -In order to run Nextcloud securely on PostgreSQL, it is assumed that only +In order to run Nextcloud securely on PostgreSQL, it is assumed that only Nextcloud uses this database and thus only one user accesses the database. For further services and users, we recommend to create a separate database or PostgreSQL instance. diff --git a/admin_manual/configuration_database/replication.rst b/admin_manual/configuration_database/replication.rst index 7cf6fc5231a..f1c5ec927e5 100644 --- a/admin_manual/configuration_database/replication.rst +++ b/admin_manual/configuration_database/replication.rst @@ -8,7 +8,7 @@ Nextcloud can natively split read and write operations on a database query level :: - 'dbreplica' => [ + 'dbreplica' => [ ['user' => 'nextcloud', 'password' => 'password1', 'host' => '10.0.3.1', 'dbname' => 'nextcloud'], ['user' => 'nextcloud', 'password' => 'password2', 'host' => '10.0.3.2', 'dbname' => 'nextcloud'], ], diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index 33ee1d59214..f35fcccb1c8 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -30,9 +30,9 @@ Definitions - **User Keys:** Each user has their own key, protected by their password, to encrypt their files. - **Recovery Key:** An admin-defined key to recover files if users lose their passwords. -- **Disk/Block Device Encryption:** A method of securing all data stored on a physical - storage device by encrypting it at the hardware or filesystem level - typically using - tools such as LUKS on Linux - so that data is only accessible after the device is +- **Disk/Block Device Encryption:** A method of securing all data stored on a physical + storage device by encrypting it at the hardware or filesystem level - typically using + tools such as LUKS on Linux - so that data is only accessible after the device is unlocked with the correct key or password. Encryption Method Comparison @@ -136,7 +136,7 @@ Key Management Modes - If you need to prevent admins from accessing files, use E2EE. - User key mode offers some protection against malicious server administrators, but has limitations. -**To select user key mode:** +**To select user key mode:** Run: diff --git a/admin_manual/configuration_files/external_storage/amazons3.rst b/admin_manual/configuration_files/external_storage/amazons3.rst index bd0b81e7245..5b99e96cf54 100644 --- a/admin_manual/configuration_files/external_storage/amazons3.rst +++ b/admin_manual/configuration_files/external_storage/amazons3.rst @@ -24,24 +24,24 @@ In the **Access key** field enter your *S3 access key ID*. In the **Secret key** field enter your *S3 access key*. -**If you are using Amazon S3:** the :code:`Region` parameter is required unless you're happy with -the default of :code:`eu-west-1` (which will be used if you don't specify anything). There is no -need to override the :code:`Hostname` or :code:`Port`. And :code:`Storage Class` only needs to be -modified if you're using a different configuration at AWS. Lastly, :code:`Enable Path Style` is -rarely required with Amazon, but some legacy Amazon datacenters may require it. Leave +**If you are using Amazon S3:** the :code:`Region` parameter is required unless you're happy with +the default of :code:`eu-west-1` (which will be used if you don't specify anything). There is no +need to override the :code:`Hostname` or :code:`Port`. And :code:`Storage Class` only needs to be +modified if you're using a different configuration at AWS. Lastly, :code:`Enable Path Style` is +rarely required with Amazon, but some legacy Amazon datacenters may require it. Leave :code:`Legacy (v2) authentication` unselected. -**If you using a non-Amazon hosted S3 store:** you will need to set the :code:`Hostname` -parameter (and can ignore the :code:`Region` parameter). You may need to enable :code:`Enable Path Style` +**If you using a non-Amazon hosted S3 store:** you will need to set the :code:`Hostname` +parameter (and can ignore the :code:`Region` parameter). You may need to enable :code:`Enable Path Style` if your non-Amazon S3 store does *not* support requests like :code:`https://bucket.hostname.domain/`. -Setting :code:`Enable Path Style` to true configures the S3 client to make requests like +Setting :code:`Enable Path Style` to true configures the S3 client to make requests like :code:`https://hostname.domain/bucket` instead. It's rare to need :code:`Legacy (v2) authentication`, but enable it if your in-house object store or service provider requires it over the default (v4) authentication. In the **Available for** field enter the users or groups who you want to give give access to your S3 mount. -The ``Enable SSL`` checkbox enables HTTPS connections and generally preferred. It is the default unless +The ``Enable SSL`` checkbox enables HTTPS connections and generally preferred. It is the default unless you disable it here. Optionally, a 32-byte base64 encoded SSE-C key can be provided for server side encryption. See :doc:`../primary_storage` and the `SSE-C AWS documentation `_ for more information how to generate a key. diff --git a/admin_manual/configuration_files/external_storage/ftp.rst b/admin_manual/configuration_files/external_storage/ftp.rst index 1962baa2af6..38e90450c23 100644 --- a/admin_manual/configuration_files/external_storage/ftp.rst +++ b/admin_manual/configuration_files/external_storage/ftp.rst @@ -4,32 +4,32 @@ FTP/FTPS To connect to an FTP server, you will need: -* A folder name for your local mountpoint; the folder will be created if it +* A folder name for your local mountpoint; the folder will be created if it does not exist * The URL of the FTP server * Port number (default: 21) * FTP server username and password -* Remote Subfolder, the FTP directory to mount in Nextcloud. Nextcloud defaults - to the root directory. If you specify a subfolder you must leave +* Remote Subfolder, the FTP directory to mount in Nextcloud. Nextcloud defaults + to the root directory. If you specify a subfolder you must leave off the leading slash. For example, ``public_html/images`` - -Your new mountpoint is available to all users by default, and you may restrict -access by entering specific users or groups in the **Available for** field. -Optionally, Nextcloud can use FTPS (FTP over SSL) by checking **Secure ftps://**. -This requires additional configuration with your root certificate if the FTP +Your new mountpoint is available to all users by default, and you may restrict +access by entering specific users or groups in the **Available for** field. + +Optionally, Nextcloud can use FTPS (FTP over SSL) by checking **Secure ftps://**. +This requires additional configuration with your root certificate if the FTP server uses a self-signed certificate. .. figure:: images/ftp.png - :alt: Nextcloud GUI FTP configuration. + :alt: Nextcloud GUI FTP configuration. .. note:: The external storage ``FTP/FTPS`` needs the ``allow_url_fopen`` PHP - setting to be set to ``1``. When having connection problems make sure that it - is not set to ``0`` in your ``php.ini``. See :ref:`label-phpinfo` to learn + setting to be set to ``1``. When having connection problems make sure that it + is not set to ``0`` in your ``php.ini``. See :ref:`label-phpinfo` to learn how to find the right ``php.ini`` file to edit. -See :doc:`../external_storage_configuration_gui` for additional mount +See :doc:`../external_storage_configuration_gui` for additional mount options and information. -FTP uses the password authentication scheme; see :doc:`auth_mechanisms` for +FTP uses the password authentication scheme; see :doc:`auth_mechanisms` for more information on authentication schemes. diff --git a/admin_manual/configuration_files/external_storage/local.rst b/admin_manual/configuration_files/external_storage/local.rst index b9dfa45ffe1..01d0b1bd110 100644 --- a/admin_manual/configuration_files/external_storage/local.rst +++ b/admin_manual/configuration_files/external_storage/local.rst @@ -4,12 +4,12 @@ Local Local storages provide access to any directory on the Nextcloud server. Since this is a significant security risk, Local storage can only be configured in -the Nextcloud admin settings. Non-admin users cannot create Local storage -mounts. +the Nextcloud admin settings. Non-admin users cannot create Local storage +mounts. -Use this to mount any directory on your Nextcloud server that is outside -of your Nextcloud ``data/`` directory. This directory must be readable and -writable by your HTTP server user. These ownership and permission examples +Use this to mount any directory on your Nextcloud server that is outside +of your Nextcloud ``data/`` directory. This directory must be readable and +writable by your HTTP server user. These ownership and permission examples are on Ubuntu Linux:: sudo chown -R www-data:www-data /path/to/localdir @@ -21,18 +21,18 @@ Important: If you use consecutive commands, make sure, you are user ``www-data`` cd /path/to/localdir mkdir data -In the **Folder name** field enter the folder name that you want to appear on +In the **Folder name** field enter the folder name that you want to appear on your Nextcloud Files page. -In the **Configuration** field enter the full filepath of the directory you +In the **Configuration** field enter the full filepath of the directory you want to mount. -In the **Available for** field enter the users or groups who have permission to +In the **Available for** field enter the users or groups who have permission to access the mount. By default all users have access. .. figure:: images/local.png -See :doc:`../external_storage_configuration_gui` for additional mount +See :doc:`../external_storage_configuration_gui` for additional mount options and information. See :doc:`auth_mechanisms` for more information on authentication schemes. diff --git a/admin_manual/configuration_files/external_storage/openstack.rst b/admin_manual/configuration_files/external_storage/openstack.rst index c04bee9b4f6..1b372ea3919 100644 --- a/admin_manual/configuration_files/external_storage/openstack.rst +++ b/admin_manual/configuration_files/external_storage/openstack.rst @@ -2,15 +2,15 @@ OpenStack Object Storage ======================== -OpenStack Object Storage is used to connect to an OpenStack Swift server, or to -Rackspace. Two authentication mechanisms are available: one is the generic -OpenStack mechanism, and the other is used exclusively for Rackspace, a provider +OpenStack Object Storage is used to connect to an OpenStack Swift server, or to +Rackspace. Two authentication mechanisms are available: one is the generic +OpenStack mechanism, and the other is used exclusively for Rackspace, a provider of object storage that uses the OpenStack Swift protocol. The OpenStack authentication mechanism uses the OpenStack Keystone v2 protocol. Your Nextcloud configuration needs: -* **Bucket**. This is user-defined; think of it as a subdirectory of your total +* **Bucket**. This is user-defined; think of it as a subdirectory of your total storage. The bucket will be created if it does not exist. * **Username** of your account. * **Password** of your account. @@ -20,25 +20,25 @@ protocol. Your Nextcloud configuration needs: .. figure:: images/openstack.png :alt: OpenStack configuration. -The Rackspace authentication mechanism requires: +The Rackspace authentication mechanism requires: -* **Bucket** +* **Bucket** * **Username** -* **API key**. +* **API key**. You must also enter the term **cloudFiles** in the **Service name** field. .. figure:: images/rackspace.png :alt: OpenStack configuration. -It may be necessary to specify a **Region**. Your region should be named in -your account information, and you can read about Rackspace regions at +It may be necessary to specify a **Region**. Your region should be named in +your account information, and you can read about Rackspace regions at `About Regions `_. -The timeout of HTTP requests is set in the **Request timeout** field, in +The timeout of HTTP requests is set in the **Request timeout** field, in seconds. -See :doc:`../external_storage_configuration_gui` for additional mount +See :doc:`../external_storage_configuration_gui` for additional mount options and information. See :doc:`auth_mechanisms` for more information on authentication schemes. diff --git a/admin_manual/configuration_files/external_storage/sftp.rst b/admin_manual/configuration_files/external_storage/sftp.rst index e8b5cd8ed93..7f1ce860f8c 100644 --- a/admin_manual/configuration_files/external_storage/sftp.rst +++ b/admin_manual/configuration_files/external_storage/sftp.rst @@ -2,12 +2,12 @@ SFTP ==== -Nextcloud's SFTP (SSH File Transfer Protocol) backend supports both password and -public key authentication. +Nextcloud's SFTP (SSH File Transfer Protocol) backend supports both password and +public key authentication. The **Host** field is required. The default port is 22 (SSH). -For public key authentication, you can generate a public/private key pair from +For public key authentication, you can generate a public/private key pair from your **SFTP with secret key login** configuration. .. figure:: images/auth_mechanism.png @@ -17,10 +17,10 @@ After generating your keys, you need to copy your new public key to the destination server to ``.ssh/authorized_keys``. Nextcloud will then use its private key to authenticate to the SFTP server. -The default **Remote Subfolder** is the root directory (``/``) of the remote +The default **Remote Subfolder** is the root directory (``/``) of the remote SFTP server, and you may enter any directory you wish. -See :doc:`../external_storage_configuration_gui` for additional mount +See :doc:`../external_storage_configuration_gui` for additional mount options and information. See :doc:`auth_mechanisms` for more information on authentication schemes. diff --git a/admin_manual/configuration_files/external_storage/webdav.rst b/admin_manual/configuration_files/external_storage/webdav.rst index b42e4afbdc5..f68415ea096 100644 --- a/admin_manual/configuration_files/external_storage/webdav.rst +++ b/admin_manual/configuration_files/external_storage/webdav.rst @@ -2,7 +2,7 @@ WebDAV ====== -Use this backend to mount a directory from any WebDAV server, or another +Use this backend to mount a directory from any WebDAV server, or another Nextcloud server. You need the following information: @@ -10,7 +10,7 @@ You need the following information: * Folder name: The name of your local mountpoint. * The URL of the WebDAV or Nextcloud server. * Username and password for the remote server -* Secure ``https://``: We always recommend ``https://`` for security, though you can +* Secure ``https://``: We always recommend ``https://`` for security, though you can leave this unchecked for ``http://``. Optionally, a ``Remote Subfolder`` can be specified to change the destination @@ -19,11 +19,11 @@ directory. The default is to use the whole root. .. figure:: images/webdav.png :alt: Webdav configuration form. -.. Note:: CPanel users should install `Web Disk - `_ to enable WebDAV +.. Note:: CPanel users should install `Web Disk + `_ to enable WebDAV functionality. -See :doc:`../external_storage_configuration_gui` for additional mount +See :doc:`../external_storage_configuration_gui` for additional mount options and information. See :doc:`auth_mechanisms` for more information on authentication schemes. diff --git a/admin_manual/configuration_files/external_storage_configuration_gui.rst b/admin_manual/configuration_files/external_storage_configuration_gui.rst index 0529d1a21b4..9113cbad492 100644 --- a/admin_manual/configuration_files/external_storage_configuration_gui.rst +++ b/admin_manual/configuration_files/external_storage_configuration_gui.rst @@ -2,8 +2,8 @@ Configuring External Storage (GUI) ================================== -The External Storage Support application enables you to mount external storage -services and devices as secondary Nextcloud storage devices. You may also allow +The External Storage Support application enables you to mount external storage +services and devices as secondary Nextcloud storage devices. You may also allow users to mount their own external storage services. For configuration of external storages via occ command, see :ref:`occ documentation `. @@ -24,32 +24,32 @@ in the top right and select settings from the dropdown. On the left side under select External Storage. To create a new external storage mount, select an available backend from the -dropdown **Add storage**. Each backend has different required options, which +dropdown **Add storage**. Each backend has different required options, which are configured in the configuration fields. .. figure:: external_storage/images/add_storage.png -Each backend may also accept multiple authentication methods. These are selected -with the dropdown under **Authentication**. Different backends support different -authentication mechanisms; some specific to the backend, others are more -generic. See :doc:`external_storage/auth_mechanisms` for more detailed +Each backend may also accept multiple authentication methods. These are selected +with the dropdown under **Authentication**. Different backends support different +authentication mechanisms; some specific to the backend, others are more +generic. See :doc:`external_storage/auth_mechanisms` for more detailed information. -When you select an authentication mechanism, the configuration fields change as -appropriate for the mechanism. The SFTP backend, for one example, supports -**username and password**, **Log-in credentials, save in session**, and **RSA +When you select an authentication mechanism, the configuration fields change as +appropriate for the mechanism. The SFTP backend, for one example, supports +**username and password**, **Log-in credentials, save in session**, and **RSA public key**. .. figure:: external_storage/images/auth_mechanism.png :alt: An SFTP configuration example. -Required fields are marked with a red border. When all required fields are -filled, the storage is automatically saved. A green dot next to the storage row -indicates the storage is ready for use. A red or yellow icon indicates -that Nextcloud could not connect to the external storage, so you need to +Required fields are marked with a red border. When all required fields are +filled, the storage is automatically saved. A green dot next to the storage row +indicates the storage is ready for use. A red or yellow icon indicates +that Nextcloud could not connect to the external storage, so you need to re-check your configuration and network availability. -If there is an error on the storage, it will be marked as unavailable for ten +If there is an error on the storage, it will be marked as unavailable for ten minutes. To re-check it, click the colored icon or reload your Admin page. Usage of variables for mount paths @@ -62,7 +62,7 @@ Use ``$user`` for automatic substitution with the logged in user's username. Use ``$home`` for automatic substitution with a configurable home directory variable (requires LDAP, see :ref:`LDAP_Special_Attributes` in the LDAP configuration documentation for details) -In the following example, the mount point for a logged in user "alice" would substitute +In the following example, the mount point for a logged in user "alice" would substitute to ``/opt/userDirectories/alice/myPictures``. .. figure:: external_storage/images/externalStorages_variables.png @@ -72,9 +72,9 @@ to ``/opt/userDirectories/alice/myPictures``. User and group permissions -------------------------- -A storage configured in a user's Personal settings is available only to the user -that created it. A storage configured in the Admin settings is available to -all users by default, and it can be restricted to specific users and groups in +A storage configured in a user's Personal settings is available only to the user +that created it. A storage configured in the Admin settings is available to +all users by default, and it can be restricted to specific users and groups in the **Available for** field. .. figure:: external_storage/images/applicable.png @@ -110,8 +110,8 @@ Using self-signed certificates ------------------------------ When using self-signed certificates for external storage mounts the certificate -must be imported into the personal settings of the user. Please refer to -`Nextcloud HTTPS External Mount +must be imported into the personal settings of the user. Please refer to +`Nextcloud HTTPS External Mount `_ for more information. @@ -138,9 +138,9 @@ The following backends are provided by the external storages app. Allow users to mount external Storage ------------------------------------- -Check **Enable User External Storage** to allow your users to mount their own -external storage services, and check the backends you want to allow. Beware, as -this allows a user to make potentially arbitrary connections to other services +Check **Enable User External Storage** to allow your users to mount their own +external storage services, and check the backends you want to allow. Beware, as +this allows a user to make potentially arbitrary connections to other services on your network! .. figure:: external_storage/images/user_mounts.png diff --git a/admin_manual/configuration_files/federated_cloud_sharing_configuration.rst b/admin_manual/configuration_files/federated_cloud_sharing_configuration.rst index 299a25a76d6..a571784f90b 100644 --- a/admin_manual/configuration_files/federated_cloud_sharing_configuration.rst +++ b/admin_manual/configuration_files/federated_cloud_sharing_configuration.rst @@ -2,44 +2,44 @@ Configuring Federation Sharing ============================== -Federated Cloud Sharing is now managed by the Federation app (9.0+), and is -now called Federation sharing. When you enable the Federation app you can -easily and securely link file shares between Nextcloud servers, in effect +Federated Cloud Sharing is now managed by the Federation app (9.0+), and is +now called Federation sharing. When you enable the Federation app you can +easily and securely link file shares between Nextcloud servers, in effect creating a cloud of Nextclouds. - -.. _label-direct-share-link: - + +.. _label-direct-share-link: + Creating a new Federation Share ------------------------------- -Follow these steps to create a new Federation share between two Nextcloud -servers. This requires no action by the user on the remote server; all it takes +Follow these steps to create a new Federation share between two Nextcloud +servers. This requires no action by the user on the remote server; all it takes is a few steps on the originating server. 1. Enable the Federation app. -2. Go to your Nextcloud Admin page and scroll to the Sharing - section. Verify that **Allow users on this server to send shares to other - servers** and **Allow users on this server to receive shares from other - servers** are enabled. +2. Go to your Nextcloud Admin page and scroll to the Sharing + section. Verify that **Allow users on this server to send shares to other + servers** and **Allow users on this server to receive shares from other + servers** are enabled. 3. Now go to the Federation section. The Federation app supports creating a - list of trusted Nextcloud servers, which allows the trusted servers to - exchange user directories and auto-complete the names of external users when + list of trusted Nextcloud servers, which allows the trusted servers to + exchange user directories and auto-complete the names of external users when you create shares. .. figure:: images/federation-0.png - -4. Now go to your Files page and select a folder to share. Click the share - icon, and then enter the username and URL of the user on the remote Nextcloud - server. In this example, that is ``freda@https://example.com/nextcloud``. - When Nextcloud verifies the link, it displays it with the **(remote)** label. + +4. Now go to your Files page and select a folder to share. Click the share + icon, and then enter the username and URL of the user on the remote Nextcloud + server. In this example, that is ``freda@https://example.com/nextcloud``. + When Nextcloud verifies the link, it displays it with the **(remote)** label. Click on this label to establish the link. .. figure:: images/federation-2.png -5. When the link is successfully completed, you have a single share option, +5. When the link is successfully completed, you have a single share option, and that is **can edit**. .. figure:: images/federation-3.png @@ -49,19 +49,19 @@ You may disconnect the share at any time by clicking the trash can icon. Configuring trusted Nextcloud servers ------------------------------------- -You may create a list of trusted Nextcloud servers for Federation sharing. This -allows your linked Nextcloud servers to share user directories, and to auto-fill +You may create a list of trusted Nextcloud servers for Federation sharing. This +allows your linked Nextcloud servers to share user directories, and to auto-fill user names in share dialogs. -You may also enter Nextcloud server URLs in the **Add Nextcloud Server** field. +You may also enter Nextcloud server URLs in the **Add Nextcloud Server** field. -A red light means the connection failed. The yellow light indicates a successful -connection, with no user names exchanged. The green light indicates a successful -connection with user names exchanged. +A red light means the connection failed. The yellow light indicates a successful +connection, with no user names exchanged. The green light indicates a successful +connection with user names exchanged. The prerequisiste for a green status is that the trusted servers were maintained -in both interacting Nextcloud servers. -Additionally ``occ federation:sync-addressbooks`` must have been executed (part of +in both interacting Nextcloud servers. +Additionally ``occ federation:sync-addressbooks`` must have been executed (part of cron job list). The delay to execute the cron is based on local configuration of the cron frequency. @@ -72,58 +72,58 @@ the cron frequency. Creating Federation Shares via public Link Share ------------------------------------------------ -Check the ``Share link`` entry to expose more sharing options (which are -described more fully in :doc:`file_sharing_configuration`). You may create a -Federation share by allowing Nextcloud to create a public link for you, and then +Check the ``Share link`` entry to expose more sharing options (which are +described more fully in :doc:`file_sharing_configuration`). You may create a +Federation share by allowing Nextcloud to create a public link for you, and then email it to the person you want to create the share with. .. figure:: images/create_public_share-6.png - -You may optionally set a password and expiration date on it. When your recipient -receives your email they must click the link, or copy it to a Web -browser. They will see a page displaying a thumbnail of the file, with a button + +You may optionally set a password and expiration date on it. When your recipient +receives your email they must click the link, or copy it to a Web +browser. They will see a page displaying a thumbnail of the file, with a button to **Add to your Nextcloud**. .. figure:: images/create_public_share-8.png -Your recipient should click the **Add to your Nextcloud** button. On the next -screen your recipient needs to enter the URL to their Nextcloud +Your recipient should click the **Add to your Nextcloud** button. On the next +screen your recipient needs to enter the URL to their Nextcloud server, and then press the return key. .. figure:: images/create_public_share-9.png -Your recipient has to take one more step, and that is to confirm creating the +Your recipient has to take one more step, and that is to confirm creating the federated cloud share link by clicking the **Accept** button. .. figure:: images/create_public_share-10.png -Un-check the ``Share link`` checkbox to disable any federated cloud share +Un-check the ``Share link`` checkbox to disable any federated cloud share created this way. Configuration tips ------------------ -The Sharing section on your Admin page allows you to control how your users +The Sharing section on your Admin page allows you to control how your users manage federated cloud shares: * Check ``Enforce password protection`` to require passwords on link shares. -* Check ``Set default expiration date`` to require an expiration date on link +* Check ``Set default expiration date`` to require an expiration date on link shares. * Check ``Allow public uploads`` to allow two-way file sharing. * If you encounter timeouts for downloading or uploading large files, you can use the option ``davstorage.request_timeout`` in your ``config.php`` to increase the timeout. The default value is 30 seconds. -Your Apache Web server must have ``mod_rewrite`` enabled, and you must have -``trusted_domains`` correctly configured in ``config.php`` to allow external -connections (see :doc:`../installation/installation_wizard`). Consider also +Your Apache Web server must have ``mod_rewrite`` enabled, and you must have +``trusted_domains`` correctly configured in ``config.php`` to allow external +connections (see :doc:`../installation/installation_wizard`). Consider also enabling SSL to encrypt all traffic between your servers . -Your Nextcloud server creates the share link from the URL that you used to log -into the server, so make sure that you log into your server using a URL that is -accessible to your users. For example, if you log in via its LAN IP address, -such as ``http://192.168.10.50``, then your share URL will be something like -``http://192.168.10.50/nextcloud/index.php/s/jWfCfTVztGlWTJe``, which is not -accessible outside of your LAN. This also applies to using the server name; for -access outside of your LAN you need to use a fully-qualified domain name such as +Your Nextcloud server creates the share link from the URL that you used to log +into the server, so make sure that you log into your server using a URL that is +accessible to your users. For example, if you log in via its LAN IP address, +such as ``http://192.168.10.50``, then your share URL will be something like +``http://192.168.10.50/nextcloud/index.php/s/jWfCfTVztGlWTJe``, which is not +accessible outside of your LAN. This also applies to using the server name; for +access outside of your LAN you need to use a fully-qualified domain name such as ``http://myserver.example.com``, rather than ``http://myserver``. .. _federated_shares_display: diff --git a/admin_manual/configuration_files/file_versioning.rst b/admin_manual/configuration_files/file_versioning.rst index 1442ae67af5..9d086086ca0 100644 --- a/admin_manual/configuration_files/file_versioning.rst +++ b/admin_manual/configuration_files/file_versioning.rst @@ -2,8 +2,8 @@ Controlling file versions and aging =================================== -The Versions app (files_versions) expires old file versions automatically to -ensure that users don't exceed their storage quotas. This is the default +The Versions app (files_versions) expires old file versions automatically to +ensure that users don't exceed their storage quotas. This is the default pattern used to delete old versions: * For the first second we keep one version @@ -14,11 +14,11 @@ pattern used to delete old versions: * For the first 30 days Nextcloud keeps one version every day * After the first 30 days Nextcloud keeps one version every week -The versions are adjusted along this pattern every time a new version is +The versions are adjusted along this pattern every time a new version is created. Nextcloud will always keep the latest version in each of the time windows. -The Versions app never uses more than 50% of the user's currently available -free space. If the stored versions exceed this limit, Nextcloud deletes the +The Versions app never uses more than 50% of the user's currently available +free space. If the stored versions exceed this limit, Nextcloud deletes the oldest file versions until it meets the disk space limit again. Nextcloud manages file versions using a combination of on-save pruning and scheduled cleanup. This ensures that versions are retained while respecting storage quotas. @@ -37,7 +37,7 @@ When an outdated or orphaned version is found, it is safely deleted from both th .. note:: Versions named by a user will never be deleted. -You may alter the default pattern in ``config.php``. The default setting is +You may alter the default pattern in ``config.php``. The default setting is ``auto``, which sets the default pattern:: 'versions_retention_obligation' => 'auto', @@ -51,8 +51,8 @@ Additional options are: * ``auto, D`` Delete all versions that are older than D days automatically, delete other versions according to expiration rules - -* ``D1, D2`` + +* ``D1, D2`` Keep versions for at least D1 days and delete when they exceed D2 days. * `disabled` @@ -63,7 +63,7 @@ Additional options are: Background job -------------- -To delete expired versions a background jobs runs every 30 minutes. +To delete expired versions a background jobs runs every 30 minutes. It's possible to deactivate the background job and setup a (system) cron to expire the versions via occ. Deactivate background job: ``occ config:app:set --value=no files_versions background_job_expire_versions`` diff --git a/admin_manual/configuration_files/previews_configuration.rst b/admin_manual/configuration_files/previews_configuration.rst index e886ff31c06..dfe565057c6 100644 --- a/admin_manual/configuration_files/previews_configuration.rst +++ b/admin_manual/configuration_files/previews_configuration.rst @@ -2,7 +2,7 @@ Previews configuration ====================== -The Nextcloud thumbnail system generates previews of files for all +The Nextcloud thumbnail system generates previews of files for all Nextcloud apps that display files, such as Files and Gallery. The following image shows some examples of previews of various file types. @@ -17,18 +17,18 @@ By default, Nextcloud can generate previews for the following filetypes: .. note:: Nextcloud can also generate previews of other file types (such as PDF, SVG, various Office document formats, and various video formats). Due to security and - performance concerns those providers are disabled by default. While those providers - are still available, we discourage enabling them and they are considered unsupported. - The full list of the preview providers that are enabled by default (as well as those - disabled by default) can be found under the ``enabledPreviewProviders`` + performance concerns those providers are disabled by default. While those providers + are still available, we discourage enabling them and they are considered unsupported. + The full list of the preview providers that are enabled by default (as well as those + disabled by default) can be found under the ``enabledPreviewProviders`` :doc:`configuration parameter `. Parameters ---------- -Please notice that the Nextcloud preview system comes already with sensible -defaults, and therefore it is usually unnecessary to adjust those configuration -values. +Please notice that the Nextcloud preview system comes already with sensible +defaults, and therefore it is usually unnecessary to adjust those configuration +values. But deemed necessary, following changes have to be made in ``config/config.php`` file. As a best practice, take a backup of this config file before making a lot of changes. @@ -38,10 +38,10 @@ See :ref:`occ_cleanup_previews` to learn more. Disabling previews: ^^^^^^^^^^^^^^^^^^^ -Under certain circumstances, for example if the server has limited -resources, you might want to consider disabling the generation of previews. -Note that if you do this all previews in all apps are disabled, including -the Gallery app, and will display generic icons instead of +Under certain circumstances, for example if the server has limited +resources, you might want to consider disabling the generation of previews. +Note that if you do this all previews in all apps are disabled, including +the Gallery app, and will display generic icons instead of thumbnails. Set the configuration option ``enable_previews`` to ``false``: @@ -77,8 +77,8 @@ to a maximum size of 100×100px: Maximum scale factor: ^^^^^^^^^^^^^^^^^^^^^ -If a lot of small pictures are stored on the Nextcloud instance and the preview -system generates blurry previews, you might want to consider setting a maximum +If a lot of small pictures are stored on the Nextcloud instance and the preview +system generates blurry previews, you might want to consider setting a maximum scale factor. By default, pictures are upscaled to 10 times the original size: :: @@ -93,7 +93,7 @@ If you want to disable scaling at all, you can set the config value to '1': 1, -If you want to disable the maximum scaling factor, you can set the config value +If you want to disable the maximum scaling factor, you can set the config value to 'null': :: @@ -106,7 +106,7 @@ JPEG quality setting: Default JPEG quality setting for preview images is '80'. Change this with: -:: +:: occ config:app:set preview jpeg_quality --value="60" diff --git a/admin_manual/configuration_files/primary_storage.rst b/admin_manual/configuration_files/primary_storage.rst index e2d1b1dadc0..83b2f517560 100644 --- a/admin_manual/configuration_files/primary_storage.rst +++ b/admin_manual/configuration_files/primary_storage.rst @@ -16,26 +16,26 @@ Differences from External Storage --------------------------------- When an object store is used as Primary Storage, Nextcloud requires exclusive access -over the bucket being used. All metadata (filenames, directory structures, etc) -is stored in Nextcloud and not in the object store. The metadata is only stored in the database and the +over the bucket being used. All metadata (filenames, directory structures, etc) +is stored in Nextcloud and not in the object store. The metadata is only stored in the database and the object store only holds the file content by unique identifier. ~~~~~~~~~~~~~~~~~~~~~~~~ Performance Implications ~~~~~~~~~~~~~~~~~~~~~~~~ -Because of this, object stores configured as Primary Storage usually perform better than -when using the same object store via the External Storage support application, but the downside -is being unable to access the files from outside of Nextcloud. This makes using an object store +Because of this, object stores configured as Primary Storage usually perform better than +when using the same object store via the External Storage support application, but the downside +is being unable to access the files from outside of Nextcloud. This makes using an object store as Primary Storage distinct from using an object store via External Storage. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Data Backup and Recovery Implications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -One impact of using an object store as Primary Storage is that your data backup strategy -needs to incorporate this. **Your data is no longer stored on your Nextcloud server, but your -files are also no longer accessible by simply bypassing your Nextcloud server and accessing +One impact of using an object store as Primary Storage is that your data backup strategy +needs to incorporate this. **Your data is no longer stored on your Nextcloud server, but your +files are also no longer accessible by simply bypassing your Nextcloud server and accessing your object store directly.** ------------- @@ -46,18 +46,18 @@ Primary object stores need to be configured in :code:`config.php` by specifying the objectstore backend and any backend specific configuration. .. note:: Configuring a primary object store on an existing Nextcloud instance will - make all existing files on the instance inaccessible. + make all existing files on the instance inaccessible. The configuration has the following structure: :: - 'objectstore' => [ - 'class' => 'Object\\Storage\\Backend\\Class', - 'arguments' => [ - ... - ], - ], + 'objectstore' => [ + 'class' => 'Object\\Storage\\Backend\\Class', + 'arguments' => [ + ... + ], + ], ~~~~~~~~~~~~~~~ OpenStack Swift @@ -74,54 +74,54 @@ V2 Authentication: :: - 'objectstore' => [ - 'class' => '\\OC\\Files\\ObjectStore\\Swift', - 'arguments' => [ - 'username' => 'username', - 'password' => 'Secr3tPaSSWoRdt7', - // the container to store the data in - 'bucket' => 'nextcloud', - 'autocreate' => true, - 'region' => 'RegionOne', - // The Identity / Keystone endpoint - 'url' => 'http://example.com/v2.0', - // optional on some swift implementations - 'tenantName' => 'username', - 'serviceName' => 'swift', - // The Interface / url Type, optional - 'urlType' => 'internal' - ], - ], + 'objectstore' => [ + 'class' => '\\OC\\Files\\ObjectStore\\Swift', + 'arguments' => [ + 'username' => 'username', + 'password' => 'Secr3tPaSSWoRdt7', + // the container to store the data in + 'bucket' => 'nextcloud', + 'autocreate' => true, + 'region' => 'RegionOne', + // The Identity / Keystone endpoint + 'url' => 'http://example.com/v2.0', + // optional on some swift implementations + 'tenantName' => 'username', + 'serviceName' => 'swift', + // The Interface / url Type, optional + 'urlType' => 'internal' + ], + ], V3 Authentication: :: - 'objectstore' => [ - 'class' => 'OC\\Files\\ObjectStore\\Swift', - 'arguments' => [ - 'autocreate' => true, - 'user' => [ - 'name' => 'UserName', - 'password' => 'Secr3tPaSSWoRdt7', - 'domain' => [ - 'name' => 'Default', - ], - ], - 'scope' => [ - 'project' => [ - 'name' => 'TenantName', - 'domain' => [ - 'name' => 'Default', - ], - ], - ], - 'serviceName' => 'swift', - 'region' => 'regionOne', - 'url' => 'http://example.com/v3', - 'bucket' => 'nextcloud', - ], - ], + 'objectstore' => [ + 'class' => 'OC\\Files\\ObjectStore\\Swift', + 'arguments' => [ + 'autocreate' => true, + 'user' => [ + 'name' => 'UserName', + 'password' => 'Secr3tPaSSWoRdt7', + 'domain' => [ + 'name' => 'Default', + ], + ], + 'scope' => [ + 'project' => [ + 'name' => 'TenantName', + 'domain' => [ + 'name' => 'Default', + ], + ], + ], + 'serviceName' => 'swift', + 'region' => 'regionOne', + 'url' => 'http://example.com/v3', + 'bucket' => 'nextcloud', + ], + ], ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Simple Storage Service (S3) @@ -137,32 +137,32 @@ Amazon-hosted S3: :: - 'objectstore' => [ - 'class' => '\\OC\\Files\\ObjectStore\\S3', - 'arguments' => [ - 'bucket' => 'my-nextcloud-store', - 'region' => 'us-east-1', - 'key' => 'EJ39ITYZEUH5BGWDRUFY', - 'secret' => 'M5MrXTRjkyMaxXPe2FRXMTfTfbKEnZCu+7uRTVSj', - ], - ], + 'objectstore' => [ + 'class' => '\\OC\\Files\\ObjectStore\\S3', + 'arguments' => [ + 'bucket' => 'my-nextcloud-store', + 'region' => 'us-east-1', + 'key' => 'EJ39ITYZEUH5BGWDRUFY', + 'secret' => 'M5MrXTRjkyMaxXPe2FRXMTfTfbKEnZCu+7uRTVSj', + ], + ], Non-Amazon hosted S3: :: - 'objectstore' => [ - 'class' => '\\OC\\Files\\ObjectStore\\S3', - 'arguments' => [ - 'bucket' => 'my-nextcloud-store', - 'hostname' => 's3.example.com', - 'key' => 'EJ39ITYZEUH5BGWDRUFY', - 'secret' => 'M5MrXTRjkyMaxXPe2FRXMTfTfbKEnZCu+7uRTVSj', - 'port' => 8443, - // required for some non-Amazon S3 implementations - 'use_path_style' => true, - ], - ], + 'objectstore' => [ + 'class' => '\\OC\\Files\\ObjectStore\\S3', + 'arguments' => [ + 'bucket' => 'my-nextcloud-store', + 'hostname' => 's3.example.com', + 'key' => 'EJ39ITYZEUH5BGWDRUFY', + 'secret' => 'M5MrXTRjkyMaxXPe2FRXMTfTfbKEnZCu+7uRTVSj', + 'port' => 8443, + // required for some non-Amazon S3 implementations + 'use_path_style' => true, + ], + ], Minimum required parameters are: @@ -170,11 +170,11 @@ Minimum required parameters are: * :code:`key` * :code:`secret` -.. note:: You will *probably* need to specify additional parameters beyond these, unless the default - values (see below) exactly match your situation. In particular, your :code:`region` (if Amazon - hosted) or :code:`hostname` (if non-Amazon hosted). +.. note:: You will *probably* need to specify additional parameters beyond these, unless the default + values (see below) exactly match your situation. In particular, your :code:`region` (if Amazon + hosted) or :code:`hostname` (if non-Amazon hosted). -Optional parameters most commonly needing adjustment (and their defaults values if left +Optional parameters most commonly needing adjustment (and their defaults values if left unconfigured): * :code:`region` defaults to :code:`eu-west-1` @@ -204,16 +204,16 @@ Optional parameters less commonly needing adjustment: * :code:`version` defaults to :code:`latest` * :code:`verify_bucket_exists` defaults to :code:`true` [Note: Setting this to :code:`false` *after* confirming the bucket has been created may provide a performance benefit, but may not be possible in multibucket scenarios.] -**If you are using Amazon S3:** the :code:`region` parameter is required unless you're happy with -the default of :code:`eu-west-1`. There is no need to override the :code:`hostname` or :code:`port`. -And :code:`storageClass` only needs to be modified if you're using a different configuration at AWS. -Lastly, :code:`use_path_style` is rarely required with Amazon, but some legacy Amazon datacenters +**If you are using Amazon S3:** the :code:`region` parameter is required unless you're happy with +the default of :code:`eu-west-1`. There is no need to override the :code:`hostname` or :code:`port`. +And :code:`storageClass` only needs to be modified if you're using a different configuration at AWS. +Lastly, :code:`use_path_style` is rarely required with Amazon, but some legacy Amazon datacenters may require it. -**If you using a non-Amazon hosted S3 store:** you will need to set the :code:`hostname` -parameter (and can ignore the :code:`region` parameter). You may need to use :code:`use_path_style` +**If you using a non-Amazon hosted S3 store:** you will need to set the :code:`hostname` +parameter (and can ignore the :code:`region` parameter). You may need to use :code:`use_path_style` if your non-Amazon S3 store does *not* support requests like :code:`https://bucket.hostname.domain/`. -Setting :code:`use_path_style` to true configures the S3 client to make requests like +Setting :code:`use_path_style` to true configures the S3 client to make requests like :code:`https://hostname.domain/bucket` instead. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -227,15 +227,15 @@ The class to be used is :code:`\\OC\\Files\\ObjectStore\\Azure` :: - 'objectstore' => [ - 'class' => '\\OC\\Files\\ObjectStore\\Azure', - 'arguments' => [ - 'container' => 'nextcloud', - 'autocreate' => true, - 'account_name' => 'account_name', - 'account_key' => 'xxxxxxxxxx' - ], - ], + 'objectstore' => [ + 'class' => '\\OC\\Files\\ObjectStore\\Azure', + 'arguments' => [ + 'container' => 'nextcloud', + 'autocreate' => true, + 'account_name' => 'account_name', + 'account_key' => 'xxxxxxxxxx' + ], + ], ------------------------ Multibucket Object Store @@ -249,17 +249,17 @@ configuration in :code:`config.php`: :: - 'objectstore' => [ - 'class' => 'Object\\Storage\\Backend\\Class', - 'arguments' => [ - 'multibucket' => true, - // optional, defaults to 64 - 'num_buckets' => 64, - // will be postfixed by an integer in the range from 0 to (num_nuckets-1) - 'bucket' => 'nextcloud_', - ... - ], - ], + 'objectstore' => [ + 'class' => 'Object\\Storage\\Backend\\Class', + 'arguments' => [ + 'multibucket' => true, + // optional, defaults to 64 + 'num_buckets' => 64, + // will be postfixed by an integer in the range from 0 to (num_nuckets-1) + 'bucket' => 'nextcloud_', + ... + ], + ], Multibucket object store backend maps every user to a range of buckets and saves all files for that user in their corresponding bucket. @@ -279,27 +279,27 @@ When using an Object Store with :code:`'multibucket => true'` it is possible to :: - 'objectstore' => [ - 'class' => 'Object\\Storage\\Backend\\Class', - 'arguments' => [ - 'multibucket' => true, - 'bucket' => 'nextcloud_', - 'perBucket' => [ - 'nextcloud_1' => [ - 'port' => 9999, - ], - ], - ], - ], + 'objectstore' => [ + 'class' => 'Object\\Storage\\Backend\\Class', + 'arguments' => [ + 'multibucket' => true, + 'bucket' => 'nextcloud_', + 'perBucket' => [ + 'nextcloud_1' => [ + 'port' => 9999, + ], + ], + ], + ], This can be useful for example if you want to configure credentials per bucket that is used by a Team folder. A script for provisioning new Team folders this way could look like this (first make sure the bucket exists with those credentials): :: - occ config:system:set --type=string --value=KEYVALUE objectstore arguments perBucket BUCKETNAME key - occ config:system:set --type=string --value=SECRETVALUE objectstore arguments perBucket BUCKETNAME secret - occ groupfolders:create --bucket BUCKETNAME TEAMFOLDERNAME + occ config:system:set --type=string --value=KEYVALUE objectstore arguments perBucket BUCKETNAME key + occ config:system:set --type=string --value=SECRETVALUE objectstore arguments perBucket BUCKETNAME secret + occ groupfolders:create --bucket BUCKETNAME TEAMFOLDERNAME The credentials must be set before the new Team folder is created. @@ -316,27 +316,27 @@ configuration to use for newly created users: :: - 'objectstore' => [ - 'default' => 'server2', - 'root' => 'server1', - 'server1' => [ - 'class' => 'Object\\Storage\\Backend\\Class', - 'arguments' => [ - 'hostname' => 's3-server1.example.com', - 'bucket' => 's1_nextcloud', - ... - ], - ], - 'server2' => [ - 'class' => 'Object\\Storage\\Backend\\Class', - 'arguments' => [ - 'multibucket' => true, - 'hostname' => 's3-server2.example.com', - 'bucket' => 's2_nextcloud_', - ... - ], - ], - ], + 'objectstore' => [ + 'default' => 'server2', + 'root' => 'server1', + 'server1' => [ + 'class' => 'Object\\Storage\\Backend\\Class', + 'arguments' => [ + 'hostname' => 's3-server1.example.com', + 'bucket' => 's1_nextcloud', + ... + ], + ], + 'server2' => [ + 'class' => 'Object\\Storage\\Backend\\Class', + 'arguments' => [ + 'multibucket' => true, + 'hostname' => 's3-server2.example.com', + 'bucket' => 's2_nextcloud_', + ... + ], + ], + ], .. note:: Bucket names must be unique between all configured object store instances. @@ -364,28 +364,28 @@ The key can be specified with the :code:`sse_c_key` parameter which needs to be :: - openssl rand 32 | base64 + openssl rand 32 | base64 The following example shows how to configure the S3 object store with SSE-C encryption support in the objectstore section of the Nextcloud config.php file: :: - 'objectstore' => [ - array ( - 'class' => 'OC\\Files\\ObjectStore\\S3', - 'arguments' => - array ( - 'bucket' => 'nextcloud', - 'key' => 'nextcloud', - 'secret' => 'nextcloud', - 'hostname' => 's3', - 'port' => '443', - 'use_ssl' => true, - 'use_path_style' => true, - 'autocreate' => true, - 'verify_bucket_exists' => true, - 'sse_c_key' => 'o9d3Q9tHcPMv6TIpH53MSXaUmY91YheZRwuIhwCFRSs=', - ), - ); - ], + 'objectstore' => [ + array ( + 'class' => 'OC\\Files\\ObjectStore\\S3', + 'arguments' => + array ( + 'bucket' => 'nextcloud', + 'key' => 'nextcloud', + 'secret' => 'nextcloud', + 'hostname' => 's3', + 'port' => '443', + 'use_ssl' => true, + 'use_path_style' => true, + 'autocreate' => true, + 'verify_bucket_exists' => true, + 'sse_c_key' => 'o9d3Q9tHcPMv6TIpH53MSXaUmY91YheZRwuIhwCFRSs=', + ), + ); + ], diff --git a/admin_manual/configuration_files/windows_compatible_filenames.rst b/admin_manual/configuration_files/windows_compatible_filenames.rst index b43923feb29..f2299eb42e0 100644 --- a/admin_manual/configuration_files/windows_compatible_filenames.rst +++ b/admin_manual/configuration_files/windows_compatible_filenames.rst @@ -22,8 +22,8 @@ or filenames like ``AUX.txt`` (on Windows ``AUX`` is a reserved name and cannot .. note:: - Enabling this setting will not enforce case-insensitivity - as modern Windows systems support case-sensitive filenames. + Enabling this setting will not enforce case-insensitivity + as modern Windows systems support case-sensitive filenames. Enabling Windows compatible filenames ------------------------------------- @@ -33,9 +33,9 @@ or by using an ``occ`` command. .. note:: - This feature works by setting a predefined set of system configuration settings. - So after enabling this the ``config.php`` will be adjusted, which also means enabling - this feature requires a writable configuration. + This feature works by setting a predefined set of system configuration settings. + So after enabling this the ``config.php`` will be adjusted, which also means enabling + this feature requires a writable configuration. Using the web interface ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/admin_manual/configuration_mimetypes/index.rst b/admin_manual/configuration_mimetypes/index.rst index aab6db1ea3d..91d7a4d17d3 100644 --- a/admin_manual/configuration_mimetypes/index.rst +++ b/admin_manual/configuration_mimetypes/index.rst @@ -5,26 +5,26 @@ Mimetypes management Mimetype aliases ---------------- -Nextcloud allows you to create aliases for mimetypes, so that you can display -custom icons for files. For example, you might want a nice audio icon for audio +Nextcloud allows you to create aliases for mimetypes, so that you can display +custom icons for files. For example, you might want a nice audio icon for audio files instead of the default file icon. -By default Nextcloud is distributed with +By default Nextcloud is distributed with ``nextcloud/resources/config/mimetypealiases.dist.json``. -Do not modify this file, as it will be replaced when Nextcloud is updated. -Instead, create your own ``nextcloud/config/mimetypealiases.json`` -file with your custom aliases. Use the same syntax as in +Do not modify this file, as it will be replaced when Nextcloud is updated. +Instead, create your own ``nextcloud/config/mimetypealiases.json`` +file with your custom aliases. Use the same syntax as in ``nextcloud/resources/config/mimetypealiases.dist.json``. -Once you have made changes to your ``mimetypealiases.json``, use the ``occ`` -command to propagate the changes through the system. This example is for +Once you have made changes to your ``mimetypealiases.json``, use the ``occ`` +command to propagate the changes through the system. This example is for Ubuntu Linux:: $ sudo -E -u www-data php occ maintenance:mimetype:update-js # you may also need to update the mimetype for existing files, see nextcloud/server#30566 $ sudo -E -u www-data php occ maintenance:mimetype:update-db --repair-filecache - + See :doc:`../occ_command` to learn more about ``occ``. Some common mimetypes that may be useful in creating aliases are: @@ -57,14 +57,14 @@ Mimetype mapping ---------------- Nextcloud allows administrators to specify the mapping of a file extension to a -mimetype. For example files ending in ``mp3`` map to ``audio/mpeg``. Which +mimetype. For example files ending in ``mp3`` map to ``audio/mpeg``. Which then in turn allows Nextcloud to show the audio icon. By default Nextcloud comes with ``mimetypemapping.dist.json``. This is a simple json array. Administrators should not update this file as it will get replaced on upgrades of Nextcloud. Instead the file ``mimetypemapping.json`` should be created and -modified, this file has precedence over the shipped file. +modified, this file has precedence over the shipped file. Icon retrieval -------------- diff --git a/admin_manual/configuration_server/activity_configuration.rst b/admin_manual/configuration_server/activity_configuration.rst index 121ea5d084e..4ea344850b3 100644 --- a/admin_manual/configuration_server/activity_configuration.rst +++ b/admin_manual/configuration_server/activity_configuration.rst @@ -75,9 +75,9 @@ If you want to manually send out all activity emails which are queued, you can r Excluding users from the activity expiration -------------------------------------------- -For certain users, it might make sense to never expire their activity data, for example +For certain users, it might make sense to never expire their activity data, for example administrators. -You can set the config value `activity_expire_exclude_users` in your Nextcloud config to +You can set the config value `activity_expire_exclude_users` in your Nextcloud config to exclude these users from expiration:: 'activity_expire_exclude_users' => [ diff --git a/admin_manual/configuration_server/android_deep_link_handling.rst b/admin_manual/configuration_server/android_deep_link_handling.rst index 4f9abcfc7ab..76b092eb41e 100644 --- a/admin_manual/configuration_server/android_deep_link_handling.rst +++ b/admin_manual/configuration_server/android_deep_link_handling.rst @@ -2,25 +2,25 @@ Android Deep Link Handling ========================== -Deep linking in Android allows your application to be launched directly from a URL, -making it easier for users to navigate to specific content within your app. -Starting from Android 12, handling deep links requires additional configuration +Deep linking in Android allows your application to be launched directly from a URL, +making it easier for users to navigate to specific content within your app. +Starting from Android 12, handling deep links requires additional configuration using an ``assetlinks.json`` file to ensure the app and the host domain are properly associated. Android 11 and Below -------------------- -For Android 11 and below, deep linking is straightforward and does not require additional +For Android 11 and below, deep linking is straightforward and does not require additional configuration beyond the usual manifest settings. Android 12 and Above -------------------- -For Android 12 and above, an additional configuration step is required to verify the +For Android 12 and above, an additional configuration step is required to verify the relationship between your app and the host domain using the ``assetlinks.json`` file. Creating assetlinks.json ~~~~~~~~~~~~~~~~~~~~~~~~ -Create a file named ``assetlinks.json`` and host it in the .well-known directory of +Create a file named ``assetlinks.json`` and host it in the .well-known directory of your website (e.g., https://www.cloud.example.com/.well-known/assetlinks.json). Example ``assetlinks.json``:: @@ -41,7 +41,7 @@ Example ``assetlinks.json``:: Nextcloud Configuration Limitation ================================== Due to the additional requirement of hosting an ``assetlinks.json`` file -for Android 12 and above, Nextcloud cannot configure the Android client +for Android 12 and above, Nextcloud cannot configure the Android client for all different hosts. This is because each host needs its own ``assetlinks.json`` -file to establish a verified relationship with the app, and Nextcloud cannot manage +file to establish a verified relationship with the app, and Nextcloud cannot manage this file for every possible host domain. diff --git a/admin_manual/configuration_server/antivirus_configuration.rst b/admin_manual/configuration_server/antivirus_configuration.rst index 7e4a7fb0c62..ff9871aa3fa 100644 --- a/admin_manual/configuration_server/antivirus_configuration.rst +++ b/admin_manual/configuration_server/antivirus_configuration.rst @@ -82,9 +82,9 @@ Docker, Docker-compose You can mount ClamAV Socket from the Docker Container to the host System as volume. In this case you do not need to expose any port outside of container. For a Docker run this command:: - + docker run --name clamav -d -v /var/run/clamav/:/var/run/clamav/ -v /var/docker/clamav/virus_db/:/var/lib/clamav/ clamav/clamav:stable_base - + For a Docker-compose use following settings:: version: "3.6" @@ -212,7 +212,7 @@ Mark a file as scanned or unscanned :: sudo -E -u www-data php occ files_antivirus:mark - + Files marked as scanned will not be scanned for the next four weeks. Configuring ICAP on Nextcloud diff --git a/admin_manual/configuration_server/automatic_configuration.rst b/admin_manual/configuration_server/automatic_configuration.rst index 6916fda06bd..0daf341c566 100644 --- a/admin_manual/configuration_server/automatic_configuration.rst +++ b/admin_manual/configuration_server/automatic_configuration.rst @@ -3,7 +3,7 @@ Automatic setup =============== If you need to install Nextcloud on multiple servers, you normally do not want -to set up each instance separately as described in +to set up each instance separately as described in :doc:`../configuration_database/linux_database_configuration`. For this reason, Nextcloud provides an automatic configuration feature. @@ -95,8 +95,8 @@ Using the following parameter settings, the "Finish setup" screen requests data "dbtableprefix" => "", ); -.. note:: Keep in mind that the automatic configuration does not eliminate the need for - creating the database user and database in advance, as described in +.. note:: Keep in mind that the automatic configuration does not eliminate the need for + creating the database user and database in advance, as described in :doc:`../configuration_database/linux_database_configuration`. All parameters @@ -119,7 +119,7 @@ Using the following parameter settings, because all parameters are already confi "directory" => "/www/htdocs/nextcloud/data", ); -.. note:: Keep in mind that the automatic configuration does not eliminate the need for - creating the database user and database in advance, as described in +.. note:: Keep in mind that the automatic configuration does not eliminate the need for + creating the database user and database in advance, as described in :doc:`../configuration_database/linux_database_configuration`. - + diff --git a/admin_manual/configuration_server/background_jobs_configuration.rst b/admin_manual/configuration_server/background_jobs_configuration.rst index 526945586bd..dcce976cc56 100644 --- a/admin_manual/configuration_server/background_jobs_configuration.rst +++ b/admin_manual/configuration_server/background_jobs_configuration.rst @@ -35,7 +35,7 @@ A value of 1 e.g. will only run these background jobs between 01:00am UTC and 05 'maintenance_window_start' => 1, -If you don't care when these jobs run, you can set the value to ``100``, but beware that +If you don't care when these jobs run, you can set the value to ``100``, but beware that resource intensive jobs may then run unnecessarily during high usage periods. This may lead to slower performance and a lower quality user experience. diff --git a/admin_manual/configuration_server/bruteforce_configuration.rst b/admin_manual/configuration_server/bruteforce_configuration.rst index d97bdd8383b..d284c792b64 100644 --- a/admin_manual/configuration_server/bruteforce_configuration.rst +++ b/admin_manual/configuration_server/bruteforce_configuration.rst @@ -5,12 +5,12 @@ Brute force protection Introduction ------------ -Nextcloud has built-in protection against brute force attempts. +Nextcloud has built-in protection against brute force attempts. -The brute force protection feature is meant to protect Nextcloud servers from attempts to guess -passwords and tokens in various ways. Besides the obvious "let's try a big list of commonly used -passwords" attack, it also makes it harder to use slightly more sophisticated attacks via the reset -password page or trying to find app password tokens. It is used throughout the Nextcloud ecosystem, +The brute force protection feature is meant to protect Nextcloud servers from attempts to guess +passwords and tokens in various ways. Besides the obvious "let's try a big list of commonly used +passwords" attack, it also makes it harder to use slightly more sophisticated attacks via the reset +password page or trying to find app password tokens. It is used throughout the Nextcloud ecosystem, including by other apps, if they have sensitive entrypoints (and choose to enable support for it). How it works @@ -19,7 +19,7 @@ How it works Overview ~~~~~~~~ -If triggered, brute force protection makes requests - coming from an IP address via a brute +If triggered, brute force protection makes requests - coming from an IP address via a brute force protected entrypoint - slower for up to a 24 hour period. In extreme circumstances it may prevent access outright, for up to 30 minutes, from a problematic IP address. @@ -27,23 +27,23 @@ This protects your system from attackers trying, for example, a lot of different The primary filter is IP address-based. This means that any account - even one associated with a given brute force attempt - is not impacted when it is connecting from a different IP address -than any brute force attempts. This helps minimize inadvertent denial of service attacks against +than any brute force attempts. This helps minimize inadvertent denial of service attacks against legitimate connections, while maximizing attack resistance from problematic IP sources. Nuisance triggers are minimized through reasonable built-in defaults appropriate to each type of action. The attempts history is automatically managed by a daily cronjob. Individual entries -expire after 48 hours (attempts, however, may be still *logged* indefinitely elsewhere through the usual +expire after 48 hours (attempts, however, may be still *logged* indefinitely elsewhere through the usual mechanisms within Nextcloud Server and at the discretion of the admin). -Excluding (whitelisting) select IP addresses from brute force protection to prevent false -positives is supported, but usually false positives are best handled by fixing the underlying causes -(e.g. a misconfigured reverse proxy or misbehaving client). +Excluding (whitelisting) select IP addresses from brute force protection to prevent false +positives is supported, but usually false positives are best handled by fixing the underlying causes +(e.g. a misconfigured reverse proxy or misbehaving client). -.. tip:: If you do notice a problem with the authentication behavior of any the official Nextcloud clients, +.. tip:: If you do notice a problem with the authentication behavior of any the official Nextcloud clients, please report it to the appropriate repository so that it can be looked into. -Keeping brute force protection active and operating properly helps protects your Nextcloud Server from +Keeping brute force protection active and operating properly helps protects your Nextcloud Server from malicious actors while minimizing potential impact on legitimate usage. Example: The login page @@ -55,11 +55,11 @@ will not notice anything. But if you do this a few times you start to notice that the verification of the login is taking longer each time. This is the brute force protection kicking in. -The maximum delay is 25 seconds, unless maximum number of attempts (currently 10) was reached within -the last 30 minutes (in which case a ``429 Too Many Requests`` will be returned until the maximum attempts +The maximum delay is 25 seconds, unless maximum number of attempts (currently 10) was reached within +the last 30 minutes (in which case a ``429 Too Many Requests`` will be returned until the maximum attempts within the recent time has dropped below the threshold). -After a successful login (from the same source IP address), any prior invalid login attempts will be cleared +After a successful login (from the same source IP address), any prior invalid login attempts will be cleared and you will no longer be hit by the delay. .. note:: Not all actions are necessarily viewed the same. It is possible for some activities to be more (or less) strict @@ -71,34 +71,34 @@ Usage Activating ~~~~~~~~~~ -Brute force protection is enabled by default on Nextcloud. Its behavior can be adjusted through the -``bruteforcesettings`` app (shipped with Server and enabled by default), several ``occ`` commands, and several -``config.php`` parameters. Its effectiveness is highly dependent on having a properly configured environment, +Brute force protection is enabled by default on Nextcloud. Its behavior can be adjusted through the +``bruteforcesettings`` app (shipped with Server and enabled by default), several ``occ`` commands, and several +``config.php`` parameters. Its effectiveness is highly dependent on having a properly configured environment, particularly when integrating a reverse proxy with Nextcloud (and associated parameters such as ``trusted_proxies``). The brute force settings app ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This app, which shipped and enabled by default, makes it possible (via the Web UI) to view the status of a +This app, which shipped and enabled by default, makes it possible (via the Web UI) to view the status of a connection and modify certain parameters of the brute force protection built into Nextcloud Server. -The user interface added by this app is found under *Administration settings -> Security* under the *Brute-force +The user interface added by this app is found under *Administration settings -> Security* under the *Brute-force IP whitelist* heading. -Currently an admin can view the status of the IP address they are connecting from as well as specify IPv4 or IPv6 +Currently an admin can view the status of the IP address they are connecting from as well as specify IPv4 or IPv6 addresses and ranges to exempt from brute force protection. -Additional enhancements may be made in the future, within this app and/or in combination with Nextcloud Server for +Additional enhancements may be made in the future, within this app and/or in combination with Nextcloud Server for additional monitoring or behavior adjustments related to brute force protection. -.. warning:: Disabling the ``bruteforcesettings`` app does **not** disable brute force protection +.. warning:: Disabling the ``bruteforcesettings`` app does **not** disable brute force protection - it merely removes your ability to adjust brute force related settings from the Web interface. - + .. danger:: - You would need to adjust the parameter ``auth.bruteforce.protection.enabled`` in your Nextcloud ``config.php`` to - disable brute force protection, which is **heavily discouraged for production servers**, particularly if your - server is reachable via a public IP address. It allows an attacker to iterate over all users and their passwords + You would need to adjust the parameter ``auth.bruteforce.protection.enabled`` in your Nextcloud ``config.php`` to + disable brute force protection, which is **heavily discouraged for production servers**, particularly if your + server is reachable via a public IP address. It allows an attacker to iterate over all users and their passwords as well as two-factor verifications afterwards ultimately leading to admin access. ``occ`` commands @@ -121,9 +121,9 @@ Troubleshooting Overview ~~~~~~~~ -On most setups Nextcloud will work out of the box without any issues. If you run into a situation where -logging in or connecting is often very slow for multiple users, the first step is to check your Nextcloud -Server logs to see what IP addresses are being detected (you will need to adjust your ``loglevel`` to ``1`` +On most setups Nextcloud will work out of the box without any issues. If you run into a situation where +logging in or connecting is often very slow for multiple users, the first step is to check your Nextcloud +Server logs to see what IP addresses are being detected (you will need to adjust your ``loglevel`` to ``1`` temporarily to do so). Look for entries that start with any of the following: @@ -132,8 +132,8 @@ Look for entries that start with any of the following: - `IP address throttled` [...] - `IP address blocked` [...] -If all clients appear to be coming from the same IP address and that IP address happens to be your -proxy, you need to review your ``trusted_proxies`` configuration. +If all clients appear to be coming from the same IP address and that IP address happens to be your +proxy, you need to review your ``trusted_proxies`` configuration. If the IP address is a common connection point, such as a multi-user office location, it can be an option to whitelist it, with the draw back that users have to be trust-worthy. @@ -142,17 +142,17 @@ For testing purposes you want want to whitelist your own IP address to see if th If it does - and assuming your proxy configuration is correct - you may have a client/device in your network that is misbehaving and generating invalid login attempts from your IP address. -You can use the `occ security:bruteforce:attempts` command to check the realtime status for a given IP address. +You can use the `occ security:bruteforce:attempts` command to check the realtime status for a given IP address. -.. note:: The `bruteforce_attempts` database table will be empty if you're using a distributed memory +.. note:: The `bruteforce_attempts` database table will be empty if you're using a distributed memory cache since the database backend is no longer used unless it is the only option available. Excluding IP addresses from brute force protection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: Most nuisance triggering of brute force protection can be resolved through proper configuration of reverse - proxies. In other cases, select IP addresses that need to be whitelisted can be configured within this app (while - leaving brute force protection enabled). This can be useful for testing purposes or when there are a lot of people +.. note:: Most nuisance triggering of brute force protection can be resolved through proper configuration of reverse + proxies. In other cases, select IP addresses that need to be whitelisted can be configured within this app (while + leaving brute force protection enabled). This can be useful for testing purposes or when there are a lot of people (or devices) connecting from a known, single IP address. It's possible to exclude IP addresses from the brute force protection. @@ -163,4 +163,4 @@ It's possible to exclude IP addresses from the brute force protection. .. danger:: Any excluded IP address can perform authentication attempts without any throttling. - It's best to exclude as few IP addresses as you can, or even none at all. + It's best to exclude as few IP addresses as you can, or even none at all. diff --git a/admin_manual/configuration_server/caching_configuration.rst b/admin_manual/configuration_server/caching_configuration.rst index 1346352a772..388e80c6dac 100644 --- a/admin_manual/configuration_server/caching_configuration.rst +++ b/admin_manual/configuration_server/caching_configuration.rst @@ -2,9 +2,9 @@ Memory caching ============== -You can significantly improve your Nextcloud server performance with memory -caching, where frequently-requested objects are stored in memory for faster -retrieval. There are two types of caches to use: a PHP opcode cache, which is +You can significantly improve your Nextcloud server performance with memory +caching, where frequently-requested objects are stored in memory for faster +retrieval. There are two types of caches to use: a PHP opcode cache, which is commonly called *opcache*, and data cache for your web server, commonly called "memcache". @@ -14,8 +14,8 @@ commonly called *opcache*, and data cache for your web server, commonly called distributed cache (``memcache.distributed``) in your ``config.php`` and not a local cache (``memcache.local``) you will still see the cache warning. -A **PHP opcache** stores compiled PHP scripts, so they don't need to be re-compiled -every time they are called. PHP bundles the Zend OPcache in core since version +A **PHP opcache** stores compiled PHP scripts, so they don't need to be re-compiled +every time they are called. PHP bundles the Zend OPcache in core since version 5.5, so you don't need to install an opcache manually. **Data caching** is supplied by the user. Nextcloud supports multiple memory @@ -28,9 +28,9 @@ needs. The supported caching backends are: For local and distributed caching, as well as transactional file locking. * `Memcached `_ For distributed caching. - + Data caches, or memcaches, must be explicitly configured in Nextcloud by installing -and enabling your desired cache, and then adding the appropriate entry to +and enabling your desired cache, and then adding the appropriate entry to ``config.php`` (See :doc:`config_sample_php_parameters` for an overview of all possible config parameters). @@ -38,7 +38,7 @@ all possible config parameters). Recommendations based on type of deployment ------------------------------------------- -You may use both a local and a distributed cache. Recommended caches are APCu +You may use both a local and a distributed cache. Recommended caches are APCu and Redis. After installing and enabling your chosen memcache (data cache), verify that it is active by running :ref:`label-phpinfo`. @@ -113,8 +113,8 @@ Linux distributions. On Red Hat/CentOS/Fedora systems install After restarting your Web server, add this line to your ``config.php`` file:: 'memcache.local' => '\OC\Memcache\APCu', - -Refresh your Nextcloud admin page, and the cache warning should disappear. + +Refresh your Nextcloud admin page, and the cache warning should disappear. Depending on your installation size and the number of users and interactions with the system you may want to adapt the ``apc.shm_size`` setting in your @@ -139,27 +139,27 @@ Redis Redis is an excellent modern memcache to use for distributed caching, and as a key-value store for :doc:`Transactional File Locking -<../configuration_files/files_locking_transactional>` because it guarantees +<../configuration_files/files_locking_transactional>` because it guarantees that cached objects are available for as long as they are needed. The Redis PHP module must be version 2.2.6+. If you are running a Linux -distribution that does not package the supported versions of this module, or +distribution that does not package the supported versions of this module, or does not package Redis at all, see :ref:`install_redis_label`. On Debian/Ubuntu/Mint, install ``redis-server`` and ``php-redis``. The installer -will automatically launch ``redis-server`` and configure it to launch at +will automatically launch ``redis-server`` and configure it to launch at startup. -On CentOS and Fedora, install ``redis`` and ``php-pecl-redis``. It will not -start automatically, so you must use your service manager to start +On CentOS and Fedora, install ``redis`` and ``php-pecl-redis``. It will not +start automatically, so you must use your service manager to start ``redis``, and to launch it at boot as a daemon. - + You can verify that the Redis daemon is running with ``ps ax``:: - + ps ax | grep redis - 22203 ? Ssl 0:00 /usr/bin/redis-server 127.0.0.1:6379 + 22203 ? Ssl 0:00 /usr/bin/redis-server 127.0.0.1:6379 -Restart your Web server, add the appropriate entries to your ``config.php``, and +Restart your Web server, add the appropriate entries to your ``config.php``, and refresh your Nextcloud admin page. Redis configuration in Nextcloud (config.php) @@ -169,11 +169,11 @@ For best performance, use Redis for file locking by adding this:: 'memcache.locking' => '\OC\Memcache\Redis', -Additionally, you should use Redis for the distributed server cache:: +Additionally, you should use Redis for the distributed server cache:: 'memcache.distributed' => '\OC\Memcache\Redis', -Furthermore, you could use Redis for the local cache like so, but it's not recommended (see warning below):: +Furthermore, you could use Redis for the local cache like so, but it's not recommended (see warning below):: 'memcache.local' => '\OC\Memcache\Redis', @@ -218,7 +218,7 @@ The following options are available to configure when using a redis cluster (all 'password' => 'password', 'dbindex' => 0, ], - + .. note:: The port is required as part of the server URL. However, it is not necessary to list all servers: for example, if all servers are load balanced via the same DNS name, only that server name is required. Connecting to single Redis server over TCP @@ -294,7 +294,7 @@ You might need to restart apache and redis for the changes to take effect:: systemctl restart apache2 systemctl restart redis-server -Redis is very configurable; consult `the Redis documentation +Redis is very configurable; consult `the Redis documentation `_ to learn more. Using the Redis session handler @@ -371,6 +371,6 @@ and lists all the servers in the shared cache pool with their port numbers:: Cache Directory location ------------------------ -The cache directory defaults to ``data/$user/cache`` where ``$user`` is the +The cache directory defaults to ``data/$user/cache`` where ``$user`` is the current user. You may use the ``'cache_path'`` directive in ``config.php`` (See :doc:`config_sample_php_parameters`) to select a different location. diff --git a/admin_manual/configuration_server/config_sample_php_parameters.rst b/admin_manual/configuration_server/config_sample_php_parameters.rst index 0f92f055472..de668cf69d5 100644 --- a/admin_manual/configuration_server/config_sample_php_parameters.rst +++ b/admin_manual/configuration_server/config_sample_php_parameters.rst @@ -5,15 +5,15 @@ Configuration Parameters Introduction ------------ -Nextcloud uses ``config/config.php`` as its main configuration file. This file controls -various fundamental aspects of server operations. It is typically modified as part of initial +Nextcloud uses ``config/config.php`` as its main configuration file. This file controls +various fundamental aspects of server operations. It is typically modified as part of initial deployment, when troubleshooting, and when making adjustments to surrounding infrastructure. -This is a required file for all Nextcloud deployments and thus it is critical for Nextcloud +This is a required file for all Nextcloud deployments and thus it is critical for Nextcloud administrators to be familiar with managing it. -This section of the *Administration Manual* documents how to adjust this essential file, -certain special characteristics of the ``config/`` directory, and all of the supported +This section of the *Administration Manual* documents how to adjust this essential file, +certain special characteristics of the ``config/`` directory, and all of the supported parameters that can be specified in a ``config/config.php`` file. .. note:: While ``config/config.php`` is a required file, many Nextcloud or Nextcloud app @@ -23,39 +23,39 @@ parameters that can be specified in a ``config/config.php`` file. Loading ------- -Configuration files located in ``config/`` are parsed automatically when Nextcloud -starts up. They are also checked for changes periodically (approximately every two seconds -in a standard PHP environment running with default *OPcache* settings; approximately every +Configuration files located in ``config/`` are parsed automatically when Nextcloud +starts up. They are also checked for changes periodically (approximately every two seconds +in a standard PHP environment running with default *OPcache* settings; approximately every sixty seconds in many pre-packaged Nextcloud installation methods). -The ``config/config.php`` file may be supplemented by additional ``*.config.php`` files +The ``config/config.php`` file may be supplemented by additional ``*.config.php`` files placed in the ``config/`` directory (if appropriately named and formatted). -.. danger:: Be cautious when naming or creating backup copies of your active +.. danger:: Be cautious when naming or creating backup copies of your active ``config/config.php``. If a backup is located within ``config/`` and is named ``(ANYTHING).config.php``, it will be loaded as part of your live configuration and override your ``config/config.php`` values! -.. tip:: If your configuration changes don't seem to be taking effect, check: (a) your PHP opcache +.. tip:: If your configuration changes don't seem to be taking effect, check: (a) your PHP opcache configuration; (b) for additional ``*.config.php`` files located in ``config/``; (c) the documentation for your Nextcloud installation method/package; (d) the output of ``occ config:list system``. Format ------ -The short answer is that ``config/`` files are plain text files with some special formatting +The short answer is that ``config/`` files are plain text files with some special formatting requirements for different types of parameters and values. This makes it extensible and easy for -Nextcloud to interact with. It also makes it easy for administrators to view with any text viewer +Nextcloud to interact with. It also makes it easy for administrators to view with any text viewer and from the command-line. -Technically these configuration files are PHP files containing a special (to Nextcloud) PHP array -called ``$CONFIG``. This array consists of various Nextcloud specific "key-value" pairs (in some cases +Technically these configuration files are PHP files containing a special (to Nextcloud) PHP array +called ``$CONFIG``. This array consists of various Nextcloud specific "key-value" pairs (in some cases arrays themselves). Each pair has the form ``key => value`` and is comma-separated. Types of Values ^^^^^^^^^^^^^^^ -Strings: +Strings: * ``"thisIsAnImportantValue"`` * Note: These must be either single or double quoted - i.e. ``"string"`` or ``'string'``. @@ -65,7 +65,7 @@ Strings: - ``'versions_retention_obligation' => 'auto, D',`` - ``'logtimezone' => 'Europe/Berlin',`` -Boolean: +Boolean: * ``true`` or ``false`` * Note: These should **not** be surrounded by quote marks within the configuration file itself. @@ -91,19 +91,19 @@ Arrays of any of the above types: - ``'connectivity_check_domains' => [ 'www.nextcloud.com', 'www.eff.org', ],`` - ``'enabledPreviewProviders' => [ 'OC\Preview\BMP', 'OC\Preview\GIF', 'OC\Preview\JPEG', ],`` -.. tip:: Nextcloud attempts to remedy some value type/formatting mistakes, but this is not foolproof. - Use the correct formatting (for the type of value in question) to avoid unexpected results arising +.. tip:: Nextcloud attempts to remedy some value type/formatting mistakes, but this is not foolproof. + Use the correct formatting (for the type of value in question) to avoid unexpected results arising from values being cast in unexpected ways. Modifying --------- -Parameters may be modified in a standard text editor (i.e. via the command-line or externally +Parameters may be modified in a standard text editor (i.e. via the command-line or externally then re-uploaded). They may also, in most cases, be modified using the commands in the ``occ config:system:*`` namespace. .. tip:: Incorrectly formatted ``key => value`` entries (or incorrectly specified values) may - not generate immediate errors or problems (such as parsing / syntax errors), but may still + not generate immediate errors or problems (such as parsing / syntax errors), but may still lead to unexpected and undesirable results. Review your fully parsed (by PHP) configuration by using the command ``occ config:list system`` and/or ``occ config:list system --private`` to identify anything unexpected. @@ -111,42 +111,42 @@ the ``occ config:system:*`` namespace. Defaults -------- -Nextcloud creates a base ``config/config.php`` file at installation time containing the most +Nextcloud creates a base ``config/config.php`` file at installation time containing the most essential parameters for operations. These values are a mixture of auto-generated and drawn from information provided by the administrator at installation time. -The file ``config/config.sample.php`` lists all the parameters within Nextcloud that can be -specified in ``config/`` files, along with example and default values for each. The content of -that sample configuration file is included :ref:`below` for ease of reference +The file ``config/config.sample.php`` lists all the parameters within Nextcloud that can be +specified in ``config/`` files, along with example and default values for each. The content of +that sample configuration file is included :ref:`below` for ease of reference and alongside additional context. -.. tip:: Only add parameters to ``config/config.php`` that you wish to modify. +.. tip:: Only add parameters to ``config/config.php`` that you wish to modify. -.. danger:: Do not copy everything from ``config/config.sample.php`` into your own +.. danger:: Do not copy everything from ``config/config.sample.php`` into your own ``config/config.php``! Besides being unnecessary, it will break things and possibly even require re-installation. Multiple/Merged Configuration Files ----------------------------------- -Nextcloud supports loading configuration parameters from multiple files. You can add arbitrary -files ending with ``.config.php*`` (i.e. ``*.config.php``) in the ``config/`` directory. The values -in these files take precedence over ``config/config.php``. This allows you to easily create and -manage custom configurations, or to divide a large complex configuration file into a set of smaller files. +Nextcloud supports loading configuration parameters from multiple files. You can add arbitrary +files ending with ``.config.php*`` (i.e. ``*.config.php``) in the ``config/`` directory. The values +in these files take precedence over ``config/config.php``. This allows you to easily create and +manage custom configurations, or to divide a large complex configuration file into a set of smaller files. These custom files are not overwritten by Nextcloud. -For example, you could place your email server configuration in ``config/email.config.php`` and +For example, you could place your email server configuration in ``config/email.config.php`` and whatever parameters you specify in it will be merged with your ``config/config.php``. -.. note:: The values in these additional configuration files **always** take precedence over +.. note:: The values in these additional configuration files **always** take precedence over ``config/config.php``. -.. tip:: To view your fully merged configuration (i.e. incorporating all config files), use +.. tip:: To view your fully merged configuration (i.e. incorporating all config files), use ``occ config:list system`` and/or ``occ config:list system --private``. -.. danger:: Be cautious when naming or creating backup copies of your active - ``config/config.php``. If a backup config file is located within ``config/`` and happens to be - named ``(ANYTHING).config.php``, it will be loaded as part of your live configuration and override +.. danger:: Be cautious when naming or creating backup copies of your active + ``config/config.php``. If a backup config file is located within ``config/`` and happens to be + named ``(ANYTHING).config.php``, it will be loaded as part of your live configuration and override your ``config/config.php`` values! Examples @@ -174,8 +174,8 @@ this after installation. The SQLite database is stored in your Nextcloud 'installed' => true, ); -.. note:: SQLite is a simple, lightweight embedded database that is fine for testing - and simple installations, but production environments you should use MySQL/MariaDB, +.. note:: SQLite is a simple, lightweight embedded database that is fine for testing + and simple installations, but production environments you should use MySQL/MariaDB, Oracle, or PosgreSQL. This example is from a new Nextcloud installation using MariaDB:: @@ -281,11 +281,11 @@ trusted_domains :: 'trusted_domains' => [ - 'demo.example.org', - 'otherdomain.example.org', - '10.111.112.113', - '[2001:db8::1]' - ], + 'demo.example.org', + 'otherdomain.example.org', + '10.111.112.113', + '[2001:db8::1]' + ], Your list of trusted domains that users can log into. Specifying trusted domains prevents host header poisoning. Do not remove this, as it performs @@ -435,9 +435,9 @@ dbreplica :: 'dbreplica' => [ - ['user' => 'nextcloud', 'password' => 'password1', 'host' => 'replica1', 'dbname' => ''], - ['user' => 'nextcloud', 'password' => 'password2', 'host' => 'replica2', 'dbname' => ''], - ], + ['user' => 'nextcloud', 'password' => 'password1', 'host' => 'replica1', 'dbname' => ''], + ['user' => 'nextcloud', 'password' => 'password2', 'host' => 'replica2', 'dbname' => ''], + ], Specify read-only replicas to be used by Nextcloud when querying the database @@ -911,11 +911,11 @@ ratelimit_overwrite :: 'ratelimit_overwrite' => [ - 'profile.profilepage.index' => [ - 'user' => ['limit' => 300, 'period' => 3600], - 'anon' => ['limit' => 1, 'period' => 300], - ] - ], + 'profile.profilepage.index' => [ + 'user' => ['limit' => 300, 'period' => 3600], + 'anon' => ['limit' => 1, 'period' => 300], + ] + ], Overwrite the individual rate limit for a specific route @@ -1637,11 +1637,11 @@ connectivity_check_domains :: 'connectivity_check_domains' => [ - 'https://www.nextcloud.com', - 'https://www.startpage.com', - 'https://www.eff.org', - 'https://www.edri.org' - ], + 'https://www.nextcloud.com', + 'https://www.startpage.com', + 'https://www.eff.org', + 'https://www.edri.org' + ], Which domains to request to determine the availability of an Internet connection. If none of these hosts are reachable, the administration panel @@ -1881,19 +1881,19 @@ log.condition :: 'log.condition' => [ - 'shared_secret' => '57b58edb6637fe3059b3595cf9c41b9', - 'users' => ['sample-user'], - 'apps' => ['files'], - 'matches' => [ - [ - 'shared_secret' => '57b58edb6637fe3059b3595cf9c41b9', - 'users' => ['sample-user'], - 'apps' => ['files'], - 'loglevel' => 1, - 'message' => 'contains substring' - ], - ], - ], + 'shared_secret' => '57b58edb6637fe3059b3595cf9c41b9', + 'users' => ['sample-user'], + 'apps' => ['files'], + 'matches' => [ + [ + 'shared_secret' => '57b58edb6637fe3059b3595cf9c41b9', + 'users' => ['sample-user'], + 'apps' => ['files'], + 'loglevel' => 1, + 'message' => 'contains substring' + ], + ], + ], Log condition for log level increase based on conditions. Once one of these conditions is met, the required log level is set to debug. This allows @@ -2104,15 +2104,15 @@ customclient_desktop :: 'customclient_desktop' - => 'https://nextcloud.com/install/#install-clients', - 'customclient_android' - => 'https://play.google.com/store/apps/details?id=com.nextcloud.client', - 'customclient_ios' - => 'https://itunes.apple.com/us/app/nextcloud/id1125420102?mt=8', - 'customclient_ios_appid' - => '1125420102', - 'customclient_fdroid' - => 'https://f-droid.org/packages/com.nextcloud.client/', + => 'https://nextcloud.com/install/#install-clients', + 'customclient_android' + => 'https://play.google.com/store/apps/details?id=com.nextcloud.client', + 'customclient_ios' + => 'https://itunes.apple.com/us/app/nextcloud/id1125420102?mt=8', + 'customclient_ios_appid' + => '1125420102', + 'customclient_fdroid' + => 'https://f-droid.org/packages/com.nextcloud.client/', This section is for configuring the download links for Nextcloud clients, as seen in the first-run wizard and on Personal pages. @@ -2166,7 +2166,7 @@ like in normal shares (when set to ``true``). .. warning:: Enabling this comes with some CRITICAL trade-offs: - + - If team folder "Advanced Permissions" (ACLs) are used, activities do not respect the permissions and therefore all users see all activities, even for files and directories they do not have access to. @@ -2247,12 +2247,12 @@ apps_paths :: 'apps_paths' => [ - [ - 'path' => '/var/www/nextcloud/apps', - 'url' => '/apps', - 'writable' => true, - ], - ], + [ + 'path' => '/var/www/nextcloud/apps', + 'url' => '/apps', + 'writable' => true, + ], + ], Use the ``apps_paths`` parameter to set the location of the Apps directory, which should be scanned for available apps, and where user-specific apps @@ -2454,17 +2454,17 @@ enabledPreviewProviders :: 'enabledPreviewProviders' => [ - 'OC\Preview\PNG', - 'OC\Preview\JPEG', - 'OC\Preview\GIF', - 'OC\Preview\BMP', - 'OC\Preview\XBitmap', - 'OC\Preview\Krita', - 'OC\Preview\WebP', - 'OC\Preview\MarkDown', - 'OC\Preview\TXT', - 'OC\Preview\OpenDocument', - ], + 'OC\Preview\PNG', + 'OC\Preview\JPEG', + 'OC\Preview\GIF', + 'OC\Preview\BMP', + 'OC\Preview\XBitmap', + 'OC\Preview\Krita', + 'OC\Preview\WebP', + 'OC\Preview\MarkDown', + 'OC\Preview\TXT', + 'OC\Preview\OpenDocument', + ], Only register providers that have been explicitly enabled @@ -2678,8 +2678,8 @@ openssl :: 'openssl' => [ - 'config' => '/absolute/location/of/openssl.cnf', - ], + 'config' => '/absolute/location/of/openssl.cnf', + ], Extra SSL options to be used for configuration. @@ -2754,21 +2754,21 @@ redis :: 'redis' => [ - 'host' => 'localhost', // can also be a Unix domain socket: '/tmp/redis.sock' - 'port' => 6379, - 'timeout' => 0.0, - 'read_timeout' => 0.0, - 'user' => '', // Optional: if not defined, no password will be used. - 'password' => '', // Optional: if not defined, no password will be used. - 'dbindex' => 0, // Optional: if undefined, SELECT will not run and will use Redis Server's default DB Index. - // If Redis in-transit encryption is enabled, provide certificates - // SSL context https://www.php.net/manual/en/context.ssl.php - 'ssl_context' => [ - 'local_cert' => '/certs/redis.crt', - 'local_pk' => '/certs/redis.key', - 'cafile' => '/certs/ca.crt' - ] - ], + 'host' => 'localhost', // can also be a Unix domain socket: '/tmp/redis.sock' + 'port' => 6379, + 'timeout' => 0.0, + 'read_timeout' => 0.0, + 'user' => '', // Optional: if not defined, no password will be used. + 'password' => '', // Optional: if not defined, no password will be used. + 'dbindex' => 0, // Optional: if undefined, SELECT will not run and will use Redis Server's default DB Index. + // If Redis in-transit encryption is enabled, provide certificates + // SSL context https://www.php.net/manual/en/context.ssl.php + 'ssl_context' => [ + 'local_cert' => '/certs/redis.crt', + 'local_pk' => '/certs/redis.key', + 'cafile' => '/certs/ca.crt' + ] + ], Connection details for Redis to use for memory caching in a single server configuration. @@ -2786,23 +2786,23 @@ redis.cluster :: 'redis.cluster' => [ - 'seeds' => [ // provide some or all of the cluster servers to bootstrap discovery, port required - 'localhost:7000', - 'localhost:7001', - ], - 'timeout' => 0.0, - 'read_timeout' => 0.0, - 'failover_mode' => \RedisCluster::FAILOVER_ERROR, - 'user' => '', // Optional: if not defined, no password will be used. - 'password' => '', // Optional: if not defined, no password will be used. - // If Redis in-transit encryption is enabled, provide certificates - // SSL context https://www.php.net/manual/en/context.ssl.php - 'ssl_context' => [ - 'local_cert' => '/certs/redis.crt', - 'local_pk' => '/certs/redis.key', - 'cafile' => '/certs/ca.crt' - ] - ], + 'seeds' => [ // provide some or all of the cluster servers to bootstrap discovery, port required + 'localhost:7000', + 'localhost:7001', + ], + 'timeout' => 0.0, + 'read_timeout' => 0.0, + 'failover_mode' => \RedisCluster::FAILOVER_ERROR, + 'user' => '', // Optional: if not defined, no password will be used. + 'password' => '', // Optional: if not defined, no password will be used. + // If Redis in-transit encryption is enabled, provide certificates + // SSL context https://www.php.net/manual/en/context.ssl.php + 'ssl_context' => [ + 'local_cert' => '/certs/redis.crt', + 'local_pk' => '/certs/redis.key', + 'cafile' => '/certs/ca.crt' + ] + ], Connection details for a Redis Cluster. @@ -2836,13 +2836,13 @@ memcached_servers :: 'memcached_servers' => [ - // hostname, port and optional weight - // or path and port 0 for Unix socket. Also see: - // https://www.php.net/manual/en/memcached.addservers.php - // https://www.php.net/manual/en/memcached.addserver.php - ['localhost', 11211], - //array('other.host.local', 11211), - ], + // hostname, port and optional weight + // or path and port 0 for Unix socket. Also see: + // https://www.php.net/manual/en/memcached.addservers.php + // https://www.php.net/manual/en/memcached.addserver.php + ['localhost', 11211], + //array('other.host.local', 11211), + ], Server details for one or more Memcached servers to use for memory caching. @@ -2853,25 +2853,25 @@ memcached_options :: 'memcached_options' => [ - // Set timeouts to 50ms - \Memcached::OPT_CONNECT_TIMEOUT => 50, - \Memcached::OPT_RETRY_TIMEOUT => 50, - \Memcached::OPT_SEND_TIMEOUT => 50, - \Memcached::OPT_RECV_TIMEOUT => 50, - \Memcached::OPT_POLL_TIMEOUT => 50, - - // Enable compression - \Memcached::OPT_COMPRESSION => true, - - // Turn on consistent hashing - \Memcached::OPT_LIBKETAMA_COMPATIBLE => true, - - // Enable Binary Protocol - \Memcached::OPT_BINARY_PROTOCOL => true, - - // Binary serializer will be enabled if the igbinary PECL module is available - //\Memcached::OPT_SERIALIZER => \Memcached::SERIALIZER_IGBINARY, - ], + // Set timeouts to 50ms + \Memcached::OPT_CONNECT_TIMEOUT => 50, + \Memcached::OPT_RETRY_TIMEOUT => 50, + \Memcached::OPT_SEND_TIMEOUT => 50, + \Memcached::OPT_RECV_TIMEOUT => 50, + \Memcached::OPT_POLL_TIMEOUT => 50, + + // Enable compression + \Memcached::OPT_COMPRESSION => true, + + // Turn on consistent hashing + \Memcached::OPT_LIBKETAMA_COMPATIBLE => true, + + // Enable Binary Protocol + \Memcached::OPT_BINARY_PROTOCOL => true, + + // Binary serializer will be enabled if the igbinary PECL module is available + //\Memcached::OPT_SERIALIZER => \Memcached::SERIALIZER_IGBINARY, + ], Connection options for Memcached @@ -2931,36 +2931,36 @@ objectstore :: 'objectstore' => [ - 'class' => 'OC\\Files\\ObjectStore\\Swift', - 'arguments' => [ - // trystack will use your Facebook ID as the username - 'username' => 'facebook100000123456789', - // in the trystack dashboard, go to user -> settings -> API Password to - // generate a password - 'password' => 'Secr3tPaSSWoRdt7', - // must already exist in the objectstore, name can be different - 'container' => 'nextcloud', - // prefix to prepend to the fileid, default is 'oid:urn:' - 'objectPrefix' => 'oid:urn:', - // create the container if it does not exist. default is false - 'autocreate' => true, - // required, dev-/trystack defaults to 'RegionOne' - 'region' => 'RegionOne', - // The Identity / Keystone endpoint - 'url' => 'http://8.21.28.222:5000/v2.0', - // uploadPartSize: size of the uploaded chunks, defaults to 524288000 - 'uploadPartSize' => 524288000, - // required on dev-/trystack - 'tenantName' => 'facebook100000123456789', - // dev-/trystack uses swift by default, the lib defaults to 'cloudFiles' - // if omitted - 'serviceName' => 'swift', - // The Interface / URL Type, optional - 'urlType' => 'internal', - // Maximum amount of data that can be uploaded - 'totalSizeLimit' => 1024 * 1024 * 1024, - ], - ], + 'class' => 'OC\\Files\\ObjectStore\\Swift', + 'arguments' => [ + // trystack will use your Facebook ID as the username + 'username' => 'facebook100000123456789', + // in the trystack dashboard, go to user -> settings -> API Password to + // generate a password + 'password' => 'Secr3tPaSSWoRdt7', + // must already exist in the objectstore, name can be different + 'container' => 'nextcloud', + // prefix to prepend to the fileid, default is 'oid:urn:' + 'objectPrefix' => 'oid:urn:', + // create the container if it does not exist. default is false + 'autocreate' => true, + // required, dev-/trystack defaults to 'RegionOne' + 'region' => 'RegionOne', + // The Identity / Keystone endpoint + 'url' => 'http://8.21.28.222:5000/v2.0', + // uploadPartSize: size of the uploaded chunks, defaults to 524288000 + 'uploadPartSize' => 524288000, + // required on dev-/trystack + 'tenantName' => 'facebook100000123456789', + // dev-/trystack uses swift by default, the lib defaults to 'cloudFiles' + // if omitted + 'serviceName' => 'swift', + // The Interface / URL Type, optional + 'urlType' => 'internal', + // Maximum amount of data that can be uploaded + 'totalSizeLimit' => 1024 * 1024 * 1024, + ], + ], This example shows how to configure Nextcloud to store all files in a Swift object storage. @@ -2987,31 +2987,31 @@ objectstore :: 'objectstore' => [ - 'class' => 'OC\\Files\\ObjectStore\\Swift', - 'arguments' => [ - 'autocreate' => true, - 'user' => [ - 'name' => 'swift', - 'password' => 'swift', - 'domain' => [ - 'name' => 'default', - ], - ], - 'scope' => [ - 'project' => [ - 'name' => 'service', - 'domain' => [ - 'name' => 'default', - ], - ], - ], - 'tenantName' => 'service', - 'serviceName' => 'swift', - 'region' => 'regionOne', - 'url' => 'http://yourswifthost:5000/v3', - 'bucket' => 'nextcloud', - ], - ], + 'class' => 'OC\\Files\\ObjectStore\\Swift', + 'arguments' => [ + 'autocreate' => true, + 'user' => [ + 'name' => 'swift', + 'password' => 'swift', + 'domain' => [ + 'name' => 'default', + ], + ], + 'scope' => [ + 'project' => [ + 'name' => 'service', + 'domain' => [ + 'name' => 'default', + ], + ], + ], + 'tenantName' => 'service', + 'serviceName' => 'swift', + 'region' => 'regionOne', + 'url' => 'http://yourswifthost:5000/v3', + 'bucket' => 'nextcloud', + ], + ], To use Swift V3 @@ -3022,26 +3022,26 @@ objectstore :: 'objectstore' => [ - 'class' => 'OC\\Files\\ObjectStore\\S3', - 'arguments' => [ - 'bucket' => 'nextcloud', - 'key' => 'your-access-key', - 'secret' => 'your-secret-key', - 'hostname' => 's3.example.com', - 'port' => 443, - 'use_ssl' => true, - 'region' => 'us-east-1', - // optional: Maximum number of retry attempts for failed S3 requests - // Default: 5 - 'retriesMaxAttempts' => 5, - // Data Integrity Protections for Amazon S3 (https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html) - // Valid values are "when_required" (default) and "when_supported". - // To ensure compatibility with 3rd party S3 implementations, Nextcloud disables it by default. However, if you are - // using Amazon S3 (or any other implementation that supports it) we recommend enabling it by using "when_supported". - 'request_checksum_calculation' => 'when_required', - 'response_checksum_validation' => 'when_required', - ], - ], + 'class' => 'OC\\Files\\ObjectStore\\S3', + 'arguments' => [ + 'bucket' => 'nextcloud', + 'key' => 'your-access-key', + 'secret' => 'your-secret-key', + 'hostname' => 's3.example.com', + 'port' => 443, + 'use_ssl' => true, + 'region' => 'us-east-1', + // optional: Maximum number of retry attempts for failed S3 requests + // Default: 5 + 'retriesMaxAttempts' => 5, + // Data Integrity Protections for Amazon S3 (https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html) + // Valid values are "when_required" (default) and "when_supported". + // To ensure compatibility with 3rd party S3 implementations, Nextcloud disables it by default. However, if you are + // using Amazon S3 (or any other implementation that supports it) we recommend enabling it by using "when_supported". + 'request_checksum_calculation' => 'when_required', + 'response_checksum_validation' => 'when_required', + ], + ], To use S3 object storage @@ -3316,12 +3316,12 @@ dbdriveroptions :: 'dbdriveroptions' => [ - PDO::MYSQL_ATTR_SSL_CA => '/file/path/to/ca_cert.pem', - PDO::MYSQL_ATTR_SSL_KEY => '/file/path/to/mysql-client-key.pem', - PDO::MYSQL_ATTR_SSL_CERT => '/file/path/to/mysql-client-cert.pem', - PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => false, - PDO::MYSQL_ATTR_INIT_COMMAND => 'SET wait_timeout = 28800' - ], + PDO::MYSQL_ATTR_SSL_CA => '/file/path/to/ca_cert.pem', + PDO::MYSQL_ATTR_SSL_KEY => '/file/path/to/mysql-client-key.pem', + PDO::MYSQL_ATTR_SSL_CERT => '/file/path/to/mysql-client-cert.pem', + PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => false, + PDO::MYSQL_ATTR_INIT_COMMAND => 'SET wait_timeout = 28800' + ], Additional driver options for the database connection, e.g., to enable SSL encryption in MySQL or specify a custom wait timeout on a cheap hoster. @@ -3411,12 +3411,12 @@ pgsql_ssl :: 'pgsql_ssl' => [ - 'mode' => '', - 'cert' => '', - 'rootcert' => '', - 'key' => '', - 'crl' => '', - ], + 'mode' => '', + 'cert' => '', + 'rootcert' => '', + 'key' => '', + 'crl' => '', + ], PostgreSQL SSL connection @@ -3427,11 +3427,11 @@ supportedDatabases :: 'supportedDatabases' => [ - 'sqlite', - 'mysql', - 'pgsql', - 'oci', - ], + 'sqlite', + 'mysql', + 'pgsql', + 'oci', + ], Database types supported for installation. @@ -4059,9 +4059,9 @@ csrf.optout :: 'csrf.optout' => [ - '/^WebDAVFS/', // OS X Finder - '/^Microsoft-WebDAV-MiniRedir/', // Windows WebDAV drive - ], + '/^WebDAVFS/', // OS X Finder + '/^Microsoft-WebDAV-MiniRedir/', // Windows WebDAV drive + ], List of user agents exempt from SameSite cookie protection due to non-standard HTTP behavior. @@ -4370,14 +4370,14 @@ binary_search_paths :: 'binary_search_paths' => [ - '/usr/local/sbin', - '/usr/local/bin', - '/usr/sbin', - '/usr/bin', - '/sbin', - '/bin', - '/opt/bin', - ], + '/usr/local/sbin', + '/usr/local/bin', + '/usr/sbin', + '/usr/bin', + '/sbin', + '/bin', + '/opt/bin', + ], Directories where Nextcloud searches for external binaries (e.g., LibreOffice, sendmail, ffmpeg). @@ -4466,9 +4466,9 @@ openmetrics_skipped_classes :: 'openmetrics_skipped_classes' => [ - 'OC\OpenMetrics\Exporters\FilesByType', - 'OCA\Files_Sharing\OpenMetrics\SharesCount', - ], + 'OC\OpenMetrics\Exporters\FilesByType', + 'OCA\Files_Sharing\OpenMetrics\SharesCount', + ], OpenMetrics skipped exporters Allows to skip some exporters in the OpenMetrics endpoint ``/metrics``. @@ -4482,10 +4482,10 @@ openmetrics_allowed_clients :: 'openmetrics_allowed_clients' => [ - '192.168.0.0/16', - 'fe80::/10', - '10.0.0.1', - ], + '192.168.0.0/16', + 'fe80::/10', + '10.0.0.1', + ], OpenMetrics allowed client IP addresses Restricts the IP addresses able to make requests on the ``/metrics`` endpoint. @@ -4509,8 +4509,8 @@ administrator.". In some cases this should not be triggered, because it was a normal maintenance change. To disable this specific email the appconfig option ``disable_email.email_address_changed_by_admin`` can be set to ``yes``:: - occ config:app:set settings disable_activity.email_address_changed_by_admin --value yes + occ config:app:set settings disable_activity.email_address_changed_by_admin --value yes To disable this behaviour change it to any other value or delete the app config:: - occ config:app:delete settings disable_activity.email_address_changed_by_admin + occ config:app:delete settings disable_activity.email_address_changed_by_admin diff --git a/admin_manual/configuration_server/email_configuration.rst b/admin_manual/configuration_server/email_configuration.rst index 36c528bf226..ee86ddd5c92 100644 --- a/admin_manual/configuration_server/email_configuration.rst +++ b/admin_manual/configuration_server/email_configuration.rst @@ -51,7 +51,7 @@ You need the following information from your mail server administrator to connect Nextcloud to a remote SMTP server: .. warning:: There were changes to the 3rd party mailer library in Nextcloud 26: - + * STARTTLS cannot be enforced; it is used automatically if the mail server supports it. Set the encryption type to **None/STARTTLS** to allow this automatic upgrade. See :ref:`here` for an example on how to configure self-signed certificates. * NTLM authentication for Microsoft Exchange is not supported by the new mailer library. Try using `basic authentication `_ instead. * Outlook and Microsoft Exchange have discontinued support for Basic authentication. It is no longer possible to use their services as your default email handler. @@ -282,7 +282,7 @@ messages by enabling the ``mail_smtpdebug`` parameter and temporarily setting yo "mail_smtpdebug" => true, "loglevel" => 0, -Be cautious setting your ``loglevel`` to DEBUG (``0``) since it'll apply to everything occurring on your NC instance, not just email. +Be cautious setting your ``loglevel`` to DEBUG (``0``) since it'll apply to everything occurring on your NC instance, not just email. And don't forget to set it back to a more reasonable level when you're done troubleshooting: :: diff --git a/admin_manual/configuration_server/external_sites.rst b/admin_manual/configuration_server/external_sites.rst index 8011fc28db6..60481cf6747 100644 --- a/admin_manual/configuration_server/external_sites.rst +++ b/admin_manual/configuration_server/external_sites.rst @@ -10,8 +10,8 @@ sites** app, as this screenshot shows. *Click to enlarge* This is useful for quick access to important pages such as the -Nextcloud manuals and informational pages for your company, and for presenting -external pages inside your custom Nextcloud branding, if you use your own custom +Nextcloud manuals and informational pages for your company, and for presenting +external pages inside your custom Nextcloud branding, if you use your own custom themes. The External sites app can be easily installed from the app store. Go to **Settings > Apps > @@ -40,21 +40,21 @@ reloading the page. Configurations preventing embedding ----------------------------------- -Your links may or may not work correctly due to the various ways that Web -browsers and Web sites handle HTTP and HTTPS URLs, and because the External -Sites app embeds external links in IFrames. Modern Web browsers try very hard -to protect Web surfers from dangerous links, and safety apps like -`Privacy Badger `_ and ad-blockers may block -embedded pages. It is strongly recommended to enforce HTTPS on your Nextcloud -server; do not weaken this, or any of your security tools, just to make -embedded Web pages work. After all, you can freely access them outside of +Your links may or may not work correctly due to the various ways that Web +browsers and Web sites handle HTTP and HTTPS URLs, and because the External +Sites app embeds external links in IFrames. Modern Web browsers try very hard +to protect Web surfers from dangerous links, and safety apps like +`Privacy Badger `_ and ad-blockers may block +embedded pages. It is strongly recommended to enforce HTTPS on your Nextcloud +server; do not weaken this, or any of your security tools, just to make +embedded Web pages work. After all, you can freely access them outside of Nextcloud. -Most Web sites that offer login functionalities use the ``X-Frame-Options`` or -``Content-Security-Policy`` HTTP header which instructs browsers to not -allow their pages to be embedded for security reasons (e.g. "Clickjacking"). You -can usually verify the reason why embedding the website is not possible by using -your browser's console tool. For example, this page has an invalid SSL +Most Web sites that offer login functionalities use the ``X-Frame-Options`` or +``Content-Security-Policy`` HTTP header which instructs browsers to not +allow their pages to be embedded for security reasons (e.g. "Clickjacking"). You +can usually verify the reason why embedding the website is not possible by using +your browser's console tool. For example, this page has an invalid SSL certificate. .. figure:: ../images/external-sites-4.png diff --git a/admin_manual/configuration_server/language_configuration.rst b/admin_manual/configuration_server/language_configuration.rst index 4934277e442..76b8249da97 100644 --- a/admin_manual/configuration_server/language_configuration.rst +++ b/admin_manual/configuration_server/language_configuration.rst @@ -43,7 +43,7 @@ The locale is used to define how dates and other formats are displayed. Nextclou should automatically pick an appropriate locale based on your current language. Users can modify their locale inside their settings panel. If that does not work properly or if you want to make sure that Nextcloud always -starts with a given locale, you can set a **default_locale** parameter in the +starts with a given locale, you can set a **default_locale** parameter in the :file:`config/config.php`. .. note:: The default_locale parameter is only used when the user hasn't configured diff --git a/admin_manual/configuration_server/logging_configuration.rst b/admin_manual/configuration_server/logging_configuration.rst index 5294e52aba1..7d025e22d87 100644 --- a/admin_manual/configuration_server/logging_configuration.rst +++ b/admin_manual/configuration_server/logging_configuration.rst @@ -2,11 +2,11 @@ Logging ======= -Use your Nextcloud log to review system status, or to help debug problems. You may adjust logging levels, and choose how and where log data is stored. If additional event logging is required, you can optionally activate the **admin_audit** app. +Use your Nextcloud log to review system status, or to help debug problems. You may adjust logging levels, and choose how and where log data is stored. If additional event logging is required, you can optionally activate the **admin_audit** app. When ``file`` based logging is utilized, both the Nextcloud log and, optionally, the **admin_audit** app log can be viewed within the Nextcloud interface under *Administration settings -> Logging* (this functionality is provided by the **logreader** app). -Further configuration and usage details for both the standard Nextcloud log and the optional **admin_audit** app log can be found below. +Further configuration and usage details for both the standard Nextcloud log and the optional **admin_audit** app log can be found below. Log level --------- @@ -146,9 +146,9 @@ If you wish to override this and log to syslog instead the following would be on :: - "log_type_audit" => "syslog", - "syslog_tag_audit" => "Nextcloud", - "logfile_audit" => "", + "log_type_audit" => "syslog", + "syslog_tag_audit" => "Nextcloud", + "logfile_audit" => "", Log level interaction ~~~~~~~~~~~~~~~~~~~~~ @@ -157,9 +157,9 @@ If system ``loglevel`` in ``config.php`` is set to ``2`` or higher, audit loggin :: - "log.condition" => [ - "apps" => ["admin_audit"], - ], + "log.condition" => [ + "apps" => ["admin_audit"], + ], Find detailed documentation on auditable events for enterprises in our `customer portal `_. @@ -172,10 +172,10 @@ Add the following to your ``config.php`` (adjusting the path to your own ``nextc :: - 'log.condition' => [ - 'apps' => [ 'admin_audit'], - ], - 'logfile_audit' => '/var/www/html/data/nextcloud.log', + 'log.condition' => [ + 'apps' => [ 'admin_audit'], + ], + 'logfile_audit' => '/var/www/html/data/nextcloud.log', Configuring through admin_audit app settings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -184,7 +184,7 @@ Previously the audit logfile was defined in the app config. This config is still :: - occ config:app:set admin_audit logfile --value=/var/log/nextcloud/audit.log + occ config:app:set admin_audit logfile --value=/var/log/nextcloud/audit.log .. _PHP date function: http://www.php.net/manual/en/function.date.php @@ -197,7 +197,7 @@ The path of the workflow log can be set as follows: :: - occ config:app:set workflowengine logfile --value=/var/log/nextcloud/flow.log + occ config:app:set workflowengine logfile --value=/var/log/nextcloud/flow.log Set the value to `/dev/null` to avoid storing the log. diff --git a/admin_manual/configuration_server/oauth2.rst b/admin_manual/configuration_server/oauth2.rst index 97965e4f182..ad4928a576d 100644 --- a/admin_manual/configuration_server/oauth2.rst +++ b/admin_manual/configuration_server/oauth2.rst @@ -38,7 +38,7 @@ Note that apache by default strips this. Make sure you have ``mod_headers``, ``m Security considerations ----------------------- -Nextcloud ``OAuth2`` implementation currently does not support scoped access. This means that every token has full access to the complete account including read and write permission to the stored files. It is essential to store the ``OAuth2`` tokens in a safe way! +Nextcloud ``OAuth2`` implementation currently does not support scoped access. This means that every token has full access to the complete account including read and write permission to the stored files. It is essential to store the ``OAuth2`` tokens in a safe way! Without scopes and restrictable access it is not recommended to use a Nextcloud instance as a user authentication service. diff --git a/admin_manual/configuration_server/reverse_proxy_configuration.rst b/admin_manual/configuration_server/reverse_proxy_configuration.rst index 1a12eccc6ab..e0671dff7b0 100644 --- a/admin_manual/configuration_server/reverse_proxy_configuration.rst +++ b/admin_manual/configuration_server/reverse_proxy_configuration.rst @@ -18,7 +18,7 @@ configured in :file:`config/config.php` Set the :file:`trusted_proxies` parameter as an array of: -* IPv4 addresses +* IPv4 addresses * IPv4 ranges in CIDR notation * IPv6 addresses * IPv6 ranges in CIDR notation @@ -42,7 +42,7 @@ Overwrite parameters The automatic hostname, protocol or webroot detection of Nextcloud can fail in certain reverse proxy situations. This configuration allows the automatic detection -to be manually overridden. If Nextcloud fails to automatically detect the hostname, protocol +to be manually overridden. If Nextcloud fails to automatically detect the hostname, protocol or webroot you can use the **overwrite** parameters inside the :file:`config/config.php`. * :file:`overwritehost` set the hostname of the proxy. You can also specify a port. @@ -124,13 +124,13 @@ If using nginx as Nextcloud's webserver from behind another nginx reverse proxy, location /.well-known/carddav { return 301 $scheme://$host/remote.php/dav; } - + location /.well-known/caldav { return 301 $scheme://$host/remote.php/dav; } - + location ^~ /.well-known { - return 301 $scheme://$host/index.php$uri; + return 301 $scheme://$host/index.php$uri; } When using NGINX Proxy Manager, the entry ``proxy_hide_header Upgrade;`` must be added in the *"Advanced Settings"* diff --git a/admin_manual/configuration_server/security_setup_warnings.rst b/admin_manual/configuration_server/security_setup_warnings.rst index 66ae66a212f..c564e216dec 100644 --- a/admin_manual/configuration_server/security_setup_warnings.rst +++ b/admin_manual/configuration_server/security_setup_warnings.rst @@ -2,8 +2,8 @@ Warnings on admin page ====================== -Your Nextcloud server has a built-in configuration checker, and it reports its -findings at the top of your Admin page. These are some of the warnings you +Your Nextcloud server has a built-in configuration checker, and it reports its +findings at the top of your Admin page. These are some of the warnings you might see, and what to do about them. .. figure:: ../images/security-setup-warning-1.png @@ -17,7 +17,7 @@ up to date! Privacy means little without security. Cache warnings -------------- -"No memory cache has been configured. To enhance your performance please +"No memory cache has been configured. To enhance your performance please configure a memcache if available." Nextcloud supports multiple php caching extensions: @@ -25,15 +25,15 @@ extensions: * Memcached * Redis (minimum required PHP extension version: 2.2.6) -You will see this warning if you have no caches installed and enabled, or if -your cache does not have the required minimum version installed; older versions +You will see this warning if you have no caches installed and enabled, or if +your cache does not have the required minimum version installed; older versions are disabled because of performance problems. If you see "*{Cache}* below version *{Version}* is installed. for stability and performance reasons we recommend to update to a newer *{Cache}* version" then you need to upgrade, or, if you're not using it, remove it. -You are not required to use any caches, but caches improve server performance. +You are not required to use any caches, but caches improve server performance. See :doc:`caching_configuration`. Transactional file locking is disabled @@ -48,11 +48,11 @@ to correctly configure your environment for transactional file locking. You are accessing this site via HTTP ------------------------------------ -"You are accessing this site via HTTP. We strongly suggest you configure your -server to require using HTTPS instead." Please take this warning seriously; -using HTTPS is a fundamental security measure. You must configure your Web -server to support it, and then there are some settings in the **Security** -section of your Nextcloud Admin page to enable. The following pages +"You are accessing this site via HTTP. We strongly suggest you configure your +server to require using HTTPS instead." Please take this warning seriously; +using HTTPS is a fundamental security measure. You must configure your Web +server to support it, and then there are some settings in the **Security** +section of your Nextcloud Admin page to enable. The following pages describe how to enable HTTPS on the Apache and Nginx Web servers. :ref:`enabling_ssl_label` (on Apache) @@ -65,7 +65,7 @@ The test with getenv(\"PATH\") only returns an empty response ------------------------------------------------------------- Some environments are not passing a valid PATH variable to Nextcloud. The -:ref:`php_fpm_tips_label` provides the information about how to configure your +:ref:`php_fpm_tips_label` provides the information about how to configure your environment. The "Strict-Transport-Security" HTTP header is not configured @@ -101,15 +101,15 @@ is maintained containing various information and debugging hints. Outdated NSS / OpenSSL version ------------------------------ -"cURL is using an outdated OpenSSL version (OpenSSL/$version). Please update your -operating system or features such as installing and updating apps via the app store +"cURL is using an outdated OpenSSL version (OpenSSL/$version). Please update your +operating system or features such as installing and updating apps via the app store or Federated Cloud Sharing will not work reliably." -"cURL is using an outdated NSS version (NSS/$version). Please update your operating -system or features such as installing and updating apps via the app store or Federated +"cURL is using an outdated NSS version (NSS/$version). Please update your operating +system or features such as installing and updating apps via the app store or Federated Cloud Sharing will not work reliably." -There are known bugs in older OpenSSL and NSS versions leading to misbehavior in +There are known bugs in older OpenSSL and NSS versions leading to misbehavior in combination with remote hosts using SNI. A technology used by most of the HTTPS websites. To ensure that Nextcloud will work properly you need to update OpenSSL to at least 1.0.2b or 1.0.1d. For NSS the patch version depends on your distribution diff --git a/admin_manual/configuration_user/authentication.rst b/admin_manual/configuration_user/authentication.rst index c02e7363809..43a0b235f2f 100644 --- a/admin_manual/configuration_user/authentication.rst +++ b/admin_manual/configuration_user/authentication.rst @@ -25,4 +25,4 @@ The time spans can be overwritten with configuration:: sudo -E -u www-data php occ config:system:set token_auth_wipe_token_retention --type=int --value 2592000 # 60*60*24*30 - 30 days sudo -E -u www-data php occ config:system:set token_auth_token_retention --type=int --value 63072000 # 60*60*24*365*2 - 2 years -Values are set in **seconds**. \ No newline at end of file +Values are set in **seconds**. diff --git a/admin_manual/configuration_user/instruction_set_for_apps.rst b/admin_manual/configuration_user/instruction_set_for_apps.rst index 1e9efbcaf92..abca739896a 100644 --- a/admin_manual/configuration_user/instruction_set_for_apps.rst +++ b/admin_manual/configuration_user/instruction_set_for_apps.rst @@ -5,8 +5,8 @@ Instruction set for apps Get list of apps ---------------- -Returns a list of apps installed on the Nextcloud server. Authentication is done -by sending a Basic HTTP Authorization +Returns a list of apps installed on the Nextcloud server. Authentication is done +by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/apps/** @@ -49,7 +49,7 @@ XML output Get app info ------------ -Provides information on a specific application. Authentication is done by +Provides information on a specific application. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/apps/{appid}** @@ -106,7 +106,7 @@ XML output Enable an app ------------- -Enable an app. Authentication is done by sending a Basic HTTP Authorization +Enable an app. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/apps/{appid}** @@ -173,4 +173,4 @@ XML output ok - + diff --git a/admin_manual/configuration_user/instruction_set_for_groups.rst b/admin_manual/configuration_user/instruction_set_for_groups.rst index f9e35ae2541..0b4b7a9f583 100644 --- a/admin_manual/configuration_user/instruction_set_for_groups.rst +++ b/admin_manual/configuration_user/instruction_set_for_groups.rst @@ -1,11 +1,11 @@ ========================== Instruction set for groups -========================== +========================== Search/get groups ----------------- -Retrieves a list of groups from the Nextcloud server. Authentication is done by +Retrieves a list of groups from the Nextcloud server. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/groups** @@ -88,7 +88,7 @@ XML output Get members of a group ---------------------- -Retrieves a list of group members. Authentication is done by sending a Basic +Retrieves a list of group members. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/groups/{groupid}** @@ -124,7 +124,7 @@ XML output - + Get subadmins of a group ------------------------ @@ -132,7 +132,7 @@ Returns subadmins of the group. Authentication is done by sending a Basic HTTP Authorization header. **Syntax: ocs/v1.php/cloud/groups/{groupid}/subadmins** - + * HTTP method: GET Status codes: @@ -164,7 +164,7 @@ XML output Tom - + Edit data of a single group --------------------------- diff --git a/admin_manual/configuration_user/reset_admin_password.rst b/admin_manual/configuration_user/reset_admin_password.rst index 6c333fc4455..cc8bbf75fa8 100644 --- a/admin_manual/configuration_user/reset_admin_password.rst +++ b/admin_manual/configuration_user/reset_admin_password.rst @@ -4,23 +4,23 @@ Resetting a lost admin password The normal ways to recover a lost password are: -1. Click the password reset link on the login screen; this appears after a - failed login attempt. This works only if you have entered your email address - on your Personal page in the Nextcloud Web interface, so that the Nextcloud +1. Click the password reset link on the login screen; this appears after a + failed login attempt. This works only if you have entered your email address + on your Personal page in the Nextcloud Web interface, so that the Nextcloud server can email a reset link to you. 2. Ask another Nextcloud server admin to reset it for you. -If neither of these is an option, then you have a third option, and that is +If neither of these is an option, then you have a third option, and that is using the ``occ`` command. See :doc:`../occ_command` to learn more about using the ``occ`` command. :: $ sudo -E -u www-data php /var/www/nextcloud/occ user:resetpassword admin - Enter a new password: - Confirm the new password: + Enter a new password: + Confirm the new password: Successfully reset password for admin - -If your Nextcloud username is not ``admin``, then substitute your Nextcloud + +If your Nextcloud username is not ``admin``, then substitute your Nextcloud username. diff --git a/admin_manual/configuration_user/reset_user_password.rst b/admin_manual/configuration_user/reset_user_password.rst index 56d5d479426..613f1751456 100644 --- a/admin_manual/configuration_user/reset_user_password.rst +++ b/admin_manual/configuration_user/reset_user_password.rst @@ -2,13 +2,13 @@ Resetting a user password ========================= -The Nextcloud login screen displays a **Wrong password. Reset it?** message -after a user enters an incorrect password, and then Nextcloud automatically -resets their password. However, if you are using a read-only authentication -backend such as LDAP or Active Directory, this will not work. In this case you -may specify a custom URL in your ``config.php`` file to direct your user to a +The Nextcloud login screen displays a **Wrong password. Reset it?** message +after a user enters an incorrect password, and then Nextcloud automatically +resets their password. However, if you are using a read-only authentication +backend such as LDAP or Active Directory, this will not work. In this case you +may specify a custom URL in your ``config.php`` file to direct your user to a server that can handle an automatic reset:: 'lost_password_link' => 'https://example.org/link/to/password/reset', - - + + diff --git a/admin_manual/configuration_user/two_factor-auth.rst b/admin_manual/configuration_user/two_factor-auth.rst index dda254aa1fd..96cb481aa3b 100644 --- a/admin_manual/configuration_user/two_factor-auth.rst +++ b/admin_manual/configuration_user/two_factor-auth.rst @@ -6,7 +6,7 @@ Two-factor authentication Two-factor authentication adds an additional layer of security to user accounts. In order to log in on an account when two-factor authentication (2FA) is enabled, you must provide both the -login password and another factor. +login password and another factor. To use 2FA two things must happen: @@ -18,7 +18,7 @@ Both steps are described below. Enabling two-factor authentication ---------------------------------- -2FA in Nextcloud is pluggable, meaning that various 2FA providers can be used to support different +2FA in Nextcloud is pluggable, meaning that various 2FA providers can be used to support different types of factors. Three providers are automatically installed (but may need to be enabled): **Two-Factor TOTP Provider** @@ -31,7 +31,7 @@ types of factors. Three providers are automatically installed (but may need to b **Two-Factor Authentication via Nextcloud notifications** - A 2FA factor provider that enables the use of a logged in device as the secondary factor. -- Disabled by default. Go to *Apps->Disabled apps* and find *Two-Factor Authentication via Nextcloud +- Disabled by default. Go to *Apps->Disabled apps* and find *Two-Factor Authentication via Nextcloud notification* to enable this factor. **Two-Factor Backup Codes** @@ -41,11 +41,11 @@ types of factors. Three providers are automatically installed (but may need to b - Generates ten backup codes (which can, of course, only be used once). - Always enabled. -Other 2FA providers may be found in the App Store. +Other 2FA providers may be found in the App Store. .. figure:: ../images/2fa-app-install.png -Developers can also `implement new two-factor provider +Developers can also `implement new two-factor provider apps `_. Enforcing two-factor authentication @@ -56,7 +56,7 @@ it for their account `under their personal settings Security*. diff --git a/admin_manual/configuration_user/user_auth_ldap.rst b/admin_manual/configuration_user/user_auth_ldap.rst index db2701bdad7..77df2f9ee38 100644 --- a/admin_manual/configuration_user/user_auth_ldap.rst +++ b/admin_manual/configuration_user/user_auth_ldap.rst @@ -585,10 +585,10 @@ Internal Username: You can override all of this with the Internal Username setting. Leave it empty for default behavior. Changes will affect only newly mapped LDAP users. - - When configuring this, be aware that the username in Nextcloud is considered + + When configuring this, be aware that the username in Nextcloud is considered immutable and cannot be changed afterwards. This can cause issues when using - an attribute that might change, e.g. the email address of a user that will + an attribute that might change, e.g. the email address of a user that will get changed during name change. * Example: *uid* @@ -781,7 +781,7 @@ Logging ^^^^^^^ Nextcloud's LDAP implementation is capable of logging lots of additional details about -its activities. When diagnosing problems, it can be useful to temporarily adjust your +its activities. When diagnosing problems, it can be useful to temporarily adjust your ``loglevel`` to INFO (``1``) or DEBUG (``0``). SSL certificate verification (LDAPS, TLS) @@ -872,7 +872,7 @@ The attributes of users are fetched on demand (i.e. for sharing autocompletion or in the user management) and then stored inside the Nextcloud database to allow a better performance on our side. They are typically checked twice a day in batches from all users again. Beside that they are also refreshed during a -login for this user or can be fetched manually via the occ command +login for this user or can be fetched manually via the occ command ``occ ldap:check-user --update USERID`` where ``USERID`` is Nextcloud's user id. For groups, a cache of memberships is stored in the database to be able to trigger diff --git a/admin_manual/configuration_user/user_auth_ldap_cleanup.rst b/admin_manual/configuration_user/user_auth_ldap_cleanup.rst index a80898da17a..04baf7361ee 100644 --- a/admin_manual/configuration_user/user_auth_ldap_cleanup.rst +++ b/admin_manual/configuration_user/user_auth_ldap_cleanup.rst @@ -2,12 +2,12 @@ LDAP user cleanup ================= -LDAP User Cleanup is a new feature in the ``LDAP user and group backend`` -application. LDAP User Cleanup is a background process that automatically -searches the Nextcloud LDAP mappings table, and verifies if the LDAP users are -still available. Any users that are not available are marked as ``deleted`` in -the ``oc_preferences`` database table. Then you can run a command to display -this table, displaying only the users marked as ``deleted``, and then you have +LDAP User Cleanup is a new feature in the ``LDAP user and group backend`` +application. LDAP User Cleanup is a background process that automatically +searches the Nextcloud LDAP mappings table, and verifies if the LDAP users are +still available. Any users that are not available are marked as ``deleted`` in +the ``oc_preferences`` database table. Then you can run a command to display +this table, displaying only the users marked as ``deleted``, and then you have the option of removing their data from your Nextcloud data directory. These items are removed upon cleanup: @@ -19,18 +19,18 @@ These items are removed upon cleanup: There are two prerequisites for LDAP User Cleanup to operate: -1. Set ``ldapUserCleanupInterval`` in ``config.php`` to your desired check +1. Set ``ldapUserCleanupInterval`` in ``config.php`` to your desired check interval in minutes. The default is 51 minutes. -2. All configured LDAP connections are enabled and operating correctly. As users - can exist on multiple LDAP servers, you want to be sure that all of your - LDAP servers are available so that a user on a temporarily disconnected LDAP +2. All configured LDAP connections are enabled and operating correctly. As users + can exist on multiple LDAP servers, you want to be sure that all of your + LDAP servers are available so that a user on a temporarily disconnected LDAP server is not marked as ``deleted``. - -The background process examines 50 users at a time, and runs at the interval you -configured with ``ldapUserCleanupInterval``. For example, if you have 200 LDAP -users and your ``ldapUserCleanupInterval`` is 20 minutes, the process will -examine the first 50 users, then 20 minutes later the next 50 users, and 20 + +The background process examines 50 users at a time, and runs at the interval you +configured with ``ldapUserCleanupInterval``. For example, if you have 200 LDAP +users and your ``ldapUserCleanupInterval`` is 20 minutes, the process will +examine the first 50 users, then 20 minutes later the next 50 users, and 20 minutes later the next 50, and so on. The amount of users to check can be set to a custom value via occ command. The @@ -39,17 +39,17 @@ following example sets it to 300: ``sudo -E -u www-data php occ config:app:set --value=300 user_ldap cleanUpJobChunkSize`` There are two ``occ`` commands to use for examining a table of users marked as -deleted, and then manually deleting them. The ``occ`` command is in your -Nextcloud directory, for example ``/var/www/nextcloud/occ``, and it must be run as -your HTTP user. To learn more about ``occ``, see +deleted, and then manually deleting them. The ``occ`` command is in your +Nextcloud directory, for example ``/var/www/nextcloud/occ``, and it must be run as +your HTTP user. To learn more about ``occ``, see :doc:`../occ_command`. These examples are for Ubuntu Linux: -1. ``sudo -E -u www-data php occ ldap:show-remnants`` displays a table with all +1. ``sudo -E -u www-data php occ ldap:show-remnants`` displays a table with all users that have been marked as deleted, and their LDAP data. -2. ``sudo -E -u www-data php occ user:delete [user]`` removes the user's data from the +2. ``sudo -E -u www-data php occ user:delete [user]`` removes the user's data from the Nextcloud data directory. This example shows what the table of users marked as ``deleted`` looks like:: @@ -70,11 +70,11 @@ Following flags can be specified additionally: * ``--json``: instead of a table, the output is json-encoded. This makes it easy to process the data programmatically. -Then you can run ``sudo -E -u www-data php occ user:delete aaliyah_brown`` to delete +Then you can run ``sudo -E -u www-data php occ user:delete aaliyah_brown`` to delete user aaliyah_brown. You must use the user's Nextcloud name. Deleting local Nextcloud users ------------------------------ -You may also use ``occ user:delete [user]`` to remove a local Nextcloud user; +You may also use ``occ user:delete [user]`` to remove a local Nextcloud user; this removes their user account and their data. diff --git a/admin_manual/configuration_user/user_password_policy.rst b/admin_manual/configuration_user/user_password_policy.rst index 71f97d1a776..9961376be1e 100644 --- a/admin_manual/configuration_user/user_password_policy.rst +++ b/admin_manual/configuration_user/user_password_policy.rst @@ -4,13 +4,13 @@ User password policy A password policy is a set of rules designed to enhance computer security by encouraging users to employ strong passwords and use them properly. -In the security-section of your administrator-settings you can configure +In the security-section of your administrator-settings you can configure * a minimal length of a password. Default is 10 characters. * a password history * a password expiration period * a lockout policy -* to forbid common passwords like 'password' or 'login'. +* to forbid common passwords like 'password' or 'login'. * to enforce upper and lower case characters * to enforce numeric characters * to enforce special characters like ! or : diff --git a/admin_manual/configuration_user/user_provisioning_api.rst b/admin_manual/configuration_user/user_provisioning_api.rst index 977fb881084..5bc62bad7ba 100644 --- a/admin_manual/configuration_user/user_provisioning_api.rst +++ b/admin_manual/configuration_user/user_provisioning_api.rst @@ -2,13 +2,13 @@ User provisioning API ===================== -The Provisioning API application enables a set of APIs that external systems can use to create, -edit, delete and query user attributes, query, set and remove groups, set quota -and query total storage used in Nextcloud. Group admin users can also query -Nextcloud and perform the same functions as an admin for groups they manage. The -API also enables an admin to query for active Nextcloud applications, application -info, and to enable or disable an app remotely. HTTP -requests can be used via a Basic Auth header to perform any of the functions +The Provisioning API application enables a set of APIs that external systems can use to create, +edit, delete and query user attributes, query, set and remove groups, set quota +and query total storage used in Nextcloud. Group admin users can also query +Nextcloud and perform the same functions as an admin for groups they manage. The +API also enables an admin to query for active Nextcloud applications, application +info, and to enable or disable an app remotely. HTTP +requests can be used via a Basic Auth header to perform any of the functions listed above. The Provisioning API app is enabled by default. The base URL for all calls to the Provisioning API is ``https://cloud.example.com/ocs/v1.php/cloud``. diff --git a/admin_manual/declarations/index.rst b/admin_manual/declarations/index.rst index 5707aeb2959..d359b840879 100644 --- a/admin_manual/declarations/index.rst +++ b/admin_manual/declarations/index.rst @@ -1,6 +1,6 @@ ============ Declarations -============ +============ .. toctree:: :maxdepth: 2 diff --git a/admin_manual/desktop/commandline.rst b/admin_manual/desktop/commandline.rst index f26b43398dd..d205c6c1bfc 100644 --- a/admin_manual/desktop/commandline.rst +++ b/admin_manual/desktop/commandline.rst @@ -55,7 +55,7 @@ Other command line switches supported by ``nextcloudcmd`` include the following: Use `password` as the password. ``-n`` - Use`netrc(5)` for login. + Use ``netrc(5)`` for login. ``--non-interactive`` Do not prompt for questions and tries to read $NC_USER and $NC_PASSWORD from the environment. diff --git a/admin_manual/desktop/envvars.rst b/admin_manual/desktop/envvars.rst index 8f9f57eb38a..c214b73cb9e 100644 --- a/admin_manual/desktop/envvars.rst +++ b/admin_manual/desktop/envvars.rst @@ -6,11 +6,11 @@ The behavior of the client can also be controlled using environment variables. T The environment variables are: -- `OWNCLOUD_CHUNK_SIZE` (default: 5242880; 5 MiB) – Specifies the chunk size of uploaded files in bytes. Increasing this value may help with synchronization problems in certain configurations. +- `OWNCLOUD_CHUNK_SIZE` (default: 5242880; 5 MiB) – Specifies the chunk size of uploaded files in bytes. Increasing this value may help with synchronization problems in certain configurations. - `OWNCLOUD_TIMEOUT` (default: 300 s) – The timeout for network connections in seconds. - `OWNCLOUD_CRITICAL_FREE_SPACE_BYTES` (default: 512\*1000\*1000 bytes) - The minimum disk space needed for operation. A fatal error is raised if less free space is available. -- `OWNCLOUD_FREE_SPACE_BYTES` (default: 1000\*1000\*1000 bytes) - Downloads that would reduce the free space below this value are skipped. More information available under the "Low Disk Space" section. -- `OWNCLOUD_MAX_PARALLEL` (default: 6) - Maximum number of parallel jobs. +- `OWNCLOUD_FREE_SPACE_BYTES` (default: 1000\*1000\*1000 bytes) - Downloads that would reduce the free space below this value are skipped. More information available under the "Low Disk Space" section. +- `OWNCLOUD_MAX_PARALLEL` (default: 6) - Maximum number of parallel jobs. - `OWNCLOUD_BLACKLIST_TIME_MIN` (default: 25 s) - Minimum timeout for blacklisted files. - `OWNCLOUD_BLACKLIST_TIME_MAX` (default: 24\*60\*60 s; one day) - Maximum timeout for blacklisted files. - `OWNCLOUD_HTTP2_ENABLED` (default: false) - If the client should communicate with the server using HTTP/2. (This may not be compatible with all server setups) diff --git a/admin_manual/desktop/index.rst b/admin_manual/desktop/index.rst index a45b2d09cc9..ab963668469 100644 --- a/admin_manual/desktop/index.rst +++ b/admin_manual/desktop/index.rst @@ -21,7 +21,7 @@ Your files are always automatically synchronized between your Nextcloud server, commandline accountcommand troubleshooting - + You can find additional information here: * `User manual`_ diff --git a/admin_manual/desktop/massdeployment.rst b/admin_manual/desktop/massdeployment.rst index 54de78842c2..8de90cd0aa1 100644 --- a/admin_manual/desktop/massdeployment.rst +++ b/admin_manual/desktop/massdeployment.rst @@ -18,7 +18,7 @@ The following parameters are supported: ``--localdirpath`` (optional) path where to create a local sync folder when creating an account via command-line. If skipped, then default local sync folder path (/home//Nextcloud for Linux/mac or C://Nextcloud for Windows) will be generated by desktop client. - + ``--isvfsenabled`` (optional) whether to set a VFS or non-VFS folder (1 for 'yes' or 0 for 'no') when creating an account via command-line. Default is 0. diff --git a/admin_manual/desktop/options.rst b/admin_manual/desktop/options.rst index 42c4037bc9c..2a1f3ed0df2 100644 --- a/admin_manual/desktop/options.rst +++ b/admin_manual/desktop/options.rst @@ -2,7 +2,7 @@ Options ======= -You have the option of starting your Nextcloud desktop client with the +You have the option of starting your Nextcloud desktop client with the ``nextcloud`` command. The following options are supported: ``nextcloud -h`` or ``nextcloud --help`` @@ -14,15 +14,15 @@ The other options are: Opens a window displaying log output. ``--logfile`` `` - Write log output to the file specified. To write to stdout, specify `-` + Write log output to the file specified. To write to stdout, specify `-` as the filename. ``--logdir`` `` - Writes each synchronization log output in a new file in the specified + Writes each synchronization log output in a new file in the specified directory. - + ``--logexpire`` `` - Removes logs older than the value specified (in hours). This command is + Removes logs older than the value specified (in hours). This command is used with ``--logdir``. ``--logflush`` diff --git a/admin_manual/exapps_management/AppAPIAndExternalApps.rst b/admin_manual/exapps_management/AppAPIAndExternalApps.rst index 079bab6b978..665b410ec1b 100644 --- a/admin_manual/exapps_management/AppAPIAndExternalApps.rst +++ b/admin_manual/exapps_management/AppAPIAndExternalApps.rst @@ -23,8 +23,8 @@ Setup deploy daemon A Deploy Daemon is the way for Nextcloud to install, communicate with, and control ExApps. .. note:: - If you are using Nextcloud AIO with the "HaRP" or "Docker Socket Proxy" container enabled, a Deploy Daemon will be automatically created and configured to work out-of-the-box. - Otherwise, follow the steps below to set up a Deploy Daemon from the AppAPI admin settings. + If you are using Nextcloud AIO with the "HaRP" or "Docker Socket Proxy" container enabled, a Deploy Daemon will be automatically created and configured to work out-of-the-box. + Otherwise, follow the steps below to set up a Deploy Daemon from the AppAPI admin settings. .. tip:: After registering a Deploy Daemon, use the **Test Deploy** action to verify it is reachable and working. @@ -56,7 +56,7 @@ The ExApps in this configuration or the ExApp server need not expose any ExApp r For different/remote setups, see deployment configuration examples :doc:`here <./DeployConfigurations>`. .. note:: - The existing ExApps can be migrated to use the new HaRP proxy following `this guide `_. + The existing ExApps can be migrated to use the new HaRP proxy following `this guide `_. .. _ai-app_api_dsp: @@ -67,23 +67,23 @@ Docker Socket Proxy 2. Go to the AppAPI admin settings. 3. Click on the "Register Daemon" button. 4. Fill in the required fields: - - ``Name``: unique name of the Deploy daemon - - ``Display name``: the name that will be displayed in the UI - - ``Deployment method``: by default, you will need to choose ``docker_install`` (``manual_install`` is for development or custom use case of manual ExApp installation) - - ``Daemon Host``: hostname/IP address + port of the Deploy daemon - - ``Nextcloud URL``: autofilled with current domain, you might need to change the protocol to http/https depending on your setup - - ``Set as default daemon``: check if you want set new Deploy daemon as default - - ``Enable https``: check if your Deploy daemon (Docker Socket Proxy) is configured with TLS - - Deploy Config: - - ``Network``: Docker network name, depends on your networking setup, enforces to "host" if "Enable https" is checked - - ``HaProxy password``: password for Docker Socket Proxy, if it is configured with TLS - - ``Compute Device``: CPU, CUDA or ROCm, depending on your hardware config on Deploy daemon host machine - - ``Add additional option`` (see :ref:`additional_options_list`): setup additional KEY + VALUE deploy config options + - ``Name``: unique name of the Deploy daemon + - ``Display name``: the name that will be displayed in the UI + - ``Deployment method``: by default, you will need to choose ``docker_install`` (``manual_install`` is for development or custom use case of manual ExApp installation) + - ``Daemon Host``: hostname/IP address + port of the Deploy daemon + - ``Nextcloud URL``: autofilled with current domain, you might need to change the protocol to http/https depending on your setup + - ``Set as default daemon``: check if you want set new Deploy daemon as default + - ``Enable https``: check if your Deploy daemon (Docker Socket Proxy) is configured with TLS + - Deploy Config: + - ``Network``: Docker network name, depends on your networking setup, enforces to "host" if "Enable https" is checked + - ``HaProxy password``: password for Docker Socket Proxy, if it is configured with TLS + - ``Compute Device``: CPU, CUDA or ROCm, depending on your hardware config on Deploy daemon host machine + - ``Add additional option`` (see :ref:`additional_options_list`): setup additional KEY + VALUE deploy config options 5. Click "Check connection" to verify that the configuration is correct. 6. Click "Register" to save the Deploy Daemon configuration. .. note:: - For remote DSP setup, it should expose the ports on the host. + For remote DSP setup, it should expose the ports on the host. .. image:: ./img/app_api_3.png @@ -126,42 +126,42 @@ Frontend requests in case of Docker Socket Proxy: .. mermaid:: - graph LR; - subgraph Browser - A[Frontend] - end + graph LR; + subgraph Browser + A[Frontend] + end - B[Proxy] + B[Proxy] - subgraph Services behind the proxy - C[Docker Socket Proxy] - D[ExApp] - E[Nextcloud Server / AppAPI] - end + subgraph Services behind the proxy + C[Docker Socket Proxy] + D[ExApp] + E[Nextcloud Server / AppAPI] + end - A --> B - B -->|Request to an ExApp| E --Converted to ExApp auth--> D - B -->|All other usual requests| E + A --> B + B -->|Request to an ExApp| E --Converted to ExApp auth--> D + B -->|All other usual requests| E Frontend requests in case of HaRP: .. mermaid:: - graph LR; - subgraph Browser - A[Frontend] - end + graph LR; + subgraph Browser + A[Frontend] + end - B[Proxy] + B[Proxy] - subgraph Services behind the proxy - C[HaRP] - D[ExApp] - E[Nextcloud Server / AppAPI] - end + subgraph Services behind the proxy + C[HaRP] + D[ExApp] + E[Nextcloud Server / AppAPI] + end - B --All other usual requests--> E - A --> B - B --Direct request to an ExApp--> C --Converted to ExApp auth--> D - C --User auth validation--> E + B --All other usual requests--> E + A --> B + B --Direct request to an ExApp--> C --Converted to ExApp auth--> D + C --User auth validation--> E diff --git a/admin_manual/exapps_management/DeployConfigurations.rst b/admin_manual/exapps_management/DeployConfigurations.rst index 0e84fbb0f29..39106c6a284 100644 --- a/admin_manual/exapps_management/DeployConfigurations.rst +++ b/admin_manual/exapps_management/DeployConfigurations.rst @@ -4,8 +4,8 @@ Deployment configurations ========================= Currently, two kinds of application deployments are supported: - * :ref:`Docker Deploy Daemon (Docker Socket Proxy) ` - * :ref:`Docker Deploy Daemon (HaRP) ` + * :ref:`Docker Deploy Daemon (Docker Socket Proxy) ` + * :ref:`Docker Deploy Daemon (HaRP) ` Docker Deploy Daemon -------------------- @@ -14,18 +14,18 @@ Orchestrates the deployment of applications as Docker containers. .. warning:: - | The administrator is responsible for the security actions taken to configure the Docker daemon connected to the Nextcloud instance. - | These schemes are only examples of possible configurations. + | The administrator is responsible for the security actions taken to configure the Docker daemon connected to the Nextcloud instance. + | These schemes are only examples of possible configurations. - | For Docker Deploy Daemon (HaRP), `AppAPI HaRP `_ is required. - | For Docker Deploy Daemon (Docker Socket Proxy), we recommend that you use the `AppAPI Docker Socket Proxy `_ or `AIO Docker Socket Proxy <#nextcloud-in-docker-aio-all-in-one>`_ container for Nextcloud AIO. + | For Docker Deploy Daemon (HaRP), `AppAPI HaRP `_ is required. + | For Docker Deploy Daemon (Docker Socket Proxy), we recommend that you use the `AppAPI Docker Socket Proxy `_ or `AIO Docker Socket Proxy <#nextcloud-in-docker-aio-all-in-one>`_ container for Nextcloud AIO. There are several Docker Daemon Deploy configurations (example schemes): - * Nextcloud and Docker on the **same host** (via socket, DockerSocketProxy, or HaRP) - * Nextcloud on the host and Docker on a **remote** host (via DockerSocketProxy with HTTPS, or HaRP) - * Nextcloud and **ExApps** in the **same Docker network** (via DockerSocketProxy, or HaRP) - * Nextcloud in AIO Docker and **ExApps** in the **same Docker network** (via AIO DockerSocketProxy) + * Nextcloud and Docker on the **same host** (via socket, DockerSocketProxy, or HaRP) + * Nextcloud on the host and Docker on a **remote** host (via DockerSocketProxy with HTTPS, or HaRP) + * Nextcloud and **ExApps** in the **same Docker network** (via DockerSocketProxy, or HaRP) + * Nextcloud in AIO Docker and **ExApps** in the **same Docker network** (via AIO DockerSocketProxy) .. _ai-app_api_ddd-harp: @@ -129,46 +129,46 @@ A setup with the HaRP container itself on the remote is not supported. 3. The FRP generated client certificates should be present in the ``certs`` folder locally. Copy the files ``client.crt``, ``client.key`` and ``ca.crt`` inside the ``certs`` folder to the remote host. 4. Create a folder structure on the remote host: ``mkdir -p certs/frp`` and copy the files ``client.crt``, ``client.key`` and ``ca.crt`` to the ``certs/frp`` folder. -5. Create a new file ``frpc.toml`` with the following contents. +5. Create a new file ``frpc.toml`` with the following contents. - .. code-block:: toml + .. code-block:: toml - # frpc.toml - serverAddr = "your.harp.server.address" # Replace with your HP_FRP_ADDRESS host - serverPort = 8782 # Default port for FRP or the port your reverse proxy listens on - loginFailExit = false # If the FRP (HaRP) server is unavailable, continue trying to log in. + # frpc.toml + serverAddr = "your.harp.server.address" # Replace with your HP_FRP_ADDRESS host + serverPort = 8782 # Default port for FRP or the port your reverse proxy listens on + loginFailExit = false # If the FRP (HaRP) server is unavailable, continue trying to log in. - transport.tls.certFile = "certs/frp/client.crt" - transport.tls.keyFile = "certs/frp/client.key" - transport.tls.trustedCaFile = "certs/frp/ca.crt" - transport.tls.serverName = "harp.nc" # DO NOT CHANGE THIS VALUE + transport.tls.certFile = "certs/frp/client.crt" + transport.tls.keyFile = "certs/frp/client.key" + transport.tls.trustedCaFile = "certs/frp/ca.crt" + transport.tls.serverName = "harp.nc" # DO NOT CHANGE THIS VALUE - metadatas.token = "some_very_secure_password" # HP_SHARED_KEY in quotes + metadatas.token = "some_very_secure_password" # HP_SHARED_KEY in quotes - [[proxies]] - remotePort = 24001 # Unique remotePort for each Docker Engine (range: 24001-24099) - name = "deploy-daemon-1" # Unique name for each Docker Engine - type = "tcp" - [proxies.plugin] - type = "unix_domain_socket" - unixPath = "/var/run/docker.sock" + [[proxies]] + remotePort = 24001 # Unique remotePort for each Docker Engine (range: 24001-24099) + name = "deploy-daemon-1" # Unique name for each Docker Engine + type = "tcp" + [proxies.plugin] + type = "unix_domain_socket" + unixPath = "/var/run/docker.sock" | Make sure to replace the ``your.harp.server.address`` with the actual address of the local host where the HaRP container is running. | You might want to open the port ``8782`` on the local host firewall to allow the remote host to connect to it, | or use a reverse proxy to forward the requests to the HaRP container. An example with nginx is given below. Feel free to adjust the port you want to listen on. The FRP client will connect to this port exposed port. | With the reverse proxy config below, the whole setup would only need the main Nextcloud proxy to be exposed and reachable from the outside world, simplifying the network setup. - .. code-block:: nginx + .. code-block:: nginx - stream { - server { - listen 8782; # Replace with the port you want to listen on - proxy_pass 127.0.0.1:8782; - proxy_protocol off; - proxy_connect_timeout 10s; - proxy_timeout 300s; - } - } + stream { + server { + listen 8782; # Replace with the port you want to listen on + proxy_pass 127.0.0.1:8782; + proxy_protocol off; + proxy_connect_timeout 10s; + proxy_timeout 300s; + } + } 6. Download a release of the FRP client from `the official releases `_ or `our snapshot from here `_. 7. Extract and copy the ``frpc`` binary to an appropriate location on the remote host, e.g. ``/usr/local/bin``. @@ -188,37 +188,37 @@ The simplest configuration is when Nextcloud is installed on the host and Docker .. mermaid:: - stateDiagram-v2 - classDef docker fill: #1f97ee, color: white, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/docker.png) no-repeat center center / contain - classDef nextcloud fill: #006aa3, color: white, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/nextcloud.svg) no-repeat center center / contain - classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px + stateDiagram-v2 + classDef docker fill: #1f97ee, color: white, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/docker.png) no-repeat center center / contain + classDef nextcloud fill: #006aa3, color: white, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/nextcloud.svg) no-repeat center center / contain + classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px - Host + Host - state Host { - Nextcloud --> Daemon : /var/run/docker.sock - Daemon --> Containers + state Host { + Nextcloud --> Daemon : /var/run/docker.sock + Daemon --> Containers - state Containers { - ExApp1 - -- - ExApp2 - -- - ExApp3 - } - } + state Containers { + ExApp1 + -- + ExApp2 + -- + ExApp3 + } + } - class Nextcloud nextcloud - class Daemon docker - class ExApp1 python - class ExApp2 python - class ExApp3 python + class Nextcloud nextcloud + class Daemon docker + class ExApp1 python + class ExApp2 python + class ExApp3 python Suggested config values(template *Custom default*): - 1. Daemon host: ``/var/run/docker.sock`` - 2. HTTPS checkbox: *not supported using docker socket* - 3. Network: ``host`` - 4. HaProxy password: **not supported using raw docker socket, should be empty** + 1. Daemon host: ``/var/run/docker.sock`` + 2. HTTPS checkbox: *not supported using docker socket* + 3. Network: ``host`` + 4. HaProxy password: **not supported using raw docker socket, should be empty** --- @@ -226,44 +226,44 @@ Suggested way to communicate with Docker via `Docker Socket Proxy container DockerSocketProxy: by port - Docker --> Containers - Docker --> DockerSocketProxy : /var/run/docker.sock + state Host { + Nextcloud --> DockerSocketProxy: by port + Docker --> Containers + Docker --> DockerSocketProxy : /var/run/docker.sock - state Containers { - DockerSocketProxy --> ExApp1 - DockerSocketProxy --> ExApp2 - DockerSocketProxy --> ExApp3 - } - } + state Containers { + DockerSocketProxy --> ExApp1 + DockerSocketProxy --> ExApp2 + DockerSocketProxy --> ExApp3 + } + } - class Nextcloud nextcloud - class Docker docker - class ExApp1 python - class ExApp2 python - class ExApp3 python + class Nextcloud nextcloud + class Docker docker + class ExApp1 python + class ExApp2 python + class ExApp3 python Suggested config values(template *Docker Socket Proxy*): - 1. Daemon host: ``localhost:2375`` - Choose **A** or **B** option: - A. Docker Socket Proxy should be deployed with ``network=host`` and ``BIND_ADDRESS=127.0.0.1`` - B. Docker Socket Proxy should be deployed with ``network=bridge`` and it's port should be published to host's 127.0.0.1(e.g. **-p 127.0.0.1:2375:2375**) - 2. HTTPS checkbox: **disabled** - 3. Network: ``host`` - 4. HaProxy password: **should not be empty** + 1. Daemon host: ``localhost:2375`` + Choose **A** or **B** option: + A. Docker Socket Proxy should be deployed with ``network=host`` and ``BIND_ADDRESS=127.0.0.1`` + B. Docker Socket Proxy should be deployed with ``network=bridge`` and it's port should be published to host's 127.0.0.1(e.g. **-p 127.0.0.1:2375:2375**) + 2. HTTPS checkbox: **disabled** + 3. Network: ``host`` + 4. HaProxy password: **should not be empty** .. warning:: - Be careful with option ``A``, by default **Docker Socket Proxy** binds to ``*`` if ``BIND_ADDRESS`` is not specified during container creation. - Check opened ports after finishing configuration. + Be careful with option ``A``, by default **Docker Socket Proxy** binds to ``*`` if ``BIND_ADDRESS`` is not specified during container creation. + Check opened ports after finishing configuration. Docker on a remote host @@ -277,42 +277,42 @@ In this case, the AppAPI uses a Docker Socket Proxy deployed on remote host to a .. mermaid:: - stateDiagram-v2 - classDef docker fill: #1f97ee, color: white, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/docker.png) no-repeat center center / contain - classDef nextcloud fill: #006aa3, color: white, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/nextcloud.svg) no-repeat center center / contain - classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px + stateDiagram-v2 + classDef docker fill: #1f97ee, color: white, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/docker.png) no-repeat center center / contain + classDef nextcloud fill: #006aa3, color: white, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/nextcloud.svg) no-repeat center center / contain + classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px - Direction LR + Direction LR - Host1 --> Host2 : by port + Host1 --> Host2 : by port - state Host1 { - Nextcloud - } + state Host1 { + Nextcloud + } - state Host2 { - [*] --> DockerSocketProxy : by port - Daemon --> Containers + state Host2 { + [*] --> DockerSocketProxy : by port + Daemon --> Containers - state Containers { - [*] --> DockerSocketProxy : /var/run/docker.sock - DockerSocketProxy --> ExApp1 - DockerSocketProxy --> ExApp2 - DockerSocketProxy --> ExApp3 - } - } + state Containers { + [*] --> DockerSocketProxy : /var/run/docker.sock + DockerSocketProxy --> ExApp1 + DockerSocketProxy --> ExApp2 + DockerSocketProxy --> ExApp3 + } + } - class Nextcloud nextcloud - class Daemon docker - class ExApp1 python - class ExApp2 python - class ExApp3 python + class Nextcloud nextcloud + class Daemon docker + class ExApp1 python + class ExApp2 python + class ExApp3 python Suggested config values(template *Docker Socket Proxy*): - 1. Daemon host: ADDRESS_OF_REMOTE_MACHINE (e.g. **server_name.com:2375**) - 2. HTTPS checkbox: ``enabled`` - 3. Network: ``host`` - 4. HaProxy password: **should not be empty** + 1. Daemon host: ADDRESS_OF_REMOTE_MACHINE (e.g. **server_name.com:2375**) + 2. HTTPS checkbox: ``enabled`` + 3. Network: ``host`` + 4. HaProxy password: **should not be empty** NC & ExApps in the same Docker ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -323,41 +323,41 @@ Suggested way to communicate with Docker: via ``docker-socket-proxy``. .. mermaid:: - stateDiagram-v2 - classDef docker fill: #1f97ee, color: white, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/docker.png) no-repeat center center / contain - classDef nextcloud fill: #006aa3, color: white, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/nextcloud.svg) no-repeat center center / contain - classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px + stateDiagram-v2 + classDef docker fill: #1f97ee, color: white, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/docker.png) no-repeat center center / contain + classDef nextcloud fill: #006aa3, color: white, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/nextcloud.svg) no-repeat center center / contain + classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px - Host + Host - state Host { - Daemon --> Containers + state Host { + Daemon --> Containers - state Containers { - [*] --> DockerSocketProxy : /var/run/docker.sock - Nextcloud --> DockerSocketProxy: by port - -- - DockerSocketProxy --> ExApp1 - DockerSocketProxy --> ExApp2 - } - } + state Containers { + [*] --> DockerSocketProxy : /var/run/docker.sock + Nextcloud --> DockerSocketProxy: by port + -- + DockerSocketProxy --> ExApp1 + DockerSocketProxy --> ExApp2 + } + } - class Nextcloud nextcloud - class Daemon docker - class ExApp1 python - class ExApp2 python - class ExApp3 python + class Nextcloud nextcloud + class Daemon docker + class ExApp1 python + class ExApp2 python + class ExApp3 python Suggested config values(template *Docker Socket Proxy*): - 1. Daemon host: nextcloud-appapi-dsp:2375 - 2. HTTPS checkbox: ``disabled`` - 3. Network: `user defined network `_ - 4. HaProxy password: **should not be empty** + 1. Daemon host: nextcloud-appapi-dsp:2375 + 2. HTTPS checkbox: ``disabled`` + 3. Network: `user defined network `_ + 4. HaProxy password: **should not be empty** .. note:: - Network **should not be the default docker's bridge** as it does not support DNS resolving by container names. + Network **should not be the default docker's bridge** as it does not support DNS resolving by container names. - This means that **Docker Socket Proxy**, **Nextcloud** and **ExApps** containers should all be in the same docker network, different from the default **bridge**. + This means that **Docker Socket Proxy**, **Nextcloud** and **ExApps** containers should all be in the same docker network, different from the default **bridge**. .. _nextcloud-in-docker-aio-all-in-one: @@ -369,45 +369,45 @@ In the case of AppAPI in Docker AIO setup (installed in Nextcloud container). .. note:: - AIO Docker Socket Proxy container must be enabled. + AIO Docker Socket Proxy container must be enabled. .. mermaid:: - stateDiagram-v2 - classDef docker fill: #1f97ee, color: white, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/docker.png) no-repeat center center / contain - classDef docker2 fill: #1f97ee, color: white, font-size: 20px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/docker.png) no-repeat center center / contain - classDef nextcloud fill: #006aa3, color: white, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/nextcloud.svg) no-repeat center center / contain - classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px - - Host - - state Host { - Daemon --> Containers - - state Containers { - [*] --> NextcloudAIOMasterContainer : /var/run/docker.sock - [*] --> DockerSocketProxy : /var/run/docker.sock - NextcloudAIOMasterContainer --> Nextcloud - AppAPI --> Nextcloud : installed in - Nextcloud --> DockerSocketProxy - DockerSocketProxy --> ExApp1 - DockerSocketProxy --> ExApp2 - DockerSocketProxy --> ExApp3 - } - } - - class Nextcloud nextcloud - class Daemon docker - class Daemon2 docker2 - class ExApp1 python - class ExApp2 python - class ExApp3 python + stateDiagram-v2 + classDef docker fill: #1f97ee, color: white, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/docker.png) no-repeat center center / contain + classDef docker2 fill: #1f97ee, color: white, font-size: 20px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/docker.png) no-repeat center center / contain + classDef nextcloud fill: #006aa3, color: white, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/documentation/master/admin_manual/exapps_management/img/nextcloud.svg) no-repeat center center / contain + classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px + + Host + + state Host { + Daemon --> Containers + + state Containers { + [*] --> NextcloudAIOMasterContainer : /var/run/docker.sock + [*] --> DockerSocketProxy : /var/run/docker.sock + NextcloudAIOMasterContainer --> Nextcloud + AppAPI --> Nextcloud : installed in + Nextcloud --> DockerSocketProxy + DockerSocketProxy --> ExApp1 + DockerSocketProxy --> ExApp2 + DockerSocketProxy --> ExApp3 + } + } + + class Nextcloud nextcloud + class Daemon docker + class Daemon2 docker2 + class ExApp1 python + class ExApp2 python + class ExApp3 python AppAPI will automatically create the default DaemonConfig for AIO Docker Socket Proxy in order to use it as an orchestrator to create ExApp containers. .. note:: - Default DaemonConfig will be created only if the default DaemonConfig is not already registered. + Default DaemonConfig will be created only if the default DaemonConfig is not already registered. Default AIO Deploy Daemon (Docker Socket Proxy) @@ -444,9 +444,9 @@ It has the prototype: .. code-block:: php - public function resolveExAppUrl( - string $appId, string $protocol, string $host, array $deployConfig, int $port, array &$auth - ) {} + public function resolveExAppUrl( + string $appId, string $protocol, string $host, array $deployConfig, int $port, array &$auth + ) {} where: @@ -458,43 +458,43 @@ where: .. note:: - Applies only to Docker Socket Proxy. + Applies only to Docker Socket Proxy. - The optional additional parameter *OVERRIDE_APP_HOST* can be used to - override the host that will be used for ExApp binding. + The optional additional parameter *OVERRIDE_APP_HOST* can be used to + override the host that will be used for ExApp binding. - It can be ``0.0.0.0`` in some specific configurations, when VPN is used - or both Nextcloud instance and ExApps are one the same physical machine but different virtual environments. + It can be ``0.0.0.0`` in some specific configurations, when VPN is used + or both Nextcloud instance and ExApps are one the same physical machine but different virtual environments. - Also you can specify something like ``10.10.2.5`` and in this case ``ExApp`` will try to bind to that address and - AppAPI will try to send request s directly to this address assuming that ExApp itself bound on it. + Also you can specify something like ``10.10.2.5`` and in this case ``ExApp`` will try to bind to that address and + AppAPI will try to send request s directly to this address assuming that ExApp itself bound on it. The simplest implementation is in the **Manual-Install** deploy type: .. code-block:: php - public function resolveExAppUrl( - string $appId, string $protocol, string $host, array $deployConfig, int $port, array &$auth - ): string { - if (boolval($deployConfig['harp'] ?? false)) { - $url = rtrim($deployConfig['nextcloud_url'], '/'); - if (str_ends_with($url, '/index.php')) { - $url = substr($url, 0, -10); - } - return sprintf('%s/exapps/%s', $url, $appId); - } - - $auth = []; - if (isset($deployConfig['additional_options']['OVERRIDE_APP_HOST']) && - $deployConfig['additional_options']['OVERRIDE_APP_HOST'] !== '' - ) { - $wideNetworkAddresses = ['0.0.0.0', '127.0.0.1', '::', '::1']; - if (!in_array($deployConfig['additional_options']['OVERRIDE_APP_HOST'], $wideNetworkAddresses)) { - $host = $deployConfig['additional_options']['OVERRIDE_APP_HOST']; - } - } - return sprintf('%s://%s:%s', $protocol, $host, $port); - } + public function resolveExAppUrl( + string $appId, string $protocol, string $host, array $deployConfig, int $port, array &$auth + ): string { + if (boolval($deployConfig['harp'] ?? false)) { + $url = rtrim($deployConfig['nextcloud_url'], '/'); + if (str_ends_with($url, '/index.php')) { + $url = substr($url, 0, -10); + } + return sprintf('%s/exapps/%s', $url, $appId); + } + + $auth = []; + if (isset($deployConfig['additional_options']['OVERRIDE_APP_HOST']) && + $deployConfig['additional_options']['OVERRIDE_APP_HOST'] !== '' + ) { + $wideNetworkAddresses = ['0.0.0.0', '127.0.0.1', '::', '::1']; + if (!in_array($deployConfig['additional_options']['OVERRIDE_APP_HOST'], $wideNetworkAddresses)) { + $host = $deployConfig['additional_options']['OVERRIDE_APP_HOST']; + } + } + return sprintf('%s://%s:%s', $protocol, $host, $port); + } | Here we see that AppAPI sends requests to the **host**:**port** specified during daemon creation for manual-install without HaRP. | But it exclusively uses the ``http(s)://nextcloud.example.tld/exapps/`` route for manual deployments using the HaRP proxy. ``http(s)://nextcloud.example.tld`` is the Nextcloud URL specified in the daemon config. Take care to configure the ``/exapps/`` route in your reverse proxy accordingly if your Nextcloud instance is on a subpath ``https://nextcloud.example.tld/nextcloud``. See `Configuring Your Reverse Proxy `_ in the HaRP readme for examples. @@ -503,43 +503,43 @@ Now, let's take a look at the Docker Daemon implementation of ``resolveExAppUrl` .. code-block:: php - public function resolveExAppUrl( - string $appId, string $protocol, string $host, array $deployConfig, int $port, array &$auth - ): string { - if (boolval($deployConfig['harp'] ?? false)) { - $url = rtrim($deployConfig['nextcloud_url'], '/'); - if (str_ends_with($url, '/index.php')) { - $url = substr($url, 0, -10); - } - return sprintf('%s/exapps/%s', $url, $appId); - } - - $auth = []; - if (isset($deployConfig['additional_options']['OVERRIDE_APP_HOST']) && - $deployConfig['additional_options']['OVERRIDE_APP_HOST'] !== '' - ) { - $wideNetworkAddresses = ['0.0.0.0', '127.0.0.1', '::', '::1']; - if (!in_array($deployConfig['additional_options']['OVERRIDE_APP_HOST'], $wideNetworkAddresses)) { - return sprintf( - '%s://%s:%s', $protocol, $deployConfig['additional_options']['OVERRIDE_APP_HOST'], $port - ); - } - } - $host = explode(':', $host)[0]; - if ($protocol == 'https') { - $exAppHost = $host; - } elseif (isset($deployConfig['net']) && $deployConfig['net'] === 'host') { - $exAppHost = 'localhost'; - } else { - $exAppHost = $appId; - } - if ($protocol == 'https' && isset($deployConfig['haproxy_password']) && $deployConfig['haproxy_password'] !== '') { - // we only set haproxy auth for remote installations, when all requests come through HaProxy. - $haproxyPass = $this->crypto->decrypt($deployConfig['haproxy_password']); - $auth = [self::APP_API_HAPROXY_USER, $haproxyPass]; - } - return sprintf('%s://%s:%s', $protocol, $exAppHost, $port); - } + public function resolveExAppUrl( + string $appId, string $protocol, string $host, array $deployConfig, int $port, array &$auth + ): string { + if (boolval($deployConfig['harp'] ?? false)) { + $url = rtrim($deployConfig['nextcloud_url'], '/'); + if (str_ends_with($url, '/index.php')) { + $url = substr($url, 0, -10); + } + return sprintf('%s/exapps/%s', $url, $appId); + } + + $auth = []; + if (isset($deployConfig['additional_options']['OVERRIDE_APP_HOST']) && + $deployConfig['additional_options']['OVERRIDE_APP_HOST'] !== '' + ) { + $wideNetworkAddresses = ['0.0.0.0', '127.0.0.1', '::', '::1']; + if (!in_array($deployConfig['additional_options']['OVERRIDE_APP_HOST'], $wideNetworkAddresses)) { + return sprintf( + '%s://%s:%s', $protocol, $deployConfig['additional_options']['OVERRIDE_APP_HOST'], $port + ); + } + } + $host = explode(':', $host)[0]; + if ($protocol == 'https') { + $exAppHost = $host; + } elseif (isset($deployConfig['net']) && $deployConfig['net'] === 'host') { + $exAppHost = 'localhost'; + } else { + $exAppHost = $appId; + } + if ($protocol == 'https' && isset($deployConfig['haproxy_password']) && $deployConfig['haproxy_password'] !== '') { + // we only set haproxy auth for remote installations, when all requests come through HaProxy. + $haproxyPass = $this->crypto->decrypt($deployConfig['haproxy_password']); + $auth = [self::APP_API_HAPROXY_USER, $haproxyPass]; + } + return sprintf('%s://%s:%s', $protocol, $exAppHost, $port); + } The route for HaRP setups remain the same here as in the previous example. All the requests are sent to the Nextcloud URL with the ``/exapps/`` route. diff --git a/admin_manual/exapps_management/ManagingDeployDaemons.rst b/admin_manual/exapps_management/ManagingDeployDaemons.rst index 7cef19e55ad..b3712575cc6 100644 --- a/admin_manual/exapps_management/ManagingDeployDaemons.rst +++ b/admin_manual/exapps_management/ManagingDeployDaemons.rst @@ -47,49 +47,49 @@ Usage Examples * Register a HaRP deploy daemon within the ``nextcloud`` docker network, with the ``appapi-harp`` container as the host and the ``appapi-harp:8782`` as the FRP server address. This can be paired with a HaRP container running in the same network. - .. code-block:: bash + .. code-block:: bash - occ app_api:daemon:register harp_proxy_docker "Harp Proxy (Docker)" "docker-install" "http" "appapi-harp:8780" "http://nextcloud.local" --net nextcloud --harp --harp_frp_address "appapi-harp:8782" --harp_shared_key "some_very_secure_password" --set-default --compute_device=cuda + occ app_api:daemon:register harp_proxy_docker "Harp Proxy (Docker)" "docker-install" "http" "appapi-harp:8780" "http://nextcloud.local" --net nextcloud --harp --harp_frp_address "appapi-harp:8782" --harp_shared_key "some_very_secure_password" --set-default --compute_device=cuda * Register a HaRP deploy daemon with the ``localhost`` as the host and the ``localhost:8782`` as the FRP server address. This can be paired with a HaRP container running in the host network mode or that has exposed the ports ``8780`` and ``8782`` to the host. - .. code-block:: bash + .. code-block:: bash - app_api:daemon:register harp_proxy_host "Harp Proxy (Host)" "docker-install" "http" "localhost:8780" "http://nextcloud.local" --harp --harp_frp_address "localhost:8782" --harp_shared_key "some_very_secure_password" --set-default --compute_device=cuda + app_api:daemon:register harp_proxy_host "Harp Proxy (Host)" "docker-install" "http" "localhost:8780" "http://nextcloud.local" --harp --harp_frp_address "localhost:8782" --harp_shared_key "some_very_secure_password" --set-default --compute_device=cuda * Register a manual install deploy daemon with HaRP support. This can be paired with a HaRP container running in the same network. The HaRP container need not have access to a docker socket or any other ports exposed to the host. It will not create docker containers of the ExApps but will only proxy the requests to the ExApp process manually launched by the user. - .. note:: - | The ExApp process should have a FRP Client (frpc) running in the same network as the HaRP container or should be able to connect to the ports exposed by the HaRP container. - | If the communication has to go without the FRP client, the ``--harp_exapp_direct`` flag should be provided. The localhost IP address is always used as the host in this case for manual deployments and ``OVERRIDE_APP_HOST`` or the ```` is used for ExApp deployments. Take care not to use the host network mode or the default bridge network for this. + .. note:: + | The ExApp process should have a FRP Client (frpc) running in the same network as the HaRP container or should be able to connect to the ports exposed by the HaRP container. + | If the communication has to go without the FRP client, the ``--harp_exapp_direct`` flag should be provided. The localhost IP address is always used as the host in this case for manual deployments and ``OVERRIDE_APP_HOST`` or the ```` is used for ExApp deployments. Take care not to use the host network mode or the default bridge network for this. - .. code-block:: bash + .. code-block:: bash - app_api:daemon:register manual_install_harp "Harp Manual Install" "manual-install" "http" "appapi-harp:8780" "http://nextcloud.local" --net nextcloud --harp --harp_frp_address "appapi-harp:8782" --harp_shared_key "some_very_secure_password" + app_api:daemon:register manual_install_harp "Harp Manual Install" "manual-install" "http" "appapi-harp:8780" "http://nextcloud.local" --net nextcloud --harp --harp_frp_address "appapi-harp:8782" --harp_shared_key "some_very_secure_password" * Register a Docker Socket Proxy deploy daemon with the ``nextcloud-appapi-dsp:2375`` as the host and the ``nextcloud`` docker network. This can be paired with a Docker Socket Proxy container running in the same network with the default port ``2375``. - .. code-block:: bash + .. code-block:: bash - app_api:daemon:register docker_install "Docker Socket Proxy" "docker-install" "http" "nextcloud-appapi-dsp:2375" "http://nextcloud.local" --net=nextcloud --set-default --compute_device=cuda + app_api:daemon:register docker_install "Docker Socket Proxy" "docker-install" "http" "nextcloud-appapi-dsp:2375" "http://nextcloud.local" --net=nextcloud --set-default --compute_device=cuda * Register a manual deploy daemon with ``host.docker.internal`` as the host used to connect to the ExApps. - .. code-block:: bash + .. code-block:: bash - app_api:daemon:register manual_install "Manual Install" "manual-install" "http" null "http://nextcloud.local" + app_api:daemon:register manual_install "Manual Install" "manual-install" "http" null "http://nextcloud.local" * Register a local docker deploy daemon with the ``/var/run/docker.sock`` as the socket and the host, and the ``nextcloud`` docker network. This does not need a Docker Socket Proxy container. The compute device used by this daemon is ``CPU``. - .. code-block:: bash + .. code-block:: bash - app_api:daemon:register local_docker "Docker Local" "docker-install" "http" "/var/run/docker.sock" "http://nextcloud.local" --net=nextcloud + app_api:daemon:register local_docker "Docker Local" "docker-install" "http" "/var/run/docker.sock" "http://nextcloud.local" --net=nextcloud * Register a local docker deploy daemon with the ``/var/run/docker.sock`` as the socket and the host, and the ``nextcloud`` docker network. This does not need a Docker Socket Proxy container. The compute device used by this daemon is ``CUDA`` (NVIDIA). - .. code-block:: bash + .. code-block:: bash - app_api:daemon:register local_docker "Docker Local" "docker-install" "http" "/var/run/docker.sock" "http://nextcloud.local" --net=nextcloud --set-default --compute_device=cuda + app_api:daemon:register local_docker "Docker Local" "docker-install" "http" "/var/run/docker.sock" "http://nextcloud.local" --net=nextcloud --set-default --compute_device=cuda DeployConfig @@ -100,32 +100,32 @@ ExApp container. .. code-block:: json - { - "net": "host", - "nextcloud_url": "https://nextcloud.local", - "haproxy_password": "some_secure_password", - "computeDevice": { - "id": "cuda", - "name": "CUDA (NVIDIA)", - }, - "harp": { - "frp_address": "localhost:8782", - "docker_socket_port": "24000", - "exapp_direct": false - } - } + { + "net": "host", + "nextcloud_url": "https://nextcloud.local", + "haproxy_password": "some_secure_password", + "computeDevice": { + "id": "cuda", + "name": "CUDA (NVIDIA)", + }, + "harp": { + "frp_address": "localhost:8782", + "docker_socket_port": "24000", + "exapp_direct": false + } + } DeployConfig options ******************** - * ``net`` **[required]** - network name to bind docker container to (default: ``host``) - * ``nextcloud_url`` **[required]** - Nextcloud URL (e.g. ``https://nextcloud.local``) - * ``haproxy_password`` *[optional]* - password for AppAPI Docker Socket Proxy - * ``computeDevice`` *[optional]* - Compute device to attach to the daemon (e.g. ``{ "id": "cuda", "label": "CUDA (NVIDIA)" }``) - * ``harp`` *[optional]* - HaRP options, can be ``null`` in case of non-HaRP setups - * ``frp_address`` *[optional]* - [host]:[port] of the HaRP FRP server, default host is same as HaRP host and port is 8782 - * ``docker_socket_port`` *[optional]* - 'remotePort' of the FRP client of the remote docker socket proxy. There is one included in the harp container so this can be skipped for default setups. [default: "24000"] - * ``exapp_direct`` *[optional]* - Flag for the advanced setups only. Disables the FRP tunnel between ExApps and HaRP. + * ``net`` **[required]** - network name to bind docker container to (default: ``host``) + * ``nextcloud_url`` **[required]** - Nextcloud URL (e.g. ``https://nextcloud.local``) + * ``haproxy_password`` *[optional]* - password for AppAPI Docker Socket Proxy + * ``computeDevice`` *[optional]* - Compute device to attach to the daemon (e.g. ``{ "id": "cuda", "label": "CUDA (NVIDIA)" }``) + * ``harp`` *[optional]* - HaRP options, can be ``null`` in case of non-HaRP setups + * ``frp_address`` *[optional]* - [host]:[port] of the HaRP FRP server, default host is same as HaRP host and port is 8782 + * ``docker_socket_port`` *[optional]* - 'remotePort' of the FRP client of the remote docker socket proxy. There is one included in the harp container so this can be skipped for default setups. [default: "24000"] + * ``exapp_direct`` *[optional]* - Flag for the advanced setups only. Disables the FRP tunnel between ExApps and HaRP. Unregister ---------- @@ -158,4 +158,4 @@ Additional options Currently, the following options are available: - - ``OVERRIDE_APP_HOST`` - can be used to override the host that will be used for ExApp binding (not passed to ExApp container envs) + - ``OVERRIDE_APP_HOST`` - can be used to override the host that will be used for ExApp binding (not passed to ExApp container envs) diff --git a/admin_manual/exapps_management/ManagingExApps.rst b/admin_manual/exapps_management/ManagingExApps.rst index c2e954c96a2..10eaffa649b 100644 --- a/admin_manual/exapps_management/ManagingExApps.rst +++ b/admin_manual/exapps_management/ManagingExApps.rst @@ -61,8 +61,8 @@ Options ******* * ``--rm-data`` *[optional]* - remove ExApp persistent storage (data volume) - * ``--force`` *[optional]* - continue removal even if some error occurs - * ``--silent`` *[optional]* - print a minimum of information, display only some errors, if any + * ``--force`` *[optional]* - continue removal even if some error occurs + * ``--silent`` *[optional]* - print a minimum of information, display only some errors, if any Update ------ diff --git a/admin_manual/file_workflows/configuration.rst b/admin_manual/file_workflows/configuration.rst index 4479aeb2988..e00932f6890 100644 --- a/admin_manual/file_workflows/configuration.rst +++ b/admin_manual/file_workflows/configuration.rst @@ -4,4 +4,4 @@ Flow configuration Administrators can disable user flows since they can have an impact on the performance of a system and you might not want to give users the ability to define their own flows rules. They can be disabled through the following command:: - occ config:app:set workflowengine user_scope_disabled --value yes \ No newline at end of file + occ config:app:set workflowengine user_scope_disabled --value yes diff --git a/admin_manual/gdpr/cookies.rst b/admin_manual/gdpr/cookies.rst index 74d34163abe..ded20c2cee1 100644 --- a/admin_manual/gdpr/cookies.rst +++ b/admin_manual/gdpr/cookies.rst @@ -17,15 +17,15 @@ Cookies stored by Nextcloud Cookie Data Stored Lifetime ==================== ==================================== ================ Session cookie - session ID 24 minutes - - secret token (used to decrypt + - secret token (used to decrypt the session on the server) Same-site cookies no user-related data are stored, forever all same-site cookies are the same - for all users on all Nextcloud + for all users on all Nextcloud instances Remember-me cookie - user id 15 days (can be - original session id configured) - - remember token + - remember token ==================== ==================================== ================ The same-site cookies are used to determine how a request reaches the Nextcloud server. We use them to prevent CSRF attacks. No identifiable information is stored in those. diff --git a/admin_manual/gdpr/index.rst b/admin_manual/gdpr/index.rst index 8d1b924b738..140c45fb0b9 100644 --- a/admin_manual/gdpr/index.rst +++ b/admin_manual/gdpr/index.rst @@ -1,6 +1,6 @@ =============== GDPR-compliance -=============== +=============== .. toctree:: :maxdepth: 2 diff --git a/admin_manual/index.rst b/admin_manual/index.rst index 04714364f21..507ffc45c2d 100644 --- a/admin_manual/index.rst +++ b/admin_manual/index.rst @@ -4,7 +4,7 @@ Introduction **Welcome to the Nextcloud Server Administration Guide.** -This guide explains how to perform administrative tasks in Nextcloud, a highly versatile and scalable open-source platform for file synchronization and content collaboration. +This guide explains how to perform administrative tasks in Nextcloud, a highly versatile and scalable open-source platform for file synchronization and content collaboration. With over 400,000 deployments, Nextcloud can run on a simple two-user Raspberry Pi or scale to support global, distributed installations serving tens of millions of users. It can be deployed on-premises, in private or public clouds, or in hybrid environments. Supported by a large and growing community, Nextcloud is available in more than 60 languages. @@ -77,17 +77,17 @@ To get started, see the Installation section. The development of the Nextcloud platform is a cooperative endeavor overseen by the core maintainers -- primarily employed by Nextcloud GmbH -- along with thousands of - partners, providers, collaborators, project members, and + partners, providers, collaborators, project members, and community participants. - The Nextcloud community includes everyone -- from individual + The Nextcloud community includes everyone -- from individual users and independent developers to large organizations. - Community members share and discuss their experiences with - the platform every day. They suggest improvements, - collaborate on design, write code, create documentation, - test for bugs, triage bug reports and enhancement ideas, - support others, improve translations, and help fund and - organize the logistics of a project this size. Most - importantly, they use Nextcloud in their daily lives and + Community members share and discuss their experiences with + the platform every day. They suggest improvements, + collaborate on design, write code, create documentation, + test for bugs, triage bug reports and enhancement ideas, + support others, improve translations, and help fund and + organize the logistics of a project this size. Most + importantly, they use Nextcloud in their daily lives and work. diff --git a/admin_manual/installation/command_line_installation.rst b/admin_manual/installation/command_line_installation.rst index a1b89ad6f2e..0e31cf0edac 100644 --- a/admin_manual/installation/command_line_installation.rst +++ b/admin_manual/installation/command_line_installation.rst @@ -2,20 +2,20 @@ Installing from command line ============================ -It is now possible to install Nextcloud entirely from the command line. This is -convenient for scripted operations, headless servers, and sysadmins who prefer -the command line. There are three stages to installing Nextcloud via the command +It is now possible to install Nextcloud entirely from the command line. This is +convenient for scripted operations, headless servers, and sysadmins who prefer +the command line. There are three stages to installing Nextcloud via the command line: 1. Download the Nextcloud code and unpack the tarball in the appropriate directories. (See :doc:`source_installation`.) -2. Change the ownership of your ``nextcloud`` directory to your HTTP user, like -this example for Debian/Ubuntu. You must run ``occ`` as your HTTP user; see +2. Change the ownership of your ``nextcloud`` directory to your HTTP user, like +this example for Debian/Ubuntu. You must run ``occ`` as your HTTP user; see :ref:`http_user_label`:: $ sudo chown -R www-data:www-data /var/www/nextcloud/ -3. Use the ``occ`` command to complete your installation. This takes the place +3. Use the ``occ`` command to complete your installation. This takes the place of running the graphical Installation Wizard:: $ cd /var/www/nextcloud/ @@ -23,9 +23,9 @@ of running the graphical Installation Wizard:: --database 'mysql' --database-name 'nextcloud' \ --database-user 'nextcloud' --database-pass 'password' \ --admin-user 'admin' --admin-pass 'password' - -Note that you must change to the root Nextcloud directory, as in the example -above, to run ``occ maintenance:install``, or the installation will fail with + +Note that you must change to the root Nextcloud directory, as in the example +above, to run ``occ maintenance:install``, or the installation will fail with a PHP fatal error message. Supported databases are:: @@ -34,6 +34,6 @@ Supported databases are:: - mysql (MySQL/MariaDB) - pgsql (PostgreSQL) - oci (Oracle currently only possible if you contact us at https://nextcloud.com/enterprise as part of a subscription) - + See :ref:`command_line_installation_label` for more information. diff --git a/admin_manual/installation/example_centos.rst b/admin_manual/installation/example_centos.rst index 02179f272ed..0580136aa45 100644 --- a/admin_manual/installation/example_centos.rst +++ b/admin_manual/installation/example_centos.rst @@ -28,7 +28,7 @@ Apache :: dnf install -y httpd - + Create a virtualhost in ``/etc/httpd/conf.d/nextcloud.conf`` and add the following content to it: :: @@ -48,8 +48,8 @@ Create a virtualhost in ``/etc/httpd/conf.d/nextcloud.conf`` and add the followi - - + + See :ref:`apache_configuration_label` for further details. Make sure the apache web service is enabled and started:: @@ -60,9 +60,9 @@ Make sure the apache web service is enabled and started:: PHP --- -.. note:: CentOS 8 doesn't come with packages for the redis and imagick php extensions. - Those can either be installed using pecl. Apart from the official PHP packages there are 3rdparty - repositories available at ``https://rpms.remirepo.net``. Using remirepo you can also install the +.. note:: CentOS 8 doesn't come with packages for the redis and imagick php extensions. + Those can either be installed using pecl. Apart from the official PHP packages there are 3rdparty + repositories available at ``https://rpms.remirepo.net``. Using remirepo you can also install the latest PHP version instead of the standard shipped one. @@ -110,7 +110,7 @@ Installing optional modules redis/imagick :: dnf install -y php-redis php-imagick - + Database -------- @@ -128,7 +128,7 @@ Improve MariaDB security.:: mysql_secure_installation -After you have done this, make sure you create a database with a username and password so that +After you have done this, make sure you create a database with a username and password so that Nextcloud will have access to it. For further details on database setup and configuration, see the :doc:`../configuration_database/linux_database_configuration` documentation. diff --git a/admin_manual/installation/example_openbsd.rst b/admin_manual/installation/example_openbsd.rst index 0773ec42e23..4aa21d9b927 100644 --- a/admin_manual/installation/example_openbsd.rst +++ b/admin_manual/installation/example_openbsd.rst @@ -12,10 +12,10 @@ In this install tutorial we will be deploying Nextcloud on a minimal OpenBSD wit From a base installed OpenBSD system you can just do:: # pkg_add nextcloud - + The extra packages:: - # pkg_add postgresql-server redis pecl82-redis php-pdo_pgsql + # pkg_add postgresql-server redis pecl82-redis php-pdo_pgsql This will take care of your dependencies and give you the options to choose which PHP version do you want. @@ -28,62 +28,62 @@ Create a virtualhost in ``/etc/httpd.conf`` and add the following content to it: server "domain.tld" { listen on egress tls port 443 hsts { - max-age 15768000 - preload - subdomains - } - - tls { - certificate "/etc/ssl/domain.tld_fullchain.pem" - key "/etc/ssl/private/domain.tld_private.pem" - } - - # Set max upload size to 513M (in bytes) - connection max request body 537919488 - connection max requests 1000 - connection request timeout 3600 - connection timeout 3600 - - root "/nextcloud" - directory index "index.php" - - # Ensure that no '*.php*' files can be fetched from these directories - location "/config/*" { - block drop - } - - location "/data/*" { - block drop - } - - # Note that this matches "*.php*" anywhere in the request path. - location "/nextcloud/*.php*" { - fastcgi socket "/run/php-fpm.sock" - } - - location "/apps/*" { - pass - } - - location "/core/*" { - pass - } - - location "/.well-known/carddav" { - block return 301 "https://$SERVER_NAME/remote.php/dav" - } - - location "/.well-known/caldav" { - block return 301 "https://$SERVER_NAME/remote.php/dav" - } - - location "/.well-known/webfinger" { - block return 301 "https://$SERVER_NAME/public.php?service=webfinger" - } - - location match "/ocs-provider/*" { - pass - } + max-age 15768000 + preload + subdomains + } + + tls { + certificate "/etc/ssl/domain.tld_fullchain.pem" + key "/etc/ssl/private/domain.tld_private.pem" + } + + # Set max upload size to 513M (in bytes) + connection max request body 537919488 + connection max requests 1000 + connection request timeout 3600 + connection timeout 3600 + + root "/nextcloud" + directory index "index.php" + + # Ensure that no '*.php*' files can be fetched from these directories + location "/config/*" { + block drop + } + + location "/data/*" { + block drop + } + + # Note that this matches "*.php*" anywhere in the request path. + location "/nextcloud/*.php*" { + fastcgi socket "/run/php-fpm.sock" + } + + location "/apps/*" { + pass + } + + location "/core/*" { + pass + } + + location "/.well-known/carddav" { + block return 301 "https://$SERVER_NAME/remote.php/dav" + } + + location "/.well-known/caldav" { + block return 301 "https://$SERVER_NAME/remote.php/dav" + } + + location "/.well-known/webfinger" { + block return 301 "https://$SERVER_NAME/public.php?service=webfinger" + } + + location match "/ocs-provider/*" { + pass + } } @@ -108,19 +108,19 @@ It is recommended to add opcache to it:: opcache.max_accelerated_files=10000 opcache.revalidate_freq=1 opcache.save_comments=1 - + And increase some limits:: post_max_size = 513M upload_max_filesize = 513M - - + + We can enable the PHP modules with:: # cd /etc/php-8.2.sample # for i in *; do ln -sf ../php-8.2.sample/$i ../php-8.2/; done - + And then we just enable and start PHP:: # rcctl enable php82_fpm @@ -131,7 +131,7 @@ Database -------- As mentioned, we will be using PostgreSQL as our database, and we already installed it, now we need to initialised:: - + $ su - _postgresql $ mkdir /var/postgresql/data $ initdb -D /var/postgresql/data -U postgres -A md5 -E UTF8 -W @@ -153,7 +153,7 @@ We need to check, enable and start postgres:: # rcctl check postgresql # rcctl enable postgresql # rcctl start postgresql - + You can follow the README on ``/usr/local/share/doc/pkg-readmes/postgresql-server`` to create users and permission. @@ -173,7 +173,7 @@ We installed redis before, we need to enable it and start it and also add it to 'timeout' => 0.0, ), ... - + Cron job -------- @@ -181,7 +181,7 @@ Cron job We need to add the Nextcloud cron job to get some tasks done by adding this entry on your cronjob:: */5 * * * * /usr/bin/ftp -Vo - https://domain.tld/cron.php >/dev/null - + Chroot ------ @@ -191,7 +191,7 @@ Since in OpenBSD httpd(8) works with a chroot(8) by default, we need to be sure # install -m 444 -o root -g bin /etc/ssl/cert.pem /etc/ssl/openssl.cnf \ /var/www/etc/ssl/ # cp /etc/resolv.conf /var/www/etc - + Nextcloud final steps --------------------- @@ -205,13 +205,13 @@ To activate this wizard, create a file named CAN_INSTALL inside the installation Use your browser to navigate to the installation's URL: https://domain.tld - + Now you just need to follow the steps and put in place your DB name, usr and passwords. Keep in mind that the upgrades for Nextcloud you can do it by running on -current:: # pkg_add -u -Dsnap - + And on -stable:: # pkg_add -u @@ -226,5 +226,5 @@ NOTE Remember always to read all the READMES from the OpenBSD packages on:: /usr/local/share/doc/pkg-readmes/ - + All this information and more is available for you there. diff --git a/admin_manual/installation/example_ubuntu.rst b/admin_manual/installation/example_ubuntu.rst index f2390bd9571..60f5c96abe0 100644 --- a/admin_manual/installation/example_ubuntu.rst +++ b/admin_manual/installation/example_ubuntu.rst @@ -12,7 +12,7 @@ following commands in a terminal:: sudo apt install apache2 mariadb-server libapache2-mod-php php-gd php-mysql \ php-curl php-mbstring php-intl php-gmp php-xml php-imagick php-zip -* This installs the packages for the Nextcloud core system. +* This installs the packages for the Nextcloud core system. If you are planning on running additional apps, keep in mind that they might require additional packages. See :ref:`Prerequisites for manual installation ` for details. diff --git a/admin_manual/installation/harden_server.rst b/admin_manual/installation/harden_server.rst index 8e6547d20c9..47d06519590 100644 --- a/admin_manual/installation/harden_server.rst +++ b/admin_manual/installation/harden_server.rst @@ -2,14 +2,14 @@ Hardening and security guidance =============================== -Nextcloud aims to ship with secure defaults that do not need to get modified by -administrators. However, in some cases some additional security hardening can be -applied in scenarios where the administrator has complete control over -the Nextcloud instance. This page assumes that you run Nextcloud Server on Apache2 +Nextcloud aims to ship with secure defaults that do not need to get modified by +administrators. However, in some cases some additional security hardening can be +applied in scenarios where the administrator has complete control over +the Nextcloud instance. This page assumes that you run Nextcloud Server on Apache2 in a Linux environment. -.. note:: Nextcloud will warn you in the administration interface if some - critical security-relevant options are missing. However, it is still up to +.. note:: Nextcloud will warn you in the administration interface if some + critical security-relevant options are missing. However, it is still up to the server administrator to review and maintain system security. Passwords @@ -27,10 +27,10 @@ Leakage of the access token can have negative security consequences. Depending o Limit on password length ^^^^^^^^^^^^^^^^^^^^^^^^ -Nextcloud uses the bcrypt algorithm, and thus for security and performance -reasons, e.g. Denial of Service as CPU demand increases exponentially, it only -verifies the first 72 characters of passwords. This applies to all passwords -that you use in Nextcloud: user passwords, passwords on link shares, and +Nextcloud uses the bcrypt algorithm, and thus for security and performance +reasons, e.g. Denial of Service as CPU demand increases exponentially, it only +verifies the first 72 characters of passwords. This applies to all passwords +that you use in Nextcloud: user passwords, passwords on link shares, and passwords on external shares. Operating system @@ -41,13 +41,13 @@ Operating system Give PHP read access to ``/dev/urandom`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Nextcloud uses a `RFC 4086 ("Randomness Requirements for Security")`_ compliant -mixer to generate cryptographically secure pseudo-random numbers. This means -that when generating a random number Nextcloud will request multiple random +Nextcloud uses a `RFC 4086 ("Randomness Requirements for Security")`_ compliant +mixer to generate cryptographically secure pseudo-random numbers. This means +that when generating a random number Nextcloud will request multiple random numbers from different sources and derive from these the final random number. -The random number generation also tries to request random numbers from -``/dev/urandom``, thus it is highly recommended to configure your setup in such +The random number generation also tries to request random numbers from +``/dev/urandom``, thus it is highly recommended to configure your setup in such a way that PHP is able to read random data from it. .. note:: When having an ``open_basedir`` configured within your ``php.ini`` file, @@ -56,8 +56,8 @@ a way that PHP is able to read random data from it. Enable hardening modules such as SELinux ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -It is highly recommended to enable hardening modules such as SELinux where -possible. See :doc:`../installation/selinux_configuration` to learn more about +It is highly recommended to enable hardening modules such as SELinux where +possible. See :doc:`../installation/selinux_configuration` to learn more about SELinux. Deployment @@ -66,35 +66,35 @@ Deployment Place data directory outside of the web root ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -It is highly recommended to place your data directory outside of the Web root -(i.e. outside of ``/var/www``). It is easiest to do this on a new +It is highly recommended to place your data directory outside of the Web root +(i.e. outside of ``/var/www``). It is easiest to do this on a new installation. .. Doc on moving data dir coming soon -.. You may also move your data directory on an existing +.. You may also move your data directory on an existing .. installation; see :doc:`` Disable preview image generation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Nextcloud is able to generate preview images of common filetypes such as images -or text files. By default the preview generation for some file types that we -consider secure enough for deployment is enabled. However, -administrators should be aware that these previews are generated using PHP +Nextcloud is able to generate preview images of common filetypes such as images +or text files. By default the preview generation for some file types that we +consider secure enough for deployment is enabled. However, +administrators should be aware that these previews are generated using PHP libraries written in C which might be vulnerable to attack vectors. -For high security deployments we recommend disabling the preview generation by -setting the ``enable_previews`` switch to ``false`` in ``config.php``. As an -administrator you are also able to manage which preview providers are enabled by +For high security deployments we recommend disabling the preview generation by +setting the ``enable_previews`` switch to ``false`` in ``config.php``. As an +administrator you are also able to manage which preview providers are enabled by modifying the ``enabledPreviewProviders`` option switch. Disable Debug Mode ^^^^^^^^^^^^^^^^^^ -Verify that ``debug`` is ``false`` in your ``config.php``. The default is ``false`` -in new installations (or when not specified). It should not be enabled in production -environments or outside of targeted troubleshooting situations. When enabled, things -like server-wide WebDAV collection listings are permitted. It is intended for local +Verify that ``debug`` is ``false`` in your ``config.php``. The default is ``false`` +in new installations (or when not specified). It should not be enabled in production +environments or outside of targeted troubleshooting situations. When enabled, things +like server-wide WebDAV collection listings are permitted. It is intended for local development and usage in controlled environments only. .. _use_https_label: @@ -102,20 +102,20 @@ development and usage in controlled environments only. Use HTTPS --------- -Using Nextcloud without using an encrypted HTTPS connection opens up your server -to a man-in-the-middle (MITM) attack, and risks the interception of user data -and passwords. It is a best practice, and highly recommended, to always use +Using Nextcloud without using an encrypted HTTPS connection opens up your server +to a man-in-the-middle (MITM) attack, and risks the interception of user data +and passwords. It is a best practice, and highly recommended, to always use HTTPS on production servers, and to never allow unencrypted HTTP. -How to setup HTTPS on your Web server depends on your setup; please consult the +How to setup HTTPS on your Web server depends on your setup; please consult the documentation for your HTTP server. The following examples are for Apache. Redirect all unencrypted traffic to HTTPS ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To redirect all HTTP traffic to HTTPS administrators are encouraged to issue a -permanent redirect using the 301 status code. When using Apache this can be -achieved by a setting such as the following in the Apache VirtualHosts +To redirect all HTTP traffic to HTTPS administrators are encouraged to issue a +permanent redirect using the 301 status code. When using Apache this can be +achieved by a setting such as the following in the Apache VirtualHosts configuration:: @@ -128,13 +128,13 @@ configuration:: Enable HTTP Strict Transport Security ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -While redirecting all traffic to HTTPS is good, it may not completely prevent -man-in-the-middle attacks. Thus administrators are encouraged to set the HTTP -Strict Transport Security header, which instructs browsers to not allow any -connection to the Nextcloud instance using HTTP, and it attempts to prevent site +While redirecting all traffic to HTTPS is good, it may not completely prevent +man-in-the-middle attacks. Thus administrators are encouraged to set the HTTP +Strict Transport Security header, which instructs browsers to not allow any +connection to the Nextcloud instance using HTTP, and it attempts to prevent site visitors from bypassing invalid certificate warnings. -This can be achieved by setting the following settings within the Apache +This can be achieved by setting the following settings within the Apache VirtualHost file:: @@ -162,17 +162,17 @@ This requires the ``mod_headers`` extension in Apache. Proper SSL configuration ^^^^^^^^^^^^^^^^^^^^^^^^ -Default SSL configurations by Web servers are often not state-of-the-art, and -require fine-tuning for an optimal performance and security experience. The -available SSL ciphers and options depend completely on your environment and +Default SSL configurations by Web servers are often not state-of-the-art, and +require fine-tuning for an optimal performance and security experience. The +available SSL ciphers and options depend completely on your environment and thus giving a generic recommendation is not really possible. -We recommend using the `Mozilla SSL Configuration Generator`_ to generate a +We recommend using the `Mozilla SSL Configuration Generator`_ to generate a suitable configuration suited for your environment. To verify your configuration you can use the free `Web TLS Profiler`_ service. This service gives detailed error messages, if your server's TLS settings deviate from the Mozilla Configuration. Another useful tool to check your server's -TLS configuration is the free `Qualys SSL Labs Test`_ which provides general +TLS configuration is the free `Qualys SSL Labs Test`_ which provides general information about the TLS settings. Also ensure that HTTP compression is disabled to mitigate the BREACH attack. @@ -197,8 +197,8 @@ Administrators connected from untrusted IP addresses will be able to use Nextclo Use a dedicated domain for Nextcloud ------------------------------------ -Administrators are encouraged to install Nextcloud on a dedicated domain such as -cloud.domain.tld instead of domain.tld to gain all the benefits offered by the +Administrators are encouraged to install Nextcloud on a dedicated domain such as +cloud.domain.tld instead of domain.tld to gain all the benefits offered by the Same-Origin-Policy. Ensure that your Nextcloud instance is installed in a DMZ @@ -209,38 +209,38 @@ Server Side Request Forgery (SSRF) part of our threat model. In fact, given all external storage adapters this can be considered a feature and not a vulnerability. This means that a user on your Nextcloud instance could probe whether other hosts -are accessible from the Nextcloud network. If you do not want this you need to -ensure that your Nextcloud is properly installed in a segregated network and proper +are accessible from the Nextcloud network. If you do not want this you need to +ensure that your Nextcloud is properly installed in a segregated network and proper firewall rules are in place. Serve security related headers by the Web server ------------------------------------------------ -Basic security headers are served by Nextcloud already in a default environment. +Basic security headers are served by Nextcloud already in a default environment. These include: - ``X-Content-Type-Options: nosniff`` - - Instructs some browsers to not sniff the mimetype of files. This is used for example to prevent browsers from interpreting text files as JavaScript. + - Instructs some browsers to not sniff the mimetype of files. This is used for example to prevent browsers from interpreting text files as JavaScript. - ``X-Robots-Tag: noindex, nofollow`` - - Instructs search machines to not index these pages and not follow any links there. + - Instructs search machines to not index these pages and not follow any links there. - ``X-Frame-Options: SAMEORIGIN`` - - Prevents embedding of the Nextcloud instance within an iframe from other domains to prevent Clickjacking and other similar attacks. + - Prevents embedding of the Nextcloud instance within an iframe from other domains to prevent Clickjacking and other similar attacks. - ``Referrer-Policy: no-referrer`` - - The default `no-referrer` policy instructs the browser not to send referrer information along with requests to any origin. + - The default `no-referrer` policy instructs the browser not to send referrer information along with requests to any origin. -These headers are hard-coded into the Nextcloud server, and need no intervention +These headers are hard-coded into the Nextcloud server, and need no intervention by the server administrator. -For optimal security, administrators are encouraged to serve these basic HTTP -headers by the Web server to enforce them on response. To do this Apache has to -be configured to use the ``.htaccess`` file and the following Apache +For optimal security, administrators are encouraged to serve these basic HTTP +headers by the Web server to enforce them on response. To do this Apache has to +be configured to use the ``.htaccess`` file and the following Apache modules need to be enabled: - mod_headers - mod_env -Administrators can verify whether this security change is active by accessing a -static resource served by the Web server and verify that the above mentioned +Administrators can verify whether this security change is active by accessing a +static resource served by the Web server and verify that the above mentioned security headers are shipped. .. _Mozilla SSL Configuration Generator: https://mozilla.github.io/server-side-tls/ssl-config-generator/ @@ -258,47 +258,47 @@ This paragraph also includes the data which is being transmitted to the Nextclou Depending on your server setup, these are the possible connections: - connectivity.nextcloud.com, www.eff.org, edri.org - - `optional (config)`_ - - for checking the internet connection + - `optional (config)`_ + - for checking the internet connection - cloud.nextcloud.com - - used for enterprise license monitoring - - submitted data: subscription key, user count + - used for enterprise license monitoring + - submitted data: subscription key, user count - updates.nextcloud.com - - to check for available Nextcloud server updates - - submitted data: server version, subscription key, install time, instance id, instance size + - to check for available Nextcloud server updates + - submitted data: server version, subscription key, install time, instance id, instance size - apps.nextcloud.com, ltd[1-3].nextcloud.com, garm[1-5].nextcloud.com - - to check for available apps and their updates - - source is apps.nextcloud.com the ltd and garm servers are just mirroring the apps.json file - - submitted data: subscription key + - to check for available apps and their updates + - source is apps.nextcloud.com the ltd and garm servers are just mirroring the apps.json file + - submitted data: subscription key - github.com, objects.githubusercontent.com, release-assets.githubusercontent.com - - to download Nextcloud standard apps - - to download Nextcloud server releases + - to download Nextcloud standard apps + - to download Nextcloud server releases - push-notifications.nextcloud.com - - sending push notifications to mobile clients - - submitted data: unique device identifier, public key, push token + - sending push notifications to mobile clients + - submitted data: unique device identifier, public key, push token - pushfeed.nextcloud.com - - optional - - checking for updates to be shown in the Nextcloud Announcements app + - optional + - checking for updates to be shown in the Nextcloud Announcements app - lookup.nextcloud.com - - optional - - for updating and lookups to the federated sharing addressbook - - submitted data: *pending* + - optional + - for updating and lookups to the federated sharing addressbook + - submitted data: *pending* - surveyserver.nextcloud.com - - optional - - if the admin has agreed to share anonymized server data - - submitted data: statistical data. see here for the `detailed field list`_ + - optional + - if the admin has agreed to share anonymized server data + - submitted data: statistical data. see here for the `detailed field list`_ - nominatim.openstreetmap.org - - optional - - if the weather status app is enabled and used - - submitted data: address manually entered by the user to resolve to longitude and latitude + - optional + - if the weather status app is enabled and used + - submitted data: address manually entered by the user to resolve to longitude and latitude - api.opentopodata.org - - optional - - if the weather status app is enabled and used - - submitted data: address manually entered by the user to resolve the altitude of the location + - optional + - if the weather status app is enabled and used + - submitted data: address manually entered by the user to resolve the altitude of the location - api.met.no - - optional - - if the weather status app is enabled and used - - submitted data: longitude and latitude configured in the weather status app by the individual user + - optional + - if the weather status app is enabled and used + - submitted data: longitude and latitude configured in the weather status app by the individual user - Any remote Nextcloud server that is connected with federated sharing - When downloading apps from the App store other domains might be accessed, based on the choice of the app developers where they host the releases. For all official Nextcloud apps this is not the case though, because they are hosted on Github. @@ -309,7 +309,7 @@ Depending on your server setup, these are the possible connections: Setup fail2ban -------------- -Exposing your server to the internet will inevitably lead to the exposure of the +Exposing your server to the internet will inevitably lead to the exposure of the services running on the internet-exposed ports to brute force login attempts. This guide will enable blocking of the originating IP addresses at an operating @@ -333,7 +333,7 @@ Fail2ban introduction ^^^^^^^^^^^^^^^^^^^^^ Fail2ban is a service that uses iptables to automatically drop connections for a -pre-defined amount of time from IPs that continuously failed to authenticate to +pre-defined amount of time from IPs that continuously failed to authenticate to the configured services. In order to setup fail2ban, you first need to download and install it on your @@ -346,11 +346,11 @@ The standard path for fail2ban's configuration is ``/etc/fail2ban``. Setup a filter and a jail for Nextcloud ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A filter defines regex rules to identify when users fail to authenticate on -Nextcloud's user interface, WebDAV, or use an untrusted domain to access the +A filter defines regex rules to identify when users fail to authenticate on +Nextcloud's user interface, WebDAV, or use an untrusted domain to access the server. -Create a file in ``/etc/fail2ban/filter.d`` named ``nextcloud.conf`` with the +Create a file in ``/etc/fail2ban/filter.d`` named ``nextcloud.conf`` with the following contents:: [Definition] @@ -360,10 +360,10 @@ following contents:: ^\{%(_groupsre)s,?\s*"remoteAddr":""%(_groupsre)s,?\s*"message":"Trusted domain error. datepattern = ,?\s*"time"\s*:\s*"%%Y-%%m-%%d[T ]%%H:%%M:%%S(%%z)?" -The jail file defines how to handle the failed authentication attempts found by +The jail file defines how to handle the failed authentication attempts found by the Nextcloud filter. -Create a file in ``/etc/fail2ban/jail.d`` named ``nextcloud.local`` with the +Create a file in ``/etc/fail2ban/jail.d`` named ``nextcloud.local`` with the following contents:: [nextcloud] @@ -377,12 +377,12 @@ following contents:: findtime = 43200 logpath = /path/to/data/directory/nextcloud.log -Ensure to replace ``logpath`` with your installation's ``nextcloud.log`` -location. If you are using ports other than ``80`` and ``443`` for your -Web server you should replace those too. The ``bantime`` and ``findtime`` are +Ensure to replace ``logpath`` with your installation's ``nextcloud.log`` +location. If you are using ports other than ``80`` and ``443`` for your +Web server you should replace those too. The ``bantime`` and ``findtime`` are defined in seconds. -Restart the fail2ban service. You can check the status of your Nextcloud jail by +Restart the fail2ban service. You can check the status of your Nextcloud jail by running:: fail2ban-client status nextcloud diff --git a/admin_manual/installation/installation_wizard.rst b/admin_manual/installation/installation_wizard.rst index 220a3e5d06e..9d8dfa128b0 100644 --- a/admin_manual/installation/installation_wizard.rst +++ b/admin_manual/installation/installation_wizard.rst @@ -106,8 +106,8 @@ attempts to create a dedicated database user with privileges limited to the Nextcloud database. This avoids storing your administrative database credentials in ``config.php``. -If privileges are sufficient, the install creates a user named ``oc_admin``. -If that user already exists, a numeric suffix is appended (``oc_admin1``, +If privileges are sufficient, the install creates a user named ``oc_admin``. +If that user already exists, a numeric suffix is appended (``oc_admin1``, ``oc_admin2``, etc.) until an available username is found. A random password is generated for the new user. The resulting credentials are @@ -116,7 +116,7 @@ written into ``config.php``:: 'dbuser' => 'oc_admin', 'dbpassword' => 'pX65Ty5DrHQkYPE5HRsDvyFHlZZHcm', -If the provided user lacks the privileges to create new database users, the +If the provided user lacks the privileges to create new database users, the installer falls back to using the provided credentials directly. .. tip:: diff --git a/admin_manual/installation/nginx.rst b/admin_manual/installation/nginx.rst index 413c5bd872d..1a5c1aa1ab5 100644 --- a/admin_manual/installation/nginx.rst +++ b/admin_manual/installation/nginx.rst @@ -10,9 +10,9 @@ This page covers how to run a Nextcloud server using NGINX backed by PHP-FPM, wh Choose the appropriate example based on whether you are deploying :ref:`nginx_webroot_example` (i.e. :code:`https://cloud.example.com/`) or :ref:`nginx_subdir_example` (i.e. :code:`https://cloud.example.com/nextcloud`). - Adjust the server directive under :code:`upstream php-handler` to match your PHP installation's configured FPM listener (a misconfiguration here will result in a :code:`502 Bad Gateway` - see :ref:`nginx_php_handler_tips` for details) - Adjust the existing :code:`server_name` directives found under *both* :code:`server` sections to your real hostname -- Adjust :code:`root` to the webroot of your Nextcloud installation -- Adjust the :code:`ssl_certificate` and :code:`ssl_certificate_key` directives to the real paths for your signed - certificate and private key. Make sure your SSL certificates are readable by the nginx server process (see `nginx HTTPS SSL +- Adjust :code:`root` to the webroot of your Nextcloud installation +- Adjust the :code:`ssl_certificate` and :code:`ssl_certificate_key` directives to the real paths for your signed + certificate and private key. Make sure your SSL certificates are readable by the nginx server process (see `nginx HTTPS SSL Module documentation `_). - If using Let's Encrypt as TLS certificate and nginx as webserver, set `ssl_stapling` and `ssl_stapling_verify` to `off` in main nginx config (see [Let's Encrypt blog post](https://letsencrypt.org/2024/12/05/ending-ocsp)). @@ -65,15 +65,15 @@ The :code:`server` line within the :code:`upstream php-handler` above needs to b Many Linux distributions define a listener for a default PHP-FPM pool called :code:`www` in a file called :code:`www.conf` located somewhere like :code:`/etc/php/8.1/pool.d`. -Look for the line that is set to something like: - +Look for the line that is set to something like: + :code:`listen = /var/run/php/php-fpm.sock` or :code:`listen = 127.0.0.1:9000` - + If PHP FPM will be running on the same host as NGINX (it's probably a safe assumption it will be if you're unsure), it is recommended you use the UNIX socket (i.e. :code:`/var/run/php/php-fpm.sock`) rather than TCP (:code:`127.0.0.1:9000`) for maximum performance (though either will work as long as your NGINX and PHP FPM configurations match). -After deciding how you'd prefer to connect NGINX with PHP FPM (and, if necessary, updating your local PHP FPM configuration and restarting FPM), set your NGINX configuration's :code:`upstream php-handler` :code:`server` to match your preference (Note: If using UNIX sockets, prepend :code:`unix:` in the NGINX configuration, but *not* in your PHP FPM :code:`www.conf`). +After deciding how you'd prefer to connect NGINX with PHP FPM (and, if necessary, updating your local PHP FPM configuration and restarting FPM), set your NGINX configuration's :code:`upstream php-handler` :code:`server` to match your preference (Note: If using UNIX sockets, prepend :code:`unix:` in the NGINX configuration, but *not* in your PHP FPM :code:`www.conf`). Suppressing log messages ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/admin_manual/installation/php_configuration.rst b/admin_manual/installation/php_configuration.rst index bb4644be7dd..c2d7f7f356f 100644 --- a/admin_manual/installation/php_configuration.rst +++ b/admin_manual/installation/php_configuration.rst @@ -2,16 +2,16 @@ Preparing PHP ============= -Before installing Nextcloud Server, ensure your PHP environment is properly configured. This includes installing -the correct PHP version, enabling required PHP modules, and adjusting important `php.ini` settings. This guide -explains which PHP modules are necessary, which are recommended for optimal performance and compatibility, and +Before installing Nextcloud Server, ensure your PHP environment is properly configured. This includes installing +the correct PHP version, enabling required PHP modules, and adjusting important `php.ini` settings. This guide +explains which PHP modules are necessary, which are recommended for optimal performance and compatibility, and how to configure your PHP environment for both web server and command-line usage. .. note:: You can safely ignore this chapter if you plan to use a turnkey Nextcloud Server installation method (such as - AIO, Snap, NCP, or Community Docker). Those installation methods provide PHP environments that are already + AIO, Snap, NCP, or Community Docker). Those installation methods provide PHP environments that are already pre-configured for use with Nextcloud Server. For guidance regarding customizing PHP in those environments, - refer to the documentation provided specifically for or by those install methods. + refer to the documentation provided specifically for or by those install methods. .. contents:: :local: @@ -22,9 +22,9 @@ PHP Installation ---------------- Refer to your OS distribution's documentation for instructions for establishing a base PHP installation. It may -be possible to choose among several versions of PHP. Refer to :doc:`./system_requirements` to see which versions -of PHP are supported by this release of Nextcloud Server. After completing a base PHP installation, -follow the below guidance to configure your new PHP installation for your new Nextcloud Server deployment. +be possible to choose among several versions of PHP. Refer to :doc:`./system_requirements` to see which versions +of PHP are supported by this release of Nextcloud Server. After completing a base PHP installation, +follow the below guidance to configure your new PHP installation for your new Nextcloud Server deployment. -------------------- Required PHP Modules @@ -52,15 +52,15 @@ The following PHP modules **must** be installed and enabled for Nextcloud Server corresponding `php-xml` (or distribution-specific) package is installed so that SimpleXML, XMLReader and XMLWriter are available to PHP. -The `ctype`, `fileinfo`, and `OpenSSL` modules are generally included and enabled in PHP by default. Often -some of the other required modules are automatically installed by OS distribution package managers. +The `ctype`, `fileinfo`, and `OpenSSL` modules are generally included and enabled in PHP by default. Often +some of the other required modules are automatically installed by OS distribution package managers. -**How to check if a module is enabled:** +**How to check if a module is enabled:** - Run ``php -m | grep -i ``. If you see output, the module is active. .. note:: - The `filter` module is required only on Mageia and FreeBSD. + The `filter` module is required only on Mageia and FreeBSD. -------------------------------- Required PHP Database Connectors @@ -79,10 +79,10 @@ Recommended General PHP Modules These modules are not required, but are highly recommended to improve functionality or security: - `intl`: Fixes sorting of non-ASCII characters and improves language translation performance. -- `sodium`: Provides Argon2 password hashing (needed if using PHP < 8.4 and PHP was built without `libargon2`). +- `sodium`: Provides Argon2 password hashing (needed if using PHP < 8.4 and PHP was built without `libargon2`). - bcrypt will be used if Argon2 is unavailable, but if passwords were previously hashed with Argon2 - (such as when migrating an existing Nextcloud Server installation to a new server environment) and this + bcrypt will be used if Argon2 is unavailable, but if passwords were previously hashed with Argon2 + (such as when migrating an existing Nextcloud Server installation to a new server environment) and this module is missing, accounts will not be able to log-in). - `sysvsem`: Enables System V semaphores used by Nextcloud to coordinate preview generation across PHP processes. Recommended; if missing, previews still work but may be less reliable under heavy load. @@ -90,15 +90,15 @@ These modules are not required, but are highly recommended to improve functional Recommended PHP Caching Modules ------------------------------- -Memory caching is not required so these modules are not required, but are highly recommended for optimal +Memory caching is not required so these modules are not required, but are highly recommended for optimal performance and reliability. Choose and install your preferred combination of memory caching modules: - `APCu` (>= 4.0.6) - `redis` / `phpredis` (>= 2.2.6, required for Transactional File Locking) - `memcached` (an older alternative to `redis` that is not recommended for new installations) -.. note:: - Memory caching is highly recommended for optimal performance. In most cases, a combination of `APCu` and +.. note:: + Memory caching is highly recommended for optimal performance. In most cases, a combination of `APCu` and `redis` are the best choice for new installations. See :doc:`../configuration_server/caching_configuration` for configuration details. @@ -109,9 +109,9 @@ Recommended PHP CLI Modules **For command-line processing** (optional): -- `pcntl`: Allows command interruption (e.g., via ``ctrl-c``). +- `pcntl`: Allows command interruption (e.g., via ``ctrl-c``). - Ensure ``pcntl_signal`` and ``pcntl_signal_dispatch`` are *not* disabled in your `php.ini` by the + Ensure ``pcntl_signal`` and ``pcntl_signal_dispatch`` are *not* disabled in your `php.ini` by the ``disable_functions`` option. **For command-line updater** (optional): @@ -178,7 +178,7 @@ Notes on PHP `ini` Configuration - Web server: `/etc/php//apache2/php.ini` or `/etc/php//fpm/php.ini` - - CLI (used by Nextcloud CRON jobs): + - CLI (used by Nextcloud CRON jobs): `/etc/php//cli/php.ini` - **Find which php.ini is active for each SAPI:** @@ -268,7 +268,7 @@ PHP Module Quick Reference Table Further Resources ----------------- -- For more details on each module, consult the +- For more details on each module, consult the `official PHP documentation `_. - Refer to your OS distribution's documentation for the specifics of installing PHP modules in your environment. - The words *extension* and *module* are interchangeable within PHP. We use the word *modules* in our documentation. diff --git a/admin_manual/installation/selinux_configuration.rst b/admin_manual/installation/selinux_configuration.rst index 3cf33df4f3a..965d63cdfe4 100644 --- a/admin_manual/installation/selinux_configuration.rst +++ b/admin_manual/installation/selinux_configuration.rst @@ -6,10 +6,10 @@ SELinux configuration When you have SELinux enabled on your Linux distribution, you may run into permissions problems after a new Nextcloud installation, and see ``permission -denied`` errors in your Nextcloud logs. +denied`` errors in your Nextcloud logs. -.. tip:: +.. tip:: Permission problems may be caused by SELinux *even if the denial is not indicated in the audit logs.* This is because SELinux does not log all system calls used for verifying access. See `Possible Causes of Silent Denials `_ to solve. diff --git a/admin_manual/installation/server_tuning.rst b/admin_manual/installation/server_tuning.rst index 5f04459cd1f..bf7880dc891 100644 --- a/admin_manual/installation/server_tuning.rst +++ b/admin_manual/installation/server_tuning.rst @@ -20,10 +20,10 @@ side effects. To reduce load, you should first identify the source of the proble Tools such as htop, iotop, `netdata `_, or `glances `_ can help you identify the process or drive that slows down your system. -First, make sure that you have installed and assigned enough RAM. Minimize swap +First, make sure that you have installed and assigned enough RAM. Minimize swap usage as much as possible, as excessive swapping can severely degrade performance. If you run your database inside a VM, use a dedicated block device for database storage -rather than storing it inside the VM's disk image file, to reduce latency caused by +rather than storing it inside the VM's disk image file, to reduce latency caused by multiple abstraction layers. .. _caching: @@ -31,49 +31,49 @@ multiple abstraction layers. Log Levels ---------- -Verify the ``loglevel`` in your ``config.php`` file. The default log level is -set to ``2`` (WARN) in new installations. Sometimes this parameter is inadvertently -left at the DEBUG level (``0``) after troubleshooting. In some older installations, this -parameter may also be something other than the default. Use ``0`` (DEBUG) -when you have a problem to diagnose, and then reset your log level to a -less-verbose level. DEBUG outputs a lot of information, and can affect your +Verify the ``loglevel`` in your ``config.php`` file. The default log level is +set to ``2`` (WARN) in new installations. Sometimes this parameter is inadvertently +left at the DEBUG level (``0``) after troubleshooting. In some older installations, this +parameter may also be something other than the default. Use ``0`` (DEBUG) +when you have a problem to diagnose, and then reset your log level to a +less-verbose level. DEBUG outputs a lot of information, and can affect your server performance. Debug Mode ---------- -Verify that ``debug`` is set to ``false`` in your ``config.php`` file. The default is ``false`` in new +Verify that ``debug`` is set to ``false`` in your ``config.php`` file. The default is ``false`` in new installations (or when not specified). While similar to the DEBUG logging level, this option -also disables various optimizations (to facilitate easier debugging) and generates additional -debug output both at the browser level and server-side. It should not be enabled in production +also disables various optimizations (to facilitate easier debugging) and generates additional +debug output both at the browser level and server-side. It should not be enabled in production environments except during isolated troubleshooting. Caching ------- -Caching improves performance by storing data, code, and other objects in memory. Memory caching is not enabled by default because it requires optional extensions (such as APCu) and/or system components (e.g., Redis). Although these add-ons are generally not challenging to install and activate—at least in single-server deployments—you must install them before enabling their use in Nextcloud. See :doc:../configuration_server/caching_configuration for guidance. +Caching improves performance by storing data, code, and other objects in memory. Memory caching is not enabled by default because it requires optional extensions (such as APCu) and/or system components (e.g., Redis). Although these add-ons are generally not challenging to install and activate—at least in single-server deployments—you must install them before enabling their use in Nextcloud. See :doc:`../configuration_server/caching_configuration` for guidance. Compression ----------- -Enabling compression in your web server for JavaScript, CSS, and SVG files improves performance +Enabling compression in your web server for JavaScript, CSS, and SVG files improves performance because less data is transferred to clients. Replacing SQLite ---------------- -SQLite is a suitable database for some use cases, but using MariaDB, MySQL, or PostgreSQL can be +SQLite is a suitable database for some use cases, but using MariaDB, MySQL, or PostgreSQL can be more beneficial with Nextcloud. -If you do not select a database at installation time, SQLite is used by default because it does not require +If you do not select a database at installation time, SQLite is used by default because it does not require any external components. -However, MySQL/MariaDB or PostgreSQL are generally recommended for Nextcloud because of the +However, MySQL/MariaDB or PostgreSQL are generally recommended for Nextcloud because of the `performance limitations of SQLite with highly concurrent applications `_, like Nextcloud. If your installation is already running on -SQLite, you can convert to MySQL or MariaDB using the steps provided in +SQLite, you can convert to MySQL or MariaDB using the steps provided in :doc:`../configuration_database/db_conversion`. See the section :doc:`../configuration_database/linux_database_configuration` for instructions @@ -82,7 +82,7 @@ on configuring Nextcloud for MySQL or MariaDB. Tuning your database -------------------- -Databases are not plug-and-play. They benefit not only from basic configuration for compatibility +Databases are not plug-and-play. They benefit not only from basic configuration for compatibility with Nextcloud, but also from tuning within the environment in which they are deployed. This tuning should be based on your hardware, storage, usage patterns, underlying operating system, priorities, and other factors. @@ -141,7 +141,7 @@ Tune PHP-FPM The default configuration of PHP-FPM is extremely conservative. You might notice excessive load times on the web interface or even sync issues. Each simultaneous request is handled by a separate PHP-FPM process, so even on a small installation you -should allow more processes to run in parallel to handle requests. +should allow more processes to run in parallel to handle requests. `This link `_ can help you calculate the optimal values for your system. @@ -155,8 +155,8 @@ Revalidation OPcache revalidation in PHP handles changes made to PHP application code stored on disk. Code changes occur whenever: -- Nextcloud or a Nextcloud app is upgraded -- a configuration change is made (e.g. when ``config.php`` is modified) +- Nextcloud or a Nextcloud app is upgraded +- a configuration change is made (e.g. when ``config.php`` is modified) Nextcloud, as much as possible, handles cache revalidation internally when required. However, this is not foolproof. In a default PHP environment, revalidation is enabled, and cached scripts are checked for changes on disk every ``2`` seconds. In many environments, these default values are reasonable and may never need to be changed. @@ -177,7 +177,7 @@ To change the default from ``2`` and check for changes on disk at most every ``6 Any Server/app upgrades or changes to ``config.php`` will then require restarting PHP (or otherwise manually clearing the cache or invalidating this particular script). .. warning:: - Please do not report bugs or odd behavior after upgrading Nextcloud or Nextcloud apps until after you've + Please do not report bugs or odd behavior after upgrading Nextcloud or Nextcloud apps until after you've restarted mod_php/fpm (to confirm the issue is not caused by local revalidation configuration). Sizing @@ -210,9 +210,9 @@ PHP ships with a JIT compiler that can be enabled on x86 platforms to benefit an .. note:: - Most Nextcloud instances use less than 2 MiB of the configured JIT buffer size, so 8 MiB is generally sufficient. + Most Nextcloud instances use less than 2 MiB of the configured JIT buffer size, so 8 MiB is generally sufficient. The overall OPcache usage, however, increases by a larger margin. The PHP parameter ``opcache.memory_consumption`` - might need to be raised in some cases. JIT buffer usage can be monitored with + might need to be raised in some cases. JIT buffer usage can be monitored with `opcache-gui `_ as well. Previews @@ -223,11 +223,11 @@ external microservice: `Imaginary `_. .. warning:: - Imaginary is currently incompatible with server-side encryption. + Imaginary is currently incompatible with server-side encryption. See https://github.com/nextcloud/server/issues/34262 We strongly recommend running our custom Docker image, which is more up to date than the official image. -You can find the image at ``_. When running it, map a port by adding `-p :9000` to the `docker run` command (or Compose equivalent), e.g. +You can find the image at ``_. When running it, map a port by adding `-p :9000` to the `docker run` command (or Compose equivalent), e.g. .. code:: @@ -249,7 +249,7 @@ Nextcloud to use Imaginary by editing your ``config.php`` file: .. warning:: - Make sure to start Imaginary with the ``-return-size`` command line parameter. Otherwise, there will be a + Make sure to start Imaginary with the ``-return-size`` command line parameter. Otherwise, there will be a minor performance impact. The flag requires a recent version of Imaginary (newer than v1.2.4). Also, ensure to add the capability ``SYS_NICE`` via ``--cap-add=sys_nice`` or (for Compose) ``cap_add: - SYS_NICE``, as it is required by Imaginary to generate HEIC previews. diff --git a/admin_manual/installation/source_installation.rst b/admin_manual/installation/source_installation.rst index 40fb7f00e6e..4c2c0abfbb1 100644 --- a/admin_manual/installation/source_installation.rst +++ b/admin_manual/installation/source_installation.rst @@ -125,7 +125,7 @@ Additional Apache configurations and apply the following modifications to the configuration:: ProxyFCGIBackendType FPM - + SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 @@ -248,14 +248,14 @@ SELinux-enabled distributions such as Fedora and CentOS. .. _php_fpm_tips_label: -PHP-FPM configuration +PHP-FPM configuration --------------------- Overview ^^^^^^^^ -`PHP-FPM `_ is a FastCGI based -implementation of PHP containing features useful for busy web sites and large web +`PHP-FPM `_ is a FastCGI based +implementation of PHP containing features useful for busy web sites and large web applications. Using it with Nextcloud is an advanced topic and requires getting familiar with how PHP-FPM functions. In most cases the defaults are not ideal for use with Nextcloud. Here we'll highlight a few of the most important areas that @@ -265,13 +265,13 @@ Process manager ^^^^^^^^^^^^^^^ The default value for ``pm.max_children`` in many PHP-FPM installations is -lower than appropriate. Having a low value may cause client connectivity +lower than appropriate. Having a low value may cause client connectivity problems, unexplained errors, and performance problems. It is a common cause of *Gateway Timeouts*. Having too high of a value in relation to available resources (such as memory), however, will also lead to problems. The default value is often ``5``. This greatly limits simultaneously connections to your -Nextcloud instance and, unless you are under severe resource constraints, will -underutilize your hardware. Check the :doc:`../installation/server_tuning` +Nextcloud instance and, unless you are under severe resource constraints, will +underutilize your hardware. Check the :doc:`../installation/server_tuning` chapter for some guidance and resources for coming up with appropriate values, as well as other related parameters. @@ -400,18 +400,18 @@ For complete instructions and downloads see: Installing via Snap packages ---------------------------- -Nextcloud snap is a community driven installation method and is designed +Nextcloud snap is a community driven installation method and is designed to be easy to install and simple to maintain. The ideal Nextcloud snap is an "install and forget" Nextcloud instance that works on most architectures -and updates itself without needing administrative skills. -Combining Nextcloud with snapd makes it a perfect fit for IoT or -scalable environments. `Snapd `_ is a secure +and updates itself without needing administrative skills. +Combining Nextcloud with snapd makes it a perfect fit for IoT or +scalable environments. `Snapd `_ is a secure and robust technology which the Nextcloud snap team has embraced. -Most importantly snaps are designed to be secure, sandboxed, containerized +Most importantly snaps are designed to be secure, sandboxed, containerized applications isolated from the underlying system and from other applications. -However, the snap is opinionated and there are `requirements `_ to be met. +However, the snap is opinionated and there are `requirements `_ to be met. - Nextcloud snap uses recommended Apache. - Nextcloud snap uses recommended MySQL. @@ -428,27 +428,27 @@ Installation **All other distros** `be warned `_ -By default the latest stable Nextcloud snap release will be installed and it will automatically update to -subsequent stable releases, but there are `other releases available as well `_ +By default the latest stable Nextcloud snap release will be installed and it will automatically update to +subsequent stable releases, but there are `other releases available as well `_ and you have full control of `automatic updates `_. -After installation, Nextcloud will start automatically. -Assuming you and the device on which it was installed are on the same network, you will reach the Nextcloud -installation by visiting ``.local`` or the IP address of the instance in your browser. -If your hostname is ``localhost`` or ``localhost.localdomain``, like on an Ubuntu Core device, -``nextcloud.local`` will be used instead. +After installation, Nextcloud will start automatically. +Assuming you and the device on which it was installed are on the same network, you will reach the Nextcloud +installation by visiting ``.local`` or the IP address of the instance in your browser. +If your hostname is ``localhost`` or ``localhost.localdomain``, like on an Ubuntu Core device, +``nextcloud.local`` will be used instead. 1st login ^^^^^^^^^ -Upon visiting the Nextcloud installation for the first time, you will be prompted to enter an admin username +Upon visiting the Nextcloud installation for the first time, you will be prompted to enter an admin username and password before Nextcloud is initialised. This may take a while depending on resources and the device. After you provide that information you will be logged in and able to install apps, create users, and upload files. HTTPS encryption ^^^^^^^^^^^^^^^^ -Nextcloud snap includes a service for automated HTTPS encryption and automated renewal using Lets Encrypt, +Nextcloud snap includes a service for automated HTTPS encryption and automated renewal using Lets Encrypt, or self-signed certificates. Run ``nextcloud.enable-https -h`` for more information. `Managing encryption `_. Configuration @@ -460,19 +460,19 @@ editing configuration files manually or using the management console. `Configuri External media ^^^^^^^^^^^^^^ -`Snap confinement `_ is a security feature and determines the amount of access an application has to system resources, -such as files, the network, peripherals and services. Thus your Nextcloud snap is securely confined from the host -system. Unless you specifically allow the Nextcloud snap to access the ``/media`` or ``/mnt`` directories on the +`Snap confinement `_ is a security feature and determines the amount of access an application has to system resources, +such as files, the network, peripherals and services. Thus your Nextcloud snap is securely confined from the host +system. Unless you specifically allow the Nextcloud snap to access the ``/media`` or ``/mnt`` directories on the host system, you will not be able to access any other directory outside of the confinement. -Removable media or external storage must be mounted to either ``/media`` or ``/mnt`` as root with root permissions +Removable media or external storage must be mounted to either ``/media`` or ``/mnt`` as root with root permissions and connected to Snap! `Managing external media and storage `_ -The interface providing the ability to access removable media is not automatically connected upon install, to use -external storage (or otherwise use a device in ``/media`` or ``/mnt`` for data), you need to give the snap permission +The interface providing the ability to access removable media is not automatically connected upon install, to use +external storage (or otherwise use a device in ``/media`` or ``/mnt`` for data), you need to give the snap permission to access removable media by connecting that interface: -``sudo snap connect nextcloud:removable-media`` +``sudo snap connect nextcloud:removable-media`` Further documentation, an extensive `Wiki `_ and `FAQ's `_ can be found on the `developers GitHub `_. diff --git a/admin_manual/installation/system_requirements.rst b/admin_manual/installation/system_requirements.rst index 66ad91533fb..7b55e8edf97 100644 --- a/admin_manual/installation/system_requirements.rst +++ b/admin_manual/installation/system_requirements.rst @@ -44,7 +44,7 @@ For best performance, stability and functionality we have documented some recomm See :doc:`source_installation` for minimum PHP-modules and additional software for installing Nextcloud. -To ensure the full functionality of your Nextcloud, please make sure that the server can reach the :ref:`required remote systems`. +To ensure the full functionality of your Nextcloud, please make sure that the server can reach the :ref:`required remote systems`. CPU Architecture and OS ^^^^^^^^^^^^^^^^^^^^^^^ @@ -64,7 +64,7 @@ depending on the numbers of users, apps, files and volume of server activity. Nextcloud needs a minimum of **128MB** RAM per process, and we recommend a minimum of **512MB** RAM per process. -In low memory environments, some features or apps may require adjustments to their default +In low memory environments, some features or apps may require adjustments to their default settings in order to function (or, in some cases, may need to be disabled outright). .. warning:: To use the built-in Updater, at least 256MB is required. diff --git a/admin_manual/installation/uninstallation.rst b/admin_manual/installation/uninstallation.rst index b2bc8d18aba..cb98fa97732 100644 --- a/admin_manual/installation/uninstallation.rst +++ b/admin_manual/installation/uninstallation.rst @@ -21,4 +21,4 @@ To uninstall, you can read values from your configuration in ``config`` director - Database (related configuration keys: ``dbtype``, ``dbhost``): remove the corresponding database on all your database servers (you may want to make a backup first) - Cache (related configuration keys: ``memcache.*``): if persistent, remove the corresponding database or key from all cache servers - Data (related configuration keys: ``datadirectory``): delete the directory on all servers (you may need to create a backup beforehand). Nextcloud has the option to store data in different locations. Also check external storage and objectstore -- Logs (related configuration keys: ``logfile``, ``logfile_audit``): normally in the data directory, but can also be in another location such as ``/var/log/`` \ No newline at end of file +- Logs (related configuration keys: ``logfile``, ``logfile_audit``): normally in the data directory, but can also be in another location such as ``/var/log/`` diff --git a/admin_manual/issues/code_signing.rst b/admin_manual/issues/code_signing.rst index e8e1b6f1657..2f4a4cc2c21 100644 --- a/admin_manual/issues/code_signing.rst +++ b/admin_manual/issues/code_signing.rst @@ -78,15 +78,15 @@ content of the file will look similar to the following example: Results ======= - core - - INVALID_HASH - - /index.php - - /version.php - - EXTRA_FILE - - /test.php + - INVALID_HASH + - /index.php + - /version.php + - EXTRA_FILE + - /test.php - calendar - - EXCEPTION - - OC\IntegrityCheck\Exceptions\InvalidSignatureException - - Signature data not found. + - EXCEPTION + - OC\IntegrityCheck\Exceptions\InvalidSignatureException + - Signature data not found. Raw output ========== diff --git a/admin_manual/issues/general_troubleshooting.rst b/admin_manual/issues/general_troubleshooting.rst index d3ea837af4a..01a6982d119 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -52,13 +52,13 @@ to disable an app from command line. Internal Server Errors ^^^^^^^^^^^^^^^^^^^^^^ -An Internal Server Error, sometimes called a "500 error", indicates that the web server +An Internal Server Error, sometimes called a "500 error", indicates that the web server encountered an unexpected condition that prevented it from fulfilling the request. This error response is a generic "catch-all" response. To find out the source of the -error you will need to check your Nextcloud log (located in `data/nextcloud.log` by +error you will need to check your Nextcloud log (located in `data/nextcloud.log` by default) and possibly your web server's error log (depending on where the failure is -occurring). +occurring). .. tip:: Whenever possible, Nextcloud will include the "Request id" in the error. This request ID can be searched for in your Nextcloud log file to find entries associated @@ -73,12 +73,12 @@ via *Administration settings->Logging*. .. tip:: When asking for help, the entire raw log entry is generally required. -.. note: In a standard Nextcloud installation the log level is set to ``2``. This is - known as the ``WARN`` level. It is sufficient for catching for day-to-day problems +.. note: In a standard Nextcloud installation the log level is set to ``2``. This is + known as the ``WARN`` level. It is sufficient for catching for day-to-day problems (warnings, errors, and fatal errors). For some situations you may need to adjust the log level in your ``config.php`` -file. Please see :doc:`../configuration_server/logging_configuration` for more +file. Please see :doc:`../configuration_server/logging_configuration` for more information on these log levels. Some logging - for example JavaScript console logging - needs debugging @@ -94,21 +94,21 @@ usually access them by pressing F12. PHP version and information ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You will need to know the PHP version and configuration that is in-use on your -Nextcloud server. This will not necessarily be the same version and configuration as -can be reached from the command-line. The simplest way to gather this information is +You will need to know the PHP version and configuration that is in-use on your +Nextcloud server. This will not necessarily be the same version and configuration as +can be reached from the command-line. The simplest way to gather this information is by using what's commonly referenced as ``phpinfo()``. -The most accurate - and easiest - way to access ``phpinfo`` is by checking it from -within Nextcloud itself. Of course, this requires that Nextcloud is functioning -enough that you can log in as an administrator and access the -**Administration settings -> System** menu. If so, you can enable the exposure of +The most accurate - and easiest - way to access ``phpinfo`` is by checking it from +within Nextcloud itself. Of course, this requires that Nextcloud is functioning +enough that you can log in as an administrator and access the +**Administration settings -> System** menu. If so, you can enable the exposure of ``phpinfo`` data by toggling it on via ``occ``: ``./occ config:app:set --value=yes serverinfo phpinfo`` -From then on a new button labeled **Show phpinfo** will be visible in the web -interface under **Administration settings -> System**. Clicking it will expose +From then on a new button labeled **Show phpinfo** will be visible in the web +interface under **Administration settings -> System**. Clicking it will expose just about everything you may want to know about your PHP environment. If accessing the Nextcloud web interface is not an option, you may create a @@ -454,7 +454,7 @@ You can run the following SQL query to reset those after **backing up the databa .. code-block:: sql - UPDATE oc_filecache SET unencrypted_size=0 WHERE encrypted=0; + UPDATE oc_filecache SET unencrypted_size=0 WHERE encrypted=0; Troubleshooting encrypted files ------------------------------- diff --git a/admin_manual/maintenance/manual_upgrade.rst b/admin_manual/maintenance/manual_upgrade.rst index 2d8d8742c5c..d2794aad611 100644 --- a/admin_manual/maintenance/manual_upgrade.rst +++ b/admin_manual/maintenance/manual_upgrade.rst @@ -10,8 +10,8 @@ timeouts) and running it in command-line mode is not an option (such as in some In these cases a manual upgrade may be the best approach. A manual upgrade consists of downloading and unpacking the Nextcloud Archive file either to your PC or host. Then -deleting your existing Nextcloud Server installation files and folders, **except** ``data/`` and ``config/``, on -your host. Then moving the new Nextcloud Server installation files into the appropriate place on your host, +deleting your existing Nextcloud Server installation files and folders, **except** ``data/`` and ``config/``, on +your host. Then moving the new Nextcloud Server installation files into the appropriate place on your host, again preserving your existing ``data/`` and ``config/`` files. And doing a few other housekeeping items, such as making sure your installed apps are transferred into the new installation and adjusting permissions. That may sound like a lot, but detailed instructions are below. @@ -25,9 +25,9 @@ like a lot, but detailed instructions are below. .. warning:: - When upgrading manually, you must confirm your system meets the - :doc:`../installation/system_requirements` of the new version as well as that you are - following the standard :doc:`upgrade requirements <./upgrade>` (such as upgrading to + When upgrading manually, you must confirm your system meets the + :doc:`../installation/system_requirements` of the new version as well as that you are + following the standard :doc:`upgrade requirements <./upgrade>` (such as upgrading to the latest maintenance release *before* upgrading to a new major release). @@ -36,22 +36,22 @@ Step-by-Step Manual Upgrade .. important:: Always start by making a fresh backup and disabling all 3rd party apps. -1. Back up your existing Nextcloud Server database, data directory, and +1. Back up your existing Nextcloud Server database, data directory, and ``config.php`` file. (See :doc:`backup`, for restore information see :doc:`restore`) -2. Choose a target Nextcloud Server release from ``_ and - download the Archive file (tarball or zip archive) into an empty directory outside of - your current installation. - - .. warning:: You cannot jump more than one major version forward at a time +2. Choose a target Nextcloud Server release from ``_ and + download the Archive file (tarball or zip archive) into an empty directory outside of + your current installation. + + .. warning:: You cannot jump more than one major version forward at a time (i.e. 27->28 is okay, but 27->29 is not). - + 3. Unpack the the downloaded tarball or zip archive - e.g.:: unzip nextcloud-[version].zip (or) tar -xjf nextcloud-[version].tar.bz2 - + 4. Stop your Web server. 5. In case you are running a cron-job for nextcloud's house-keeping disable it @@ -63,34 +63,34 @@ Step-by-Step Manual Upgrade 6. Rename your current Nextcloud directory, for example ``nextcloud-old``. -7. Unpacking the new archive creates a new ``nextcloud`` directory populated - with your new server files. Move this directory and its contents to the - original location of your old server. For example ``/var/www/``, so that +7. Unpacking the new archive creates a new ``nextcloud`` directory populated + with your new server files. Move this directory and its contents to the + original location of your old server. For example ``/var/www/``, so that once again you have ``/var/www/nextcloud``. -8. Copy the ``config/config.php`` file from your old Nextcloud directory to your new +8. Copy the ``config/config.php`` file from your old Nextcloud directory to your new Nextcloud directory. -9. If you keep your ``data/`` directory in your ``nextcloud/`` directory, move - it from your old version of Nextcloud to your new ``nextcloud/``. If you keep - it outside of ``nextcloud/`` then you don't have to do anything with it, - because its location is configured in your original ``config.php``, and +9. If you keep your ``data/`` directory in your ``nextcloud/`` directory, move + it from your old version of Nextcloud to your new ``nextcloud/``. If you keep + it outside of ``nextcloud/`` then you don't have to do anything with it, + because its location is configured in your original ``config.php``, and none of the upgrade steps touch it. 10. If you are using 3rd party application, it may not always be available in your - upgraded/new Nextcloud instance. To check this, compare a list of the apps in the - new ``nextcloud/apps/`` folder to a list of the of the apps in your backed-up/old + upgraded/new Nextcloud instance. To check this, compare a list of the apps in the + new ``nextcloud/apps/`` folder to a list of the of the apps in your backed-up/old ``nextcloud/apps/`` folder. If you find 3rd party apps in the old folder that needs to be in the new/upgraded instance, simply copy them over and ensure the permissions are set up as shown below. 11. If you have additional apps folders like for example ``nextcloud/apps-extras`` or ``nextcloud/apps-external``, make sure to also transfer/keep these in the upgraded folder. - + 12. If you are using 3rd party theme make sure to copy it from your ``themes/`` directory to your new one. It is possible you will have to make some modifications to it after the upgrade. - + 13. Adjust file ownership and permissions:: chown -R www-data:www-data nextcloud @@ -99,15 +99,15 @@ Step-by-Step Manual Upgrade 14. Restart your Web server. -15. Now launch the upgrade from the command line using ``occ``, like this +15. Now launch the upgrade from the command line using ``occ``, like this example on Ubuntu Linux:: - + sudo -E -u www-data php occ upgrade - + (!) this MUST be executed from within your nextcloud installation directory - -16. The upgrade operation takes a few minutes to a few hours, depending on the - size of your installation. When it is finished you will see a success + +16. The upgrade operation takes a few minutes to a few hours, depending on the + size of your installation. When it is finished you will see a success message, or an error message that will tell where it went wrong. 17. Re-enable the nextcloud cron-job. (See step 4 above.) @@ -116,21 +116,21 @@ Step-by-Step Manual Upgrade (Delete the `#` at the beginning of the corresponding line in the crontab file.) -Login and take a look at the bottom of your Admin page to -verify the version number. Check your other settings to make sure they're -correct. Go to the Apps page and review the core apps to make sure the right +Login and take a look at the bottom of your Admin page to +verify the version number. Check your other settings to make sure they're +correct. Go to the Apps page and review the core apps to make sure the right ones are enabled. Re-enable your third-party apps. Previous Nextcloud releases --------------------------- -You'll find previous Nextcloud releases in the `Nextcloud Server Changelog +You'll find previous Nextcloud releases in the `Nextcloud Server Changelog `_. Troubleshooting --------------- -Occasionally, *files do not show up after an upgrade*. A rescan of the files can +Occasionally, *files do not show up after an upgrade*. A rescan of the files can help:: sudo -E -u www-data php console.php files:scan --all @@ -143,9 +143,9 @@ process is used. This is usually due to the process taking too long and encountering a PHP time-out. Stop the upgrade process this way:: sudo -E -u www-data php occ maintenance:mode --off - + Then start the manual process:: - + sudo -E -u www-data php occ upgrade If this does not work properly, try the repair function:: @@ -154,5 +154,5 @@ If this does not work properly, try the repair function:: .. _nextcloud.com/install/: - https://nextcloud.com/install/ - + https://nextcloud.com/install/ + diff --git a/admin_manual/maintenance/package_upgrade.rst b/admin_manual/maintenance/package_upgrade.rst index 0bc89747de2..0ce271174db 100644 --- a/admin_manual/maintenance/package_upgrade.rst +++ b/admin_manual/maintenance/package_upgrade.rst @@ -1,17 +1,17 @@ ========================= Upgrade via snap packages ========================= - + Upgrade quickstart ------------------ -Nextcloud snap is an unofficial Nextcloud designed to be easy to install and simple to maintain. -The ideal Nextcloud snap is an "install and forget" Nextcloud instance that works on most -architectures and updates itself without needing administrative skills. -Combining Nextcloud with snapd makes it a perfect fit for IoT or scalable environments. +Nextcloud snap is an unofficial Nextcloud designed to be easy to install and simple to maintain. +The ideal Nextcloud snap is an "install and forget" Nextcloud instance that works on most +architectures and updates itself without needing administrative skills. +Combining Nextcloud with snapd makes it a perfect fit for IoT or scalable environments. Snapd is a secure and robust technology which the Nextcloud snap team has embraced. -However, the snap is opinionated. +However, the snap is opinionated. - Nextcloud snap uses recommended Apache. - Nextcloud snap uses recommended MySQL. @@ -28,31 +28,31 @@ Installation **All other distros** `be warned `_ -By default the latest stable Nextcloud snap release will be installed and it will automatically update to -subsequent stable releases, but there are `other releases available as well `_ +By default the latest stable Nextcloud snap release will be installed and it will automatically update to +subsequent stable releases, but there are `other releases available as well `_ and you have full control of `automatic updates `_. -After installation, Nextcloud will start automatically. -Assuming you and the device on which it was installed are on the same network, you will reach the Nextcloud -installation by visiting ``.local`` or the IP address of the instance in your browser. -If your hostname is ``localhost`` or ``localhost.localdomain``, like on an Ubuntu Core device, -``nextcloud.local`` will be used instead. +After installation, Nextcloud will start automatically. +Assuming you and the device on which it was installed are on the same network, you will reach the Nextcloud +installation by visiting ``.local`` or the IP address of the instance in your browser. +If your hostname is ``localhost`` or ``localhost.localdomain``, like on an Ubuntu Core device, +``nextcloud.local`` will be used instead. 1st login --------- -Upon visiting the Nextcloud installation for the first time, you will be prompted to enter an admin username +Upon visiting the Nextcloud installation for the first time, you will be prompted to enter an admin username and password before Nextcloud is initialised. This may take a while depending on resources and the device. After you provide that information you will be logged in and able to install apps, create users, and upload files. Upgrade tips ------------ -By default the Nextcloud snap will automatically update to subsequent stable releases. You may however upgrade +By default the Nextcloud snap will automatically update to subsequent stable releases. You may however upgrade manually too by issuing the command: ``sudo snap refresh nextcloud`` - + If the upgrade fails you can easily revert to the last working version by issuing the command: ``sudo snap revert nextcloud`` diff --git a/admin_manual/maintenance/restore.rst b/admin_manual/maintenance/restore.rst index 92f763df4e6..39b37c614d5 100644 --- a/admin_manual/maintenance/restore.rst +++ b/admin_manual/maintenance/restore.rst @@ -90,7 +90,7 @@ If the recovered backup is outdated the state of the clients may be more up to date than the state of the server. In this case also make sure to run the :ref:`maintenance:data-fingerprint ` command -afterwards. +afterwards. It changes the logic of the synchronisation algorithm to try an recover as much data as possible. Files missing on the server are therefore recovered from the clients diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst index 4f7fe6b33b4..dc0d0d43ad4 100644 --- a/admin_manual/maintenance/update.rst +++ b/admin_manual/maintenance/update.rst @@ -25,10 +25,10 @@ What does the updater do? .. note:: The built-in updater itself only replaces the existing files with the ones from the - version it updates to. The migration phase, which upgrades your database and apps, + version it updates to. The migration phase, which upgrades your database and apps, needs to be executed afterwards. In command line mode, the updater offers to trigger this - for you right after the code was successfully replaced by running ``occ upgrade`` for you. - In web mode, the updater finishes and then offers to send you back to your instance's main + for you right after the code was successfully replaced by running ``occ upgrade`` for you. + In web mode, the updater finishes and then offers to send you back to your instance's main URL to trigger the migration phase's web UI. The built-in updater performs these operations: @@ -231,25 +231,25 @@ To execute this, run the command with the ``--no-interaction`` option. (i.e. Troubleshooting --------------- -* The built-in updater logs all of its actions to a dedicated log file called - ``updater.log`` located in your configured ``datadirectory`` +* The built-in updater logs all of its actions to a dedicated log file called + ``updater.log`` located in your configured ``datadirectory`` (e.g. ``/var/www/html/data/updater.log``). This file can be helpful in isolating where things are failing. It will also be needed if you reach out for assistance on the community help forum (https://help.nextcloud.com). * If you are having problems using the Updater in web-mode, you should try using - command-line mode (if it's an option in your environment). Command-line avoids - issues with web server timeouts, which can be problematic since sometimes the + command-line mode (if it's an option in your environment). Command-line avoids + issues with web server timeouts, which can be problematic since sometimes the Updater can take a long time to complete certain steps. * If the problem seems to be during the backup step, you can try disabling the - backups the updater automatically creates of the installation files. Keep in + backups the updater automatically creates of the installation files. Keep in mind these backups do **not** include your data (which you are already hopefully doing). The backup step can only be disabled while in command-line mode. Append - the option ``--no-backup`` to the ``updater.phar`` command. + the option ``--no-backup`` to the ``updater.phar`` command. * If you accidentally say no when the command-line mode of the updater asks if you'd - like to run ``occ upgrade``, you can safely execute ``occ upgrade`` manually or + like to run ``occ upgrade``, you can safely execute ``occ upgrade`` manually or simply visit the URL of your instance to complete the database migrations and app upgrade phase. diff --git a/admin_manual/maintenance/upgrade.rst b/admin_manual/maintenance/upgrade.rst index ace3ad74ddc..49a6efc6dec 100644 --- a/admin_manual/maintenance/upgrade.rst +++ b/admin_manual/maintenance/upgrade.rst @@ -14,39 +14,39 @@ and update instructions for that installation method for the most accurate upgra There are two ways to upgrade an Archive based Nextcloud Server deployment: * With the :doc:`Built-in Updater ` (via the web or command-line interfaces). -* :doc:`Manually upgrading ` (using a downloaded Archive file) +* :doc:`Manually upgrading ` (using a downloaded Archive file) -The Built-in Updater, in either Web or command-line mode, is the easiest choice for most environments. +The Built-in Updater, in either Web or command-line mode, is the easiest choice for most environments. However some environments require the manual approach. Both approaches are covered fully here. .. important:: - Before upgrading, especially between major versions (e.g. v27.y.z -> v28.y.z) please review + Before upgrading, especially between major versions (e.g. v27.y.z -> v28.y.z) please review :ref:`critical changes` first. These are highlights of changes that may be required in your environment to accommodate changes in Nextcloud Server. These notes are periodically revised as - needed so it is also a good idea to revisit them periodically, such as when proceeding with maintenance + needed so it is also a good idea to revisit them periodically, such as when proceeding with maintenance upgrades. When an update is available for your Nextcloud server, by default you will receive -a notification. You can also check for available updates by visiting the Update section under +a notification. You can also check for available updates by visiting the Update section under **Administration settings->Overview** in the Web UI. -.. note:: - It is best to keep your Nextcloud server upgraded regularly. This means installing all maintenance/point releases +.. note:: + It is best to keep your Nextcloud server upgraded regularly. This means installing all maintenance/point releases and upgrading to new major releases before your current one reaches :doc:`end-of-life` status. - Examples of major releases are 27, 28, or 29. Maintenance releases are intermediate releases for each - major release that address critical functionality or security bugs. For example 28.0.4 and 29.0.2 are maintenance - releases. + Examples of major releases are 27, 28, or 29. Maintenance releases are intermediate releases for each + major release that address critical functionality or security bugs. For example 28.0.4 and 29.0.2 are maintenance + releases. Approaching Upgrades -------------------- -Nextcloud must be upgraded step by step: +Nextcloud must be upgraded step by step: * Before you can upgrade to the next major release, you need to upgrade to the latest point release of your current major version. * Then run the upgrade again to upgrade to the next major release's latest point release. * **You cannot skip major releases.** Please re-run the upgrade until you have reached the highest available (or applicable) release. * Example: 18.0.5 -> 18.0.11 -> 19.0.5 -> 20.0.2 -**Wait for background migrations to finish after major upgrades**. After upgrading to a new major version, some migrations are scheduled to run +**Wait for background migrations to finish after major upgrades**. After upgrading to a new major version, some migrations are scheduled to run as a background job. If you plan to upgrade directly to another major version (e.g. 24 -> 25 -> 26) you need to make sure these migrations were executed before starting the next upgrade. To do so you should run the ``cron.php`` file 2-3 times, for example:: diff --git a/admin_manual/occ_command.rst b/admin_manual/occ_command.rst index 321be5e56a4..a0fecf2089f 100644 --- a/admin_manual/occ_command.rst +++ b/admin_manual/occ_command.rst @@ -376,7 +376,7 @@ While setting a configuration value, multiple options are available: - ``--update-only`` only updates if a value is already stored .. note:: - See `Appconfig Concepts`_ to learn more about `typed value`, `lazy` and `sensitive` flag. + See `Appconfig Concepts`_ to learn more about `typed value`, `lazy` and `sensitive` flag. .. _Appconfig Concepts: https://docs.nextcloud.com/server/33/developer_manual/digging_deeper/config/appconfig.html#concept-overview @@ -698,11 +698,11 @@ This example will import from a file named personal.xcal in XML iCalendar format sudo -E -u www-data php occ calendar:import --format xcal dennis personal /tmp/personal.xcal This example will import from a file named personal.jcal in JSON iCalendar format to the calendar named personal of user dennis: :: - + sudo -E -u www-data php occ calendar:import --format jcal dennis personal /tmp/personal.jcal This example will import from standard input to the calendar named personal of user dennis: :: - + cat /tmp/personal.ics | sudo -E -u www-data php occ calendar:import dennis personal Misc diff --git a/admin_manual/office/installation.rst b/admin_manual/office/installation.rst index 01b40c5b01c..f32d7df4857 100644 --- a/admin_manual/office/installation.rst +++ b/admin_manual/office/installation.rst @@ -12,7 +12,7 @@ For manual installations there are multiple options to get Nextcloud Office depl There are packages for all major Linux distributions available which allow deploying a Collabora Online server through installing it through the regular package management. For an example installation guide on Ubuntu, see: :doc:`example-ubuntu` .. seealso:: - https://www.collaboraoffice.com/code/linux-packages/ + https://www.collaboraoffice.com/code/linux-packages/ https://sdk.collaboraonline.com/docs/installation/index.html @@ -23,7 +23,7 @@ For manual installations there are multiple options to get Nextcloud Office depl https://sdk.collaboraonline.com/docs/installation/CODE_Docker_image.html -- **Built-in CODE server** +- **Built-in CODE server** This app provides a built-in server with all of the document editing features of Collabora Online. Easy to install, for personal use or for small teams. A bit slower than a standalone server and without the advanced scalability features. Installation can be performed by enabling the according Nextcloud app. Further details can be found in the `app documentation `_. .. note:: @@ -33,10 +33,10 @@ For manual installations there are multiple options to get Nextcloud Office depl .. note:: In most scenarios running a dedicated Collabora Online server will require some sort of reverse proxy to be setup in front of it. For more details see :doc:`proxy`. - + .. toctree:: :hidden: - + example-ubuntu example-docker - proxy \ No newline at end of file + proxy diff --git a/admin_manual/office/migration.rst b/admin_manual/office/migration.rst index 45b500ea4d8..4236746659a 100644 --- a/admin_manual/office/migration.rst +++ b/admin_manual/office/migration.rst @@ -36,4 +36,4 @@ Required upgrade steps: Upgrade the docker image ************************ -For upgrading the docker images it is enough to pull the latest CODE image from Docker Hub. \ No newline at end of file +For upgrading the docker images it is enough to pull the latest CODE image from Docker Hub. diff --git a/admin_manual/office/troubleshooting.rst b/admin_manual/office/troubleshooting.rst index e1e15228aa7..4eb720593cd 100644 --- a/admin_manual/office/troubleshooting.rst +++ b/admin_manual/office/troubleshooting.rst @@ -39,13 +39,13 @@ Issue: Collabora Online doesn't handle my 100 users. Issue: Collabora Online doesn't work with Encryption. Yes, this is currently unsupported. - -Issue: Nextcloud Office could not connect to the built-in Collabora Online - Built-in CODE server. + +Issue: Nextcloud Office could not connect to the built-in Collabora Online - Built-in CODE server. Make sure that the Nextcloud instance is able to reach itself using the same hostname that is used to access through the browser. You might want to add your Nextcloud domain to /etc/hosts to ensure the connectivity if DNS resolution doesn't work for this: ``` - 127.0.0.1 cloud.yourdomain.com + 127.0.0.1 cloud.yourdomain.com ``` If you continue to see a warning about the WOPI allow list, make sure to also add the IP to the allow list under Settings/Administration/Office. diff --git a/admin_manual/release_notes/upgrade_to_28.rst b/admin_manual/release_notes/upgrade_to_28.rst index bd2cda9120f..6d705cf575d 100644 --- a/admin_manual/release_notes/upgrade_to_28.rst +++ b/admin_manual/release_notes/upgrade_to_28.rst @@ -21,9 +21,9 @@ Web server configuration Setup Checks ------------ -The setup checks (the ones visible under *Administration settings->Overview*) that previously ran from the web browser now run server-side rather than from the browser. +The setup checks (the ones visible under *Administration settings->Overview*) that previously ran from the web browser now run server-side rather than from the browser. -This means that some false positives may be triggered in existing installations after upgrading. This does not mean the checks are invalid or broken. It does mean that local configuration matters that may not have had obvious side effects previously may now prevent the tests from getting accurate results. +This means that some false positives may be triggered in existing installations after upgrading. This does not mean the checks are invalid or broken. It does mean that local configuration matters that may not have had obvious side effects previously may now prevent the tests from getting accurate results. In nearly all cases the resolution is one or more of the following: @@ -53,18 +53,18 @@ Previews for Office files using LibreOffice Nextcloud can generate previews for Office files using LibreOffice. -Since Nextcloud 28, you can also create previews for EMF files. +Since Nextcloud 28, you can also create previews for EMF files. To enable it, add ``'OC\Preview\EMF'`` to ``enabledPreviewProviders``. Until Nextcloud 28, the same LibreOffice user profile was used to generate the previews. LibreOffice can only be invoked once per user profile, so the generation of a preview for an office file would fail if another one were created right now. -Beginning with Nextcloud 28, a different LibreOffice user profile is used for each file. Downside: If you upload 100 emf files, you may end up with 100 LibreOffice +Beginning with Nextcloud 28, a different LibreOffice user profile is used for each file. Downside: If you upload 100 emf files, you may end up with 100 LibreOffice invocations. Though, you can use ``preview_concurrency_new`` and ``preview_concurrency_all`` to limit the number of previews that can be generated concurrently when php-sysvsem is available. -The configuration option ``preview_office_cl_parameters`` was removed with Nextcloud 28. -We expect LibreOffice to be started with the given parameters, so it's unfavorable to have a configuration option to change the parameters. -Please reach out to us via https://github.com/nextcloud/server/pull/41395 if that's causing any trouble for you. +The configuration option ``preview_office_cl_parameters`` was removed with Nextcloud 28. +We expect LibreOffice to be started with the given parameters, so it's unfavorable to have a configuration option to change the parameters. +Please reach out to us via https://github.com/nextcloud/server/pull/41395 if that's causing any trouble for you. .. tip:: Previews for EMF files can be enabled without a local LibreOffice installation if you are already using Nextcloud Office / Collabora. Make sure you have Nextcloud Office 8.3.0 installed and add ``'OCA\Richdocuments\Preview\EMF'`` to ``enabledPreviewProviders``. diff --git a/admin_manual/release_schedule.rst b/admin_manual/release_schedule.rst index 2e0660b9872..1eeda3b0b79 100644 --- a/admin_manual/release_schedule.rst +++ b/admin_manual/release_schedule.rst @@ -23,18 +23,18 @@ Nextcloud has two types of releases in the default release channel: 1. Major releases 2. Maintenance releases -**Major** releases of Nextcloud Server (e.g. ``28.X.X``) introduce new features and functionality. +**Major** releases of Nextcloud Server (e.g. ``28.X.X``) introduce new features and functionality. Every major release is, in turn, supported for *one year* via periodic **maintenance** releases (e.g. ``X.X.4``), which correct critical bugs and security vulnerabilities. Major releases ~~~~~~~~~~~~~~ -Major releases usually introduce new features and often also include changes "under the hood". These changes may be extensive. +Major releases usually introduce new features and often also include changes "under the hood". These changes may be extensive. A specific major release is indicated by the first part of the version string. For example, Nextcloud Server ``28.0.4`` is major release ``28``. And ``27.1.7`` is major release ``27``. -.. tip:: The highest numbered major release offers the latest features. While the lowest numbered major release offers the most time in the field. +.. tip:: The highest numbered major release offers the latest features. While the lowest numbered major release offers the most time in the field. .. note:: You may need to meet new system requirements before the Updater will offer you a new major version. Even if offered, there may be other changes required that the Updater cannot check for fully. We try to highlight these, in each new edition of the Admin Manual, in the Critical changes section of the *Release notes* chapter. @@ -43,13 +43,13 @@ A specific major release is indicated by the first part of the version string. F Maintenance releases ~~~~~~~~~~~~~~~~~~~~ -Maintenance releases deliberately **do not** introduce new features or breaking changes. This is meant to reduce the risks and impact associated with deploying updates so that critical bugs or security vulnerabilities can be rapidly and routinely addressed. +Maintenance releases deliberately **do not** introduce new features or breaking changes. This is meant to reduce the risks and impact associated with deploying updates so that critical bugs or security vulnerabilities can be rapidly and routinely addressed. Maintenance releases are published (generally simultaneously) for all stable major releases that have not reached end-of-life status. These releases should not have app compatibility concerns or introduce changes requiring retraining end users. -A specific maintenance release is indicated by the last part of the version number. For example, ``28.0.4`` is the *fourth* maintenance release for major version ``28`` of Nextcloud Server. It offers fixes for any critical bugs and security vulnerabilities addressed since the last maintenance release (``28.0.3`` in this example). +A specific maintenance release is indicated by the last part of the version number. For example, ``28.0.4`` is the *fourth* maintenance release for major version ``28`` of Nextcloud Server. It offers fixes for any critical bugs and security vulnerabilities addressed since the last maintenance release (``28.0.3`` in this example). .. note:: All critical bug fixes, including security related ones, are `backported `_ to **all** maintained major releases. @@ -69,7 +69,7 @@ This overlapping schedule and predictable cadence permits rapid development whil .. note:: Since every major release is supported for one year from initial release, the minimum you need to do to stay up-to-date is to install maintenance releases as they're published and upgrade to the next higher up major release when the one you're currently on reaches end-of-life status. Since maintenance releases only patch your Server with the latest bug and security vulnerability fixes - and do **not** introduce other significant changes - the risk of upgrading to a new maintenance release is far less than upgrading to a new major release. -End-of-life +End-of-life ~~~~~~~~~~~ End-of-life status means that support/maintenance ends. Maintenance releases cease for a major version on the one year anniversary of initial release. The major version then moves into end-of-life status and will not receive any further bug fixes or corrections for security vulnerabilities. @@ -90,9 +90,9 @@ Since multiple major releases are published throughout the year and each is supp Release channels ---------------- -By default all Nextcloud installations utilize the ``stable`` release channel. This channel delivers the latest features that are ready for most users at minimal risk. +By default all Nextcloud installations utilize the ``stable`` release channel. This channel delivers the latest features that are ready for most users at minimal risk. -.. note:: Nextcloud does staged roll-outs of new releases to further reduce the risk of widespread updates. New releases, particularly major releases, are usually only made available to a small percentage of systems initially. After a week (or more) has passed with no reported widespread critical bugs, more systems will be offered the update. Sometimes major versions are limited to <100% of systems until after the first maintenance (bug fix) release has been published. +.. note:: Nextcloud does staged roll-outs of new releases to further reduce the risk of widespread updates. New releases, particularly major releases, are usually only made available to a small percentage of systems initially. After a week (or more) has passed with no reported widespread critical bugs, more systems will be offered the update. Sometimes major versions are limited to <100% of systems until after the first maintenance (bug fix) release has been published. .. warning:: When using the ``stable`` channel it is possible you'll be *offered* a newer major version to upgrade to *even if* your existing major version has **not** reached end-of-life. It is up to you to decide whether to upgrade then or wait until a better time for deploying a major new release. On the other hand, new **maintenance** releases (within the major version you're already running) should be deployed as soon as possible to keep up-to-date with security and other critical bug fixes. @@ -110,7 +110,7 @@ Before upgrading from one one major release to another, we strongly recommend re Beta releases and Release candidates ------------------------------------ -Before a new final major release is published, typically at least four beta releases are published followed by two release candidates, with an interval of one week between each. +Before a new final major release is published, typically at least four beta releases are published followed by two release candidates, with an interval of one week between each. Before a new final maintenance release is published, one release candidate is published approximately one week beforehand. @@ -118,9 +118,9 @@ Anticipated dates for each release can be found on `detailed schedule `_ and report suspected bugs to `the GitHub repository `_. diff --git a/admin_manual/webhook_listeners/index.rst b/admin_manual/webhook_listeners/index.rst index 39019ac970d..abedad63010 100644 --- a/admin_manual/webhook_listeners/index.rst +++ b/admin_manual/webhook_listeners/index.rst @@ -7,7 +7,7 @@ Webhook Listeners Introduction ------------ -Nextcloud supports sending notifications to external services whenever something +Nextcloud supports sending notifications to external services whenever something important happens, such as when files are changed or updated. Overview @@ -46,7 +46,7 @@ Enable the ``webhook_listeners`` app that comes bundled with Nextcloud - e.g. Listening to events ------------------- -You can use the OCS API to add webhooks for specific events. See: +You can use the OCS API to add webhooks for specific events. See: `Register a new webhook `_. Note: When authenticating with the OCS API to register webhooks, the account you @@ -77,7 +77,7 @@ because you are inside a regular expression. You can also use additional comparison operators (``$e``, ``$ne``, ``$gt``, ``$gte``, ``$lt``, ``$lte``, ``$in``, ``$nin``) as well as logical operators (``$and``, ``$or``, ``$not``, ``$nor``). For example, use ``{ "time": { "$lt": 1711971024 } }`` to accept -only events prior to April 1st, 2024, and ``{ "time": { "$not": { "$lt": 1711971024 } }}`` +only events prior to April 1st, 2024, and ``{ "time": { "$not": { "$lt": 1711971024 } }}`` to accept events after April 1st, 2024. Speeding up webhook dispatch @@ -92,9 +92,9 @@ The following command will launch a worker for the webhook call background job: Screen or tmux session ^^^^^^^^^^^^^^^^^^^^^^ -Run the following ``occ`` command inside a screen or tmux session, preferably four +Run the following ``occ`` command inside a screen or tmux session, preferably four or more times, to enable parallel processing of multiple requests by different users -or the same user. It is best to run one command per screen session or tmux window/pane +or the same user. It is best to run one command per screen session or tmux window/pane to keep logs visible and make each worker easy to restart. .. code-block:: @@ -184,26 +184,26 @@ This is an exhaustive list of available events. It features the event ID and the "form": array{ "id": int, "hash": string, - "title": string, - "description": string, - "ownerId": string, - "fileId": string|null, - "fileFormat": string|null, - "created": int, - "access": int, - "expires": int, - "isAnonymous": bool, - "submitMultiple": bool, - "showExpiration": bool, - "lastUpdated": int, - "submissionMessage": string|null, - "state": int, + "title": string, + "description": string, + "ownerId": string, + "fileId": string|null, + "fileFormat": string|null, + "created": int, + "access": int, + "expires": int, + "isAnonymous": bool, + "submitMultiple": bool, + "showExpiration": bool, + "lastUpdated": int, + "submissionMessage": string|null, + "state": int, }, "submission": array{ "id": int, - "formId": int, - "userId": string, - "timestamp": int, + "formId": int, + "userId": string, + "timestamp": int, }, } } diff --git a/admin_manual/windmill_workflows/index.rst b/admin_manual/windmill_workflows/index.rst index ce15bb35257..e5fac8efe4d 100644 --- a/admin_manual/windmill_workflows/index.rst +++ b/admin_manual/windmill_workflows/index.rst @@ -23,10 +23,10 @@ Installation Setting up the workspace connection ----------------------------------- -In Windmill, you have separate workspaces available. To enable Windmill to react to events happening on your Nextcloud instance, you need to connect a workspace to your Nextcloud connection. This is only possible for workspace admins. +In Windmill, you have separate workspaces available. To enable Windmill to react to events happening on your Nextcloud instance, you need to connect a workspace to your Nextcloud connection. This is only possible for workspace admins. * In Windmill, open the workspace settings of the workspace you want to connect to Nextcloud via Settings -> Workspace -* Go to the Native Triggers tab and choose Nextcloud -> Configure OAuth +* Go to the Native Triggers tab and choose Nextcloud -> Configure OAuth * Follow the instructions to set up the OAuth connection * Click on "Connect" and accept the OAuth connection **with a Nextcloud admin account** or an account that has webhook admin privileges * If it shows "Connected", the workspace connection is successfully set up. @@ -46,14 +46,14 @@ see https://docs.nextcloud.com/server/33/developer_manual/_static/openapi.html#/ .. image:: images/windmill_add_trigger.png :alt: Screenshot of adding a Nextcloud trigger in a workflow -Now you can choose an event out of a drop-down list of events that your flow should react to. You can additionally fill in some parameters: +Now you can choose an event out of a drop-down list of events that your flow should react to. You can additionally fill in some parameters: * *Event filters* allows more fine grained filtering for which events should be used. The filter condition as well as the available events with their payloads is documented in the :ref:`webhook_listeners documentation`. * The *User ID filter* allows to define the user that can trigger a flow with their actions in Nextcloud. The webhook will only be called by requests from this user. Empty or null means no filtering. -* The *Headers* field allows to define an array of headers to be sent in a webhook call, which will mostly not be needed. +* The *Headers* field allows to define an array of headers to be sent in a webhook call, which will mostly not be needed. -You can add more than one trigger to a flow. +You can add more than one trigger to a flow. Nextcloud Scripts ----------------- @@ -139,7 +139,7 @@ All the scripts we provide have one input parameter in common: *nextcloud* needs * userId: the user id of the user the script should authenticate with * token: a password or token for that user -We advise to either add these credentials as a resource of the Nextcloud type to your workspace and refer to the resource in your script, or use the authentication credentials that are provided in the webhook callback. +We advise to either add these credentials as a resource of the Nextcloud type to your workspace and refer to the resource in your script, or use the authentication credentials that are provided in the webhook callback. For every flow that is triggered by a Nextcloud event, there are 2 sets of temporary credentials included: * the credentials for the user account that is saved in the initial OAuth connection, available as :code:`flow_input.authentication.owner` diff --git a/developer_manual/app_development/bootstrap.rst b/developer_manual/app_development/bootstrap.rst index 3a02928a837..246717af2d7 100644 --- a/developer_manual/app_development/bootstrap.rst +++ b/developer_manual/app_development/bootstrap.rst @@ -19,8 +19,8 @@ The `Application` class is the main entry point of an app. This class is optiona to register any services or run some code for every request. -Nextcloud will try to autoload the class from the namespace ``\OCA\\AppInfo\Application``, like -``\OCA\MyApp\AppInfo\Application``, where *MyApp* would be the name of your app. The file will therefore have the location ``myapp/lib/AppInfo/Application.php``. +Nextcloud will try to autoload the class from the namespace ``\OCA\\AppInfo\Application``, like +``\OCA\MyApp\AppInfo\Application``, where *MyApp* would be the name of your app. The file will therefore have the location ``myapp/lib/AppInfo/Application.php``. .. code-block:: php @@ -88,7 +88,7 @@ The class **must** extend ``OCP\AppFramework\App`` and may optionally implement } } - + Note that the context objects of the methods ``register`` and ``boot`` have different interfaces and thus have different capabilities appropriate for their stage. Bootstrapping process diff --git a/developer_manual/app_development/dav_extension.rst b/developer_manual/app_development/dav_extension.rst index f8bcbd14020..f5f7d3f0eeb 100644 --- a/developer_manual/app_development/dav_extension.rst +++ b/developer_manual/app_development/dav_extension.rst @@ -15,7 +15,7 @@ Registering a DAV plugin To register a server plugin in your app, register an event listener for ``OCA\DAV\Events\SabrePluginAddEvent`` (introduced in Nextcloud 28). In the listener's handler, add your DAV plugin to the server. - + For example: .. code-block:: php diff --git a/developer_manual/app_development/dependency_management.rst b/developer_manual/app_development/dependency_management.rst index c243f0a5fd0..a03290d7af1 100644 --- a/developer_manual/app_development/dependency_management.rst +++ b/developer_manual/app_development/dependency_management.rst @@ -38,79 +38,79 @@ Alternatively you can use [composer-bin-plugin](https://github.com/bamarni/compo 1. Install composer-bin-plugin according to their docs. - .. code-block:: shell + .. code-block:: shell - composer require --dev bamarni/composer-bin-plugin + composer require --dev bamarni/composer-bin-plugin 2. Install the tools you need in the vendor-bin directory. - .. code-block:: shell + .. code-block:: shell - composer bin psalm require --dev psalm/phar - composer bin psalm require --dev nextcloud/ocp:dev-master + composer bin psalm require --dev psalm/phar + composer bin psalm require --dev nextcloud/ocp:dev-master 3. Adjust some config (see below) - - Add in `composer.json`: - - .. code-block:: json - :caption: composer.json - - { - "extra": { - "bamarni-bin": { - "bin-links": true, - "forward-command": true - } - } - } - - - Add in `composer.json`: - - .. code-block:: json - :caption: composer.json - - { - "scripts": { - "post-install-cmd": [ - "[ $COMPOSER_DEV_MODE -eq 0 ] || composer bin all install --ansi" - ], - "post-update-cmd": [ - "[ $COMPOSER_DEV_MODE -eq 0 ] || composer bin all update --ansi" - ] - } - } - - - Adjust `psalm.xml`: - - Ensure the schemaLocation is correct: - - .. code-block:: xml - :caption: psalm.xml - - xsi:schemaLocation="https://getpsalm.org/schema/config vendor-bin/psalm/vendor/vimeo/psalm/config.xsd" - - - Ensure it has something like this: - - .. code-block:: xml - :caption: psalm.xml - - - - - - - - - - - - - - - Adjust `.php-cs-fixer.dist.php` - - .. code-block:: PHP - :caption: .php-cs-fixer.dist.php - - require_once __DIR__ . '/vendor-bin/cs-fixer/vendor/autoload.php'; + - Add in `composer.json`: + + .. code-block:: json + :caption: composer.json + + { + "extra": { + "bamarni-bin": { + "bin-links": true, + "forward-command": true + } + } + } + + - Add in `composer.json`: + + .. code-block:: json + :caption: composer.json + + { + "scripts": { + "post-install-cmd": [ + "[ $COMPOSER_DEV_MODE -eq 0 ] || composer bin all install --ansi" + ], + "post-update-cmd": [ + "[ $COMPOSER_DEV_MODE -eq 0 ] || composer bin all update --ansi" + ] + } + } + + - Adjust `psalm.xml`: + - Ensure the schemaLocation is correct: + + .. code-block:: xml + :caption: psalm.xml + + xsi:schemaLocation="https://getpsalm.org/schema/config vendor-bin/psalm/vendor/vimeo/psalm/config.xsd" + + - Ensure it has something like this: + + .. code-block:: xml + :caption: psalm.xml + + + + + + + + + + + + + + - Adjust `.php-cs-fixer.dist.php` + + .. code-block:: PHP + :caption: .php-cs-fixer.dist.php + + require_once __DIR__ . '/vendor-bin/cs-fixer/vendor/autoload.php'; Conflict example **************** diff --git a/developer_manual/app_development/info.rst b/developer_manual/app_development/info.rst index 9f098029cac..864631cb62d 100644 --- a/developer_manual/app_development/info.rst +++ b/developer_manual/app_development/info.rst @@ -287,9 +287,9 @@ dependencies/nextcloud * required * must contain a **min-version** attribute (maximum 3 digits separated by dots) * must contain a **max-version** attribute (maximum 3 digits separated by dots) - + .. note:: Dependencies `dependencies/php`, `dependencies/database` and `dependencies/lib` are checked at installation time (not on update time), hence applications need to stick to the dependencies supported by a major version of Nextcloud the moment an app releases support for that version, i.e. app needs to support the same PHP version-range the supported Nextcloud version supports. - + background-jobs/job * optional * must contain a php class which is run as background jobs diff --git a/developer_manual/app_development/intro.rst b/developer_manual/app_development/intro.rst index 22a13686b43..3a71f002a08 100644 --- a/developer_manual/app_development/intro.rst +++ b/developer_manual/app_development/intro.rst @@ -19,7 +19,7 @@ Edit an existing app Alternatively, if you would like to contribute to an existing app instead of creating a new one, first :doc:`set up the development environment <../getting_started/devenv>`, then create an `apps-extra` folder in the Nextcloud root directory:: cd /var/www/nextcloud/apps-extra - + You can then configure Nextcloud to run apps from this directory, by changing your `app_paths` system config in your `config.php` .. code-block:: php @@ -36,10 +36,10 @@ You can then configure Nextcloud to run apps from this directory, by changing yo 'writable' => false, ), ), - + Finally, clone the app to which you would like to contribute inside the `apps-extra` folder. For example: - git clone https://github.com/nextcloud/cookbook.git + git clone https://github.com/nextcloud/cookbook.git Enable the app -------------- diff --git a/developer_manual/app_development/translation_setup.rst b/developer_manual/app_development/translation_setup.rst index d62cea8d88a..6f8c4cbd63c 100644 --- a/developer_manual/app_development/translation_setup.rst +++ b/developer_manual/app_development/translation_setup.rst @@ -132,7 +132,7 @@ The translation tool requires ``gettext``, installable via:: The above tool generates a template that can be used to translate all strings of an app. This template is located in the folder :file:`translationfiles/template/` with the name :file:`myapp.pot`. It can be used by your favored translation tool such -as `Poedit `_. It then creates a :file:`.po` file. +as `Poedit `_. It then creates a :file:`.po` file. The :file:`.po` file needs to be placed in a folder named like the language code with the app name as filename - for example :file:`translationfiles/es/myapp.po`. After this step the tool needs to be invoked to transfer the po file into our diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_20.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_20.rst index f44a964e4bb..1fa62d21a38 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_20.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_20.rst @@ -25,7 +25,7 @@ The :ref:`unified search` replaces the traditional search input, Removed globals ^^^^^^^^^^^^^^^ -* ``escape-html``: use `the escape-html package ` or similar +* ``escape-html``: use `the escape-html package `_ or similar Deprecated global variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_24.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_24.rst index be2cfe21056..01cbb308e28 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_24.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_24.rst @@ -14,9 +14,9 @@ Make sure your ``appinfo/info.xml`` allows for Nextcloud 24. .. code-block:: xml - - - + + + Back-end changes ---------------- diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_25.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_25.rst index 79a25175940..3c231a9235b 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_25.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_25.rst @@ -14,9 +14,9 @@ Make sure your ``appinfo/info.xml`` allows for Nextcloud 25. .. code-block:: xml - - - + + + SCSS support removal ^^^^^^^^^^^^^^^^^^^^ diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst index b3c58e99af9..7c19ae828b3 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst @@ -31,7 +31,7 @@ Added APIs * File actions: to register file actions, please use the dedicated API from https://npmjs.org/@nextcloud/files or https://nextcloud-libraries.github.io/nextcloud-files/functions/registerFileAction.html -* New file menu: to register entries in the new file menu, please use the dedicated API from https://npmjs.org/@nextcloud/files or +* New file menu: to register entries in the new file menu, please use the dedicated API from https://npmjs.org/@nextcloud/files or https://nextcloud-libraries.github.io/nextcloud-files/functions/addNewFileMenuEntry.html * Reminder from 27, to interact with the Files app router, use ``OCP.Files.Router``. See :ref:`FilesAPI` * To Interact with the Files app data, please use the following events. All of them have a `Node object `_ as main parameter. @@ -196,12 +196,12 @@ If you want to support Nextcloud 27 and Nextcloud 28: .. code-block:: php - // @TODO: Remove method_exists when min-version="28" - if (method_exists(\OC::$server, 'createEventSource')) { - $eventSource = \OC::$server->createEventSource(); - } else { - $eventSource = \OCP\Server::get(IEventSourceFactory::class)->create(); - } + // @TODO: Remove method_exists when min-version="28" + if (method_exists(\OC::$server, 'createEventSource')) { + $eventSource = \OC::$server->createEventSource(); + } else { + $eventSource = \OCP\Server::get(IEventSourceFactory::class)->create(); + } Added events ^^^^^^^^^^^^ diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst index 839640347d8..365ce47e1d4 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst @@ -57,7 +57,7 @@ Removed APIs import { subscribe, unsubscribe } from '@nextcloud/event-bus' subscribe('notifications:action:execute', (event) => { - console.info('Notification action has been executed:', event.notification, event.action) + console.info('Notification action has been executed:', event.notification, event.action) }) Back-end changes @@ -141,7 +141,7 @@ Changed APIs - ``DATETIME_TZ`` for fields that will (de)serialized as ``\DateTime`` instances with both the time part set and with timezone information. - ``DATETIME_TZ_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set and with timezone information. -- It's now possible to paginate DAV requests with new headers. +- It's now possible to paginate DAV requests with new headers. - First request should contains the following headers: diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_33.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_33.rst index f03a0ed08e1..4a64da49fff 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_33.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_33.rst @@ -235,7 +235,7 @@ Removed APIs method when executing a ``UPDATE``, ``INSERT`` and ``DELETE`` statement, available since Nextcloud 20. Instead of catching a exceptions from the Doctrine DBAL package, you now need to catch ``OCP\DB\Exception`` - and check the `getReason``. For example, the following old code: + and check the ``getReason``. For example, the following old code: .. code-block:: php diff --git a/developer_manual/app_publishing_maintenance/maintainer.rst b/developer_manual/app_publishing_maintenance/maintainer.rst index ce174e57222..92e2434d455 100644 --- a/developer_manual/app_publishing_maintenance/maintainer.rst +++ b/developer_manual/app_publishing_maintenance/maintainer.rst @@ -30,4 +30,4 @@ The role of a Nextcloud app maintainer is to oversee all processes around an app + Monitor vulnerable dependencies, e.g. through Github security alerts, and release updates timely + Coordinate disclosed vulnerabilities with the Nextcloud security team -To avoid the so called `bus factor `_, it is highly recommended to have more than one maintainer for each app. Apps can have one primary maintainer and one or more backup maintainers. For transparency, it can make sense to declare the maintainers of an app in the app's repository README file, so that others know whom to contact. \ No newline at end of file +To avoid the so called `bus factor `_, it is highly recommended to have more than one maintainer for each app. Apps can have one primary maintainer and one or more backup maintainers. For transparency, it can make sense to declare the maintainers of an app in the app's repository README file, so that others know whom to contact. diff --git a/developer_manual/app_publishing_maintenance/release_automation.rst b/developer_manual/app_publishing_maintenance/release_automation.rst index 908c682a6c1..f68c8ee0a05 100644 --- a/developer_manual/app_publishing_maintenance/release_automation.rst +++ b/developer_manual/app_publishing_maintenance/release_automation.rst @@ -200,4 +200,4 @@ The process 2. Decide if this should be a normal or a pre-release, pre-releases will be uploaded as nightly version to the App Store. 3. When you are done, publish the release and wait a few minutes, you will see a request to approve the release, in Actions or your notifications. 4. If everything worked you find a ``appname.tar.gz`` as an attachment of the release. -5. Check the App Store for your newly released version, congratulations on your first automatically released app. \ No newline at end of file +5. Check the App Store for your newly released version, congratulations on your first automatically released app. diff --git a/developer_manual/basics/backgroundjobs.rst b/developer_manual/basics/backgroundjobs.rst index 6aec0860f25..5e0f13b7196 100644 --- a/developer_manual/basics/backgroundjobs.rst +++ b/developer_manual/basics/backgroundjobs.rst @@ -193,7 +193,7 @@ Beware that the reliability of the execution time is limited. Systems that do no // create an expiring share $this->jobList->scheduleAfter( - RevokeShare::class, + RevokeShare::class, ['id' => $shareId], $expiration, ); diff --git a/developer_manual/basics/dependency_injection.rst b/developer_manual/basics/dependency_injection.rst index f60ec6b66f6..c4dc39f8cc8 100644 --- a/developer_manual/basics/dependency_injection.rst +++ b/developer_manual/basics/dependency_injection.rst @@ -58,7 +58,7 @@ For example, consider the following pattern: .. code-block:: php :emphasize-lines: 10, 14 - /** + /** * Without dependency injection: */ diff --git a/developer_manual/basics/front-end/templates.rst b/developer_manual/basics/front-end/templates.rst index 57b19179a88..1ac87e2c46c 100644 --- a/developer_manual/basics/front-end/templates.rst +++ b/developer_manual/basics/front-end/templates.rst @@ -5,7 +5,7 @@ Templates .. sectionauthor:: Bernhard Posselt Nextcloud provides its own templating system which is basically plain PHP with some additional functions and preset variables. All the parameters which have been passed from the :doc:`controller <../controllers>` are available in an array called **$_[]**, e.g.:: - + array('key' => 'something') can be accessed through:: @@ -29,7 +29,7 @@ Printing values is done by using the :php:func:`p()` function, printing HTML is Including templates ------------------- -Templates can also include other templates by using the **$this->inc('templateName')** method. +Templates can also include other templates by using the **$this->inc('templateName')** method. .. code-block:: php @@ -43,7 +43,7 @@ The parent variables will also be available in the included templates, but shoul
I am included, but I can still access the parents variables!
- + inc('other_template', array('variable' => 'value'))); ?> Including CSS and JavaScript @@ -67,6 +67,6 @@ Including images To generate links to images use the **image_path** function: .. code-block:: php - + diff --git a/developer_manual/basics/storage/configuration.rst b/developer_manual/basics/storage/configuration.rst index e6d61832542..d3e9e55834e 100644 --- a/developer_manual/basics/storage/configuration.rst +++ b/developer_manual/basics/storage/configuration.rst @@ -122,7 +122,7 @@ App values are saved in the database per app and are useful for setting global a User values ----------- -User values are saved in the database per user and app and are good for saving user specific app settings: +User values are saved in the database per user and app and are good for saving user specific app settings: .. code-block:: php diff --git a/developer_manual/basics/storage/database.rst b/developer_manual/basics/storage/database.rst index d7dcca25510..683c62b9037 100644 --- a/developer_manual/basics/storage/database.rst +++ b/developer_manual/basics/storage/database.rst @@ -257,7 +257,7 @@ The following types (as part of ``OCP\DB\Types``) can be added for a field: * ``Types::TIME_IMMUTABLE`` - only the time is stored (without timezone) * ``Types::DATETIME_IMMUTABLE`` - date and time are stored, but without timezone * ``Types::DATETIME_TZ_IMMUTABLE`` - date and time are stored with timezone information - + * ``Types::DATE``, ``Types::TIME``, ``Types::DATETIME``, ``Types::DATETIME_TZ`` - similar as the immutable variants, but these will be provided as ``\DateTime`` objects. It is recommended to use the immutable variants as the internal state tracking of the ``Entity`` class only work with re-assignments, so any changes on this mutable types will not be tracked and the update method will not write back the changes to the database. diff --git a/developer_manual/basics/storage/filesystem.rst b/developer_manual/basics/storage/filesystem.rst index fddd71d21ae..25afdfd3731 100644 --- a/developer_manual/basics/storage/filesystem.rst +++ b/developer_manual/basics/storage/filesystem.rst @@ -59,7 +59,7 @@ For more details on the specific methods provided by file and folder nodes see t Writing to a file ----------------- -All methods return a Folder object on which files and folders can be accessed, or filesystem operations can be performed relatively to their root. For instance for writing to file:`nextcloud/data/myfile.txt` you should get the root folder and use: +All methods return a Folder object on which files and folders can be accessed, or filesystem operations can be performed relatively to their root. For instance for writing to :file:`nextcloud/data/myfile.txt` you should get the root folder and use: .. code-block:: php diff --git a/developer_manual/basics/storage/migrations.rst b/developer_manual/basics/storage/migrations.rst index 21f10f9eb47..37abd4543c4 100644 --- a/developer_manual/basics/storage/migrations.rst +++ b/developer_manual/basics/storage/migrations.rst @@ -39,18 +39,18 @@ With this step the new column gets created: .. code-block:: php public function changeSchema(IOutput $output, \Closure $schemaClosure, array $options) { - /** @var ISchemaWrapper $schema */ - $schema = $schemaClosure(); + /** @var ISchemaWrapper $schema */ + $schema = $schemaClosure(); - $table = $schema->getTable('twofactor_backupcodes'); + $table = $schema->getTable('twofactor_backupcodes'); - $table->addColumn('user_id', \OCP\DB\Types::STRING, [ - 'notnull' => true, - 'length' => 64, - ]); + $table->addColumn('user_id', \OCP\DB\Types::STRING, [ + 'notnull' => true, + 'length' => 64, + ]); - return $schema; - } + return $schema; + } 2. Migration 1: Post schema change @@ -131,7 +131,7 @@ Since 30, details about migrations are available to administrator as metadata ca #[ModifyColumn(table: 'other_table', name: 'this_field', type: ColumnType::BIGINT)] class Version30000Date20240729185117 extends SimpleMigrationStep { public function changeSchema(IOutput $output, Closure $schemaClosure, array $options) { - [...] + [...] } } diff --git a/developer_manual/client_apis/LoginFlow/index.rst b/developer_manual/client_apis/LoginFlow/index.rst index 8659dd475ef..134f3ecfcc2 100644 --- a/developer_manual/client_apis/LoginFlow/index.rst +++ b/developer_manual/client_apis/LoginFlow/index.rst @@ -46,7 +46,7 @@ On the final login the server will do a redirect to a url of the following forma .. code:: - nc://login/server:&user:&password: + nc://login/server:&user:&password: * ``server``: The address of the server to connect to. The server may specify a protocol (http or https). If no protocol is specified the client will assume https. * ``loginname``: The username that the client must use to login. **Note:** Keep in mind that this is the loginname and could be different from the username. For example the email address could be used to login but not for generating the webdav URL. You could fetch the actual username from the OCS API endpoint ``/ocs/v1.php/cloud/user``. @@ -54,7 +54,7 @@ On the final login the server will do a redirect to a url of the following forma .. note:: - ``loginname`` and ``password`` are encoded by PHP's `urlencode `_, which differs from `RFC 3986 `_. You may need to replace plus signs :code:`'+'` with spaces :code:`' '` before decoding. + ``loginname`` and ``password`` are encoded by PHP's `urlencode `_, which differs from `RFC 3986 `_. You may need to replace plus signs :code:`'+'` with spaces :code:`' '` before decoding. This information will be used by the client to create a new account. After this the webview is destroyed including all the state the webview holds. diff --git a/developer_manual/client_apis/OCS/ocs-api-overview.rst b/developer_manual/client_apis/OCS/ocs-api-overview.rst index 44d6abded3d..7e54c0b2208 100644 --- a/developer_manual/client_apis/OCS/ocs-api-overview.rst +++ b/developer_manual/client_apis/OCS/ocs-api-overview.rst @@ -47,55 +47,55 @@ This request returns the available metadata of a user. Admin users can see the i .. code:: - GET /ocs/v1.php/cloud/users/USERID + GET /ocs/v1.php/cloud/users/USERID .. code:: xml - - - - ok - 100 - OK - - - - - 1 - /path/to/storage/location/userid - userid - 1578283711000 - Database - - - 20632824998 - 842011482 - 21474836480 - 3.92 - 21474836480 - - user@foo.de - John Doe - John Doe - -
- https://example.com - - - 1st group - 2nd group - 3rd group - ... group - - de - de_DE - - 1 - 1 - - - + + + + ok + 100 + OK + + + + + 1 + /path/to/storage/location/userid + userid + 1578283711000 + Database + + + 20632824998 + 842011482 + 21474836480 + 3.92 + 21474836480 + + user@foo.de + John Doe + John Doe + +
+ https://example.com + + + 1st group + 2nd group + 3rd group + ... group + + de + de_DE + + 1 + 1 + + + User metadata - List user IDs @@ -105,29 +105,29 @@ This request returns a list containing all user IDs. Only admin users can query .. code:: - GET /ocs/v1.php/cloud/users + GET /ocs/v1.php/cloud/users .. code:: xml - - - - ok - 100 - OK - - - - - - 1st_user - 2nd_user - 3rd_user - ..._user - - - + + + + ok + 100 + OK + + + + + + 1st_user + 2nd_user + 3rd_user + ..._user + + + @@ -138,38 +138,38 @@ Clients can obtain capabilities provided by the Nextcloud server and its apps vi .. code:: - GET /ocs/v1.php/cloud/capabilities + GET /ocs/v1.php/cloud/capabilities .. code:: xml - - - - ok - 100 - OK - - - - - - 17 - 0 - 2 - 17.0.2 - - - - - - 60 - remote.php/webdav - - - - + + + + ok + 100 + OK + + + + + + 17 + 0 + 2 + 17.0.2 + + + + + + 60 + remote.php/webdav + + + + Theming capabilities @@ -179,20 +179,20 @@ Values of the theming app are exposed through the capabilities API, allowing cli .. code:: xml - - Nextcloud - https://nextcloud.com - A safe home for all your data - #0082c9 - #ffffff - #0082c9 - #aaaaaa - #555555 - http://cloud.example.com/index.php/apps/theming/logo?v=1 - http://cloud.example.com/index.php/apps/theming/logo?v=1 - - - + + Nextcloud + https://nextcloud.com + A safe home for all your data + #0082c9 + #ffffff + #0082c9 + #aaaaaa + #555555 + http://cloud.example.com/index.php/apps/theming/logo?v=1 + http://cloud.example.com/index.php/apps/theming/logo?v=1 + + + For elements like radio buttons, input borders and more, instead of the primary ``color`` value, the ``color-element-bright`` should be used on bright background and ``color-element-dark`` on dark background. This when the primary color is e.g. set to ``#000000`` the ``color-elemenet-dark`` will be set to ``#555555`` so items are still visible. In the Nextcloud web UI only the top header uses ``color``, everything else uses ``color-element-*``. @@ -215,7 +215,7 @@ To obtain a direct link: .. code:: - POST /ocs/v2.php/apps/dav/api/v1/direct + POST /ocs/v2.php/apps/dav/api/v1/direct With the :code:`fileId` in the body (so :code:`fileId=42` for example). This will then return you the link to use to obtain the file. diff --git a/developer_manual/client_apis/OCS/ocs-fulltextsearch-collections-api.rst b/developer_manual/client_apis/OCS/ocs-fulltextsearch-collections-api.rst index 0a7f01cb6a3..d4aaccaa5e7 100644 --- a/developer_manual/client_apis/OCS/ocs-fulltextsearch-collections-api.rst +++ b/developer_manual/client_apis/OCS/ocs-fulltextsearch-collections-api.rst @@ -78,32 +78,32 @@ The endpoint to get this list is: .. code-block:: console - $ curl -X GET "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/index?format=json&length=50" -H "OCS-APIRequest: true" -u "admin:password" - { - "ocs": { - "meta": { - "status": "ok", - "statuscode": 200, - "message": "OK" - }, - "data": [ - { - "url": "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/document/files/597996", - "status": 28 - } - ] - } - } + $ curl -X GET "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/index?format=json&length=50" -H "OCS-APIRequest: true" -u "admin:password" + { + "ocs": { + "meta": { + "status": "ok", + "statuscode": 200, + "message": "OK" + }, + "data": [ + { + "url": "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/document/files/597996", + "status": 28 + } + ] + } + } Details about the response: - ``url`` is the link to the document, - ``status`` is a bitflag based on this list: - * `1` => document has already been marked as indexed before, - * `4` => meta have been modified, - * `8` => content have been modified, - * `16` => parts have been modified - * `32` => document have been removed + * `1` => document has already been marked as indexed before, + * `4` => meta have been modified, + * `8` => content have been modified, + * `16` => parts have been modified + * `32` => document have been removed @@ -117,56 +117,56 @@ The endpoint to get data about a document is: .. code-block:: console - $ curl -X GET "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/document/files/597996?format=json" -H "OCS-APIRequest: true" -u "admin:password" - { - "ocs": { - "meta": { - "status": "ok", - "statuscode": 200, - "message": "OK" - }, - "data": { - "id": "597996", - "providerId": "files", - "access": { - "ownerId": "user1", - "users": ['user2', 'user3'], - "groups": ['group1'], - "circles": [], - "links": [] - }, - "index": { - "ownerId": "user1", - "providerId": "files", - "collection": "test", - "source": "files_local", - "documentId": "597996", - "lastIndex": 0, - "errors": [], - "errorCount": 0, - "status": 28, - "options": [] - }, - "title": "640-240-max.png", - "link": "https://cloud.example.net/index.php/f/597996", - "parts": { - "comments": " This is a comment !" - }, - "content": "VGhlIHF1aWNrIGJyb3duIGZveApqdW1wcyBvdmVyCnRoZSBsYXp5IGRvZy4=", - "isContentEncoded": 1 - } - } - } + $ curl -X GET "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/document/files/597996?format=json" -H "OCS-APIRequest: true" -u "admin:password" + { + "ocs": { + "meta": { + "status": "ok", + "statuscode": 200, + "message": "OK" + }, + "data": { + "id": "597996", + "providerId": "files", + "access": { + "ownerId": "user1", + "users": ['user2', 'user3'], + "groups": ['group1'], + "circles": [], + "links": [] + }, + "index": { + "ownerId": "user1", + "providerId": "files", + "collection": "test", + "source": "files_local", + "documentId": "597996", + "lastIndex": 0, + "errors": [], + "errorCount": 0, + "status": 28, + "options": [] + }, + "title": "640-240-max.png", + "link": "https://cloud.example.net/index.php/f/597996", + "parts": { + "comments": " This is a comment !" + }, + "content": "VGhlIHF1aWNrIGJyb3duIGZveApqdW1wcyBvdmVyCnRoZSBsYXp5IGRvZy4=", + "isContentEncoded": 1 + } + } + } .. note:: If `isContentEncoded` is set to 1, content needs to be decoded .. code-block:: console - $ php -r "echo base64_decode('VGhlIHF1aWNrIGJyb3duIGZveApqdW1wcyBvdmVyCnRoZSBsYXp5IGRvZy4=');" - The quick brown fox - jumps over - the lazy dog. + $ php -r "echo base64_decode('VGhlIHF1aWNrIGJyb3duIGZveApqdW1wcyBvdmVyCnRoZSBsYXp5IGRvZy4=');" + The quick brown fox + jumps over + the lazy dog. @@ -181,17 +181,17 @@ Once a document has been indexed in your external search engine, you have to not .. code-block:: console - $ curl -X POST "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/document/files/597996/done" -H "OCS-APIRequest: true" -u "admin:password" - { - "ocs": { - "meta": { - "status": "ok", - "statuscode": 200, - "message": "OK" - }, - "data": [] - } - } + $ curl -X POST "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/document/files/597996/done" -H "OCS-APIRequest: true" -u "admin:password" + { + "ocs": { + "meta": { + "status": "ok", + "statuscode": 200, + "message": "OK" + }, + "data": [] + } + } Once set as indexed, the document will only returns to the list of document to be (re-)indexed if they get modified. @@ -205,4 +205,4 @@ If needed, an endpoint is available to reset the whole index: .. code-block:: console - $ curl -X DELETE -u "user1:password" "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/index" -H "OCS-APIRequest: true" -k + $ curl -X DELETE -u "user1:password" "https://cloud.example.net/ocs/v2.php/apps/fulltextsearch/collection/test/index" -H "OCS-APIRequest: true" -k diff --git a/developer_manual/client_apis/OCS/ocs-openapi.rst b/developer_manual/client_apis/OCS/ocs-openapi.rst index d52bc6eba92..35e5bde4865 100644 --- a/developer_manual/client_apis/OCS/ocs-openapi.rst +++ b/developer_manual/client_apis/OCS/ocs-openapi.rst @@ -24,7 +24,7 @@ Before you start, make sure the following requirements are met: Install Psalm in your app as explained in ``_. - You need to Psalm >=``5.9.0``. Older versions contain a bug that prevents the changes in this tutorial from working. + You need Psalm ``>=5.9.0``. Older versions contain a bug that prevents the changes in this tutorial from working. Install and enable the required extensions as explained in :ref:`Required PHP extensions `. diff --git a/developer_manual/client_apis/OCS/ocs-recommendations-api.rst b/developer_manual/client_apis/OCS/ocs-recommendations-api.rst index 56da0981f31..024e25a4a19 100644 --- a/developer_manual/client_apis/OCS/ocs-recommendations-api.rst +++ b/developer_manual/client_apis/OCS/ocs-recommendations-api.rst @@ -38,4 +38,4 @@ Fetch user setting and recommendations + ``200 OK`` * Result: - `enabled` (boolean) True if recommendations are enabled for user. False otherwise. - - `recommendations` (list) List of recommended files and folders, independent of the users decision. \ No newline at end of file + - `recommendations` (list) List of recommended files and folders, independent of the users decision. diff --git a/developer_manual/client_apis/OCS/ocs-share-api.rst b/developer_manual/client_apis/OCS/ocs-share-api.rst index 12e35d38573..5687d30307f 100644 --- a/developer_manual/client_apis/OCS/ocs-share-api.rst +++ b/developer_manual/client_apis/OCS/ocs-share-api.rst @@ -154,7 +154,7 @@ Share attributes are used for more advanced flags like permissions. ] .. warning:: Since Nextcloud 30, the ``enabled`` key have bee renamed to ``value`` and supports more than boolean. - + Download permission """"""""""""""""""" diff --git a/developer_manual/client_apis/RemoteWipe/index.rst b/developer_manual/client_apis/RemoteWipe/index.rst index afa5b0d09bc..9c4dd03481c 100644 --- a/developer_manual/client_apis/RemoteWipe/index.rst +++ b/developer_manual/client_apis/RemoteWipe/index.rst @@ -35,7 +35,7 @@ Wiping the actual device ------------------------ The client must remove all user data linked to the account. This includes: - * caches + * caches * offline files * the actual account itself diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 2ff6a1934ab..79fdac046ff 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -62,25 +62,25 @@ Here is a JavaScript code sample to get you started: .. code-block:: javascript - import { createClient } from 'webdav' - import { generateRemoteUrl } from '@nextcloud/router' - import { getCurrentUser } from '@nextcloud/auth' - - const client = createClient(generateRemoteUrl('dav')) - const response = await client.getDirectoryContents(`/files/${getCurrentUser()?.uid}/folder`, { - details: true, - data: ` - - - - - - - - - - `, - }) + import { createClient } from 'webdav' + import { generateRemoteUrl } from '@nextcloud/router' + import { getCurrentUser } from '@nextcloud/auth' + + const client = createClient(generateRemoteUrl('dav')) + const response = await client.getDirectoryContents(`/files/${getCurrentUser()?.uid}/folder`, { + details: true, + data: ` + + + + + + + + + + `, + }) Requesting properties --------------------- @@ -91,26 +91,26 @@ You can request additional properties by sending a request body with the :code:` .. code-block:: xml - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + A note about namespaces URI ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -134,14 +134,14 @@ And here is how it should look in your DAV request: .. code-block:: xml - - - xmlns:ocm="http://open-cloud-mesh.org/ns"> - ... + + + xmlns:ocm="http://open-cloud-mesh.org/ns"> + ... Supported properties ^^^^^^^^^^^^^^^^^^^^ @@ -359,7 +359,7 @@ The contents of a folder can be listed by sending a :code:`PROPFIND` request to .. code:: - PROPFIND remote.php/dav/files/user/path/to/folder + PROPFIND remote.php/dav/files/user/path/to/folder Getting properties for just the folder ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -375,7 +375,7 @@ A file can be downloaded by sending a :code:`GET` request to the WebDAV url of t .. code:: - GET remote.php/dav/files/user/path/to/file + GET remote.php/dav/files/user/path/to/file .. _webdav-download-folders: @@ -390,17 +390,17 @@ The :code:`Accept` header must be set and contain the MIME type for ZIP archives .. code:: - GET remote.php/dav/files/user/path/to/folder - Accept: application/zip + GET remote.php/dav/files/user/path/to/folder + Accept: application/zip Optionally it is possible to only include some files from the folder in the archive by providing the files using the custom :code:`X-NC-Files` header: .. code:: - GET remote.php/dav/files/user/path/to/folder - Accept: application/zip - X-NC-Files: document.txt - X-NC-Files: image.png + GET remote.php/dav/files/user/path/to/folder + Accept: application/zip + X-NC-Files: document.txt + X-NC-Files: image.png As setting headers is not possible with HTML links it is also possible to provide this both options as query parameters. In this case the :code:`Accept` header value must be passed as the :code:`accept` query parameter. @@ -408,7 +408,7 @@ The optional files list can be provided as a JSON encoded array through the :cod .. code:: - GET remote.php/dav/files/user/path/to/folder?accept=zip&files=["image.png","document.txt"] + GET remote.php/dav/files/user/path/to/folder?accept=zip&files=["image.png","document.txt"] Uploading files --------------- @@ -417,7 +417,7 @@ A file can be uploaded by sending a :code:`PUT` request to the file and sending .. code:: - PUT remote.php/dav/files/user/path/to/file + PUT remote.php/dav/files/user/path/to/file Any existing file will be overwritten by the request. @@ -428,7 +428,7 @@ A folder can be created by sending a :code:`MKCOL` request to the folder. .. code:: - MKCOL remote.php/dav/files/user/path/to/new/folder + MKCOL remote.php/dav/files/user/path/to/new/folder Deleting files and folders (rfc4918_) ------------------------------------- @@ -437,7 +437,7 @@ A file or folder can be deleted by sending a :code:`DELETE` request to the file .. code:: - DELETE remote.php/dav/files/user/path/to/file + DELETE remote.php/dav/files/user/path/to/file When deleting a folder, its contents will be deleted recursively. @@ -448,8 +448,8 @@ A file or folder can be moved by sending a :code:`MOVE` request to the file or f .. code:: - MOVE remote.php/dav/files/user/path/to/file - Destination: https://cloud.example/remote.php/dav/files/user/new/location + MOVE remote.php/dav/files/user/path/to/file + Destination: https://cloud.example/remote.php/dav/files/user/new/location The overwrite behavior of the move can be controlled by setting the :code:`Overwrite` head to :code:`T` or :code:`F` to enable or disable overwriting respectively. @@ -460,8 +460,8 @@ A file or folder can be copied by sending a :code:`COPY` request to the file or .. code:: - COPY remote.php/dav/files/user/path/to/file - Destination: https://cloud.example/remote.php/dav/files/user/new/location + COPY remote.php/dav/files/user/path/to/file + Destination: https://cloud.example/remote.php/dav/files/user/new/location The overwrite behavior of the copy can be controlled by setting the :code:`Overwrite` head to :code:`T` or :code:`F` to enable or disable overwriting respectively. @@ -472,15 +472,15 @@ A file or folder can be marked as favorite by sending a :code:`PROPPATCH` reques .. code-block:: xml - PROPPATCH remote.php/dav/files/user/path/to/file - - - - - 1 - - - + PROPPATCH remote.php/dav/files/user/path/to/file + + + + + 1 + + + Setting the :code:`oc:favorite` property to ``1`` marks a file as favorite, setting it to ``0`` un-marks it as favorite. @@ -491,13 +491,13 @@ Favorites for a user can be retrieved by sending a :code:`REPORT` request and sp .. code-block:: xml - REPORT remote.php/dav/files/user/path/to/folder - - - - 1 - - + REPORT remote.php/dav/files/user/path/to/folder + + + + 1 + + File properties can be requested by adding a :code:`` element to the request listing the requested properties in the same way as it would be done for a :code:`PROPFIND` request. diff --git a/developer_manual/client_apis/WebDAV/search.rst b/developer_manual/client_apis/WebDAV/search.rst index c4e63aaa12f..43ad744b1f9 100644 --- a/developer_manual/client_apis/WebDAV/search.rst +++ b/developer_manual/client_apis/WebDAV/search.rst @@ -219,7 +219,7 @@ Get all png and jpg files over 10MB. - + Search for all common files (no directories) and limit the result of the last 5 files with ordering, last modified .. code-block:: xml diff --git a/developer_manual/client_apis/android_library/examples.rst b/developer_manual/client_apis/android_library/examples.rst index abe08a68464..405535dcad8 100644 --- a/developer_manual/client_apis/android_library/examples.rst +++ b/developer_manual/client_apis/android_library/examples.rst @@ -76,7 +76,7 @@ of the new folder. Code example ^^^^^^^^^^^^ -   + .. code-block:: java private void startFolderCreation(String newFolderPath) { @@ -265,7 +265,7 @@ used by a different file or folder. This one will be replaced by the former. Code example ^^^^^^^^^^^^ -   + .. code-block:: java private void startFileMove(String filePath, String newFilePath, boolean overwrite) { @@ -278,7 +278,7 @@ Code example if (operation instanceof MoveRemoteFileOperation) { if (result.isSuccess()) { // do your stuff here - } + } } // … } diff --git a/developer_manual/client_apis/files.rst b/developer_manual/client_apis/files.rst index 8d5cf320c0c..181663906a4 100644 --- a/developer_manual/client_apis/files.rst +++ b/developer_manual/client_apis/files.rst @@ -55,7 +55,7 @@ better understand the methods. /** * Trigger a route change on the files app - * + * * @param path the url path, eg: '/trashbin?dir=/Deleted' * @param replace replace the current history * @see https://router.vuejs.org/guide/essentials/navigation.html#navigate-to-a-different-location @@ -72,10 +72,10 @@ better understand the methods. * @see https://router.vuejs.org/guide/essentials/navigation.html#navigate-to-a-different-location */ goToRoute( - name?: string, - params?: Dictionary, - query?: Dictionary, - replace?: boolean, + name?: string, + params?: Dictionary, + query?: Dictionary, + replace?: boolean, ): Promise diff --git a/developer_manual/design/atomiccomponents.rst b/developer_manual/design/atomiccomponents.rst index 6a7f244a1d9..a8f225aff11 100644 --- a/developer_manual/design/atomiccomponents.rst +++ b/developer_manual/design/atomiccomponents.rst @@ -14,7 +14,7 @@ Buttons are used to initiate actions in your app. This may be a primary action, There are generally different types of buttons for different purposes: .. image:: ../images/button-primary-secondary.png - :alt: Primary button "Move" and secondary button "Copy" in Files + :alt: Primary button "Move" and secondary button "Copy" in Files * Primary buttons are used to indicate the main action ("Start call" button in Talk, "Move" in Files). The primary buttons are stylized in Nextcloud blue by default or the theming color when themed. These should only be used sparingly and ideally only for 1 visible action at a time. * Secondary buttons are used for actions that have lesser weight than the primary action ("Today" button in Calendar, "Copy" in Files) @@ -108,7 +108,7 @@ Text inputs are usually used for free-form inputs. Make sure that the label for .. _Dropdowns: Dropdowns -^^^^^^^^^ +^^^^^^^^^ `Dropdown Vue component `_. `Penpot dropdowns `_ @@ -139,7 +139,7 @@ Checkboxes and radio buttons Checkboxes and radio buttons are very common input methods. They are most commonly used in the :ref:`action menu`, :ref:`sidebar` and :ref:`settings`. -They should have a concise label, especially if they are inside an action menu. If more explanation is needed, you can also add a subline. +They should have a concise label, especially if they are inside an action menu. If more explanation is needed, you can also add a subline. Pickers ------- @@ -155,7 +155,7 @@ Datetime picker :alt: Files date picker -A user can quickly select dates, times and date ranges using the datetime picker. Use good default dates relevant to the task at hand. For example, in the case of setting an expiration date, unless the server has something enforced as default, 1 week is a good default. +A user can quickly select dates, times and date ranges using the datetime picker. Use good default dates relevant to the task at hand. For example, in the case of setting an expiration date, unless the server has something enforced as default, 1 week is a good default. .. _Color picker: @@ -168,9 +168,9 @@ Color picker :alt: Deck color picker -For certain elements of your UI you might want to allow people to set colors. This can easily be achieved using a color picker with some predefined colors. Be cautious about using different colors in the UI. In most Nextcloud apps like Deck and Calendar, user defined colors for UI elements are used sparingly and shown as a circle next to the element they refer to. +For certain elements of your UI you might want to allow people to set colors. This can easily be achieved using a color picker with some predefined colors. Be cautious about using different colors in the UI. In most Nextcloud apps like Deck and Calendar, user defined colors for UI elements are used sparingly and shown as a circle next to the element they refer to. -In addition to these 2 pickers, there is also the `emoji picker `_ and the `timezone picker `_ which can be also be used in your app. +In addition to these 2 pickers, there is also the `emoji picker `_ and the `timezone picker `_ which can be also be used in your app. .. _Tags: @@ -188,7 +188,7 @@ Tags are used by users to manage their items. They can be colored for easy ident Modal ----- -`Modal Vue component `_. +`Modal Vue component `_. `Penpot modals `_ .. image:: ../images/deck-card-modal.png @@ -257,7 +257,7 @@ User bubbles :alt: Talk user bubble -When referring to a user inline in your app, a user bubble element can be used. In Talk and Comments, user bubbles are used in the content when someone mentions a user. In Mail, it is used in the header for the recipients of the message. +When referring to a user inline in your app, a user bubble element can be used. In Talk and Comments, user bubbles are used in the content when someone mentions a user. In Mail, it is used in the header for the recipients of the message. .. _Counter bubbles: @@ -270,7 +270,7 @@ Counter bubbles .. image:: ../images/talk-counter-bubble.png :alt: Talk counter bubble -In Talk, it is used for showing which chats are unread and if you or your group is mentioned. +In Talk, it is used for showing which chats are unread and if you or your group is mentioned. .. _Empty content: @@ -295,6 +295,6 @@ Skeleton screens .. image:: ../images/skeleton-screen-talk.png :alt: Talk skeleton screen - :scale: 50% + :scale: 50% While the app is loading, it is best to show a skeleton view of the apps probable contents as loading feedback. A good example for this is Talk on web as well as Files and Talk on Android. diff --git a/developer_manual/design/foundations.rst b/developer_manual/design/foundations.rst index 44feeb9c225..0e601372309 100644 --- a/developer_manual/design/foundations.rst +++ b/developer_manual/design/foundations.rst @@ -22,7 +22,7 @@ Primary color While this is the primary color associated with Nextcloud and can be used to draw attention to an element, it is best to limit the usage of this to primary actions and other important elements. .. note:: - The primary color can be customized by admins through theming, but the default experience will be Nextcloud blue. If the primary color is themed to something very light like a shade of yellow, the text or header icons will be inverted to dark automatically. + The primary color can be customized by admins through theming, but the default experience will be Nextcloud blue. If the primary color is themed to something very light like a shade of yellow, the text or header icons will be inverted to dark automatically. * On web: ``var(--color-primary-element)`` * Android: uses default Material Design colors @@ -31,7 +31,7 @@ While this is the primary color associated with Nextcloud and can be used to dra Background color ^^^^^^^^^^^^^^^^ - + .. list-table:: * - .. figure:: ../images/colour-main-background.svg diff --git a/developer_manual/design/index.rst b/developer_manual/design/index.rst index 35e71db7d26..b4ed4cb7e00 100644 --- a/developer_manual/design/index.rst +++ b/developer_manual/design/index.rst @@ -2,11 +2,11 @@ Interface & interaction design ============================== -.. toctree:: - :maxdepth: 2 +.. toctree:: + :maxdepth: 2 - introduction - foundations - layout - layoutcomponents - atomiccomponents + introduction + foundations + layout + layoutcomponents + atomiccomponents diff --git a/developer_manual/design/layout.rst b/developer_manual/design/layout.rst index 9004511c672..40c43989d79 100644 --- a/developer_manual/design/layout.rst +++ b/developer_manual/design/layout.rst @@ -1,7 +1,7 @@ Layout ====== -These layout guidelines mainly focus on our web interface. On Android and iOS we closely follow the platform guidelines, namely `Material Design `_\ , and `Apple Human Interface Guidelines `_. +These layout guidelines mainly focus on our web interface. On Android and iOS we closely follow the platform guidelines, namely `Material Design `_\ , and `Apple Human Interface Guidelines `_. While deciding how you want your app to look, there are a number of factors to consider: @@ -42,7 +42,7 @@ Special case: no sidebar .. image:: ../images/activity-layout.png :alt: Activity layout - + Typically, a sidebar is used to show more information about an item. Sometimes this is not necessary as in the case of Activities. Then, the layout will have only a navigation and the main content. Special case: list in navigation diff --git a/developer_manual/desktop/building.rst b/developer_manual/desktop/building.rst index 842d79b4567..a09f02eb573 100644 --- a/developer_manual/desktop/building.rst +++ b/developer_manual/desktop/building.rst @@ -42,7 +42,7 @@ the repository is different for a fork than for the main official version. When cloning a GitHub repository, you have two options for authenticating your GitHub account, SSH or HTTPS. SSH requires additional setup but is more secure and simplifies things later on. For an explanation of the differences between -HTTPS and SSH, as well as instructions to set up SSH, see this `GitHub +HTTPS and SSH, as well as instructions to set up SSH, see this `GitHub help article`_ on the subject. .. _`GitHub help article`: https://help.github.com/en/articles/which-remote-url-should-i-use @@ -136,7 +136,7 @@ Then, in Terminal: % echo 'export QT_PATH=$(brew --prefix qt6)/bin' >> ~/.nextcloud_build_variables % echo 'export CMAKE_PREFIX_PATH=$(brew --prefix qt6);$(brew --prefix karchive)' >> ~/.nextcloud_build_variables - + .. note:: The name ``~/.nextcloud_build_variables`` is just a suggestion for convenience. You can use a different file or create an entire shell script, but this way of doing things is the simplest to explain. @@ -178,15 +178,15 @@ Then, in Terminal: By default Nextcloud Desktop will build in a protected directory on macOS, so you need to specify a build location. You can do this every time you build, or you can add it to your save build variables, like so: - + .. code-block:: bash % echo 'export CMAKE_INSTALL_PREFIX=~/Builds' >> ~/.nextcloud_build_variables # If you want to build a macOS app bundle for distribution % echo 'export BUILD_OWNCLOUD_OSX_BUNDLE=ON' >> ~/.nextcloud_build_variables - + Replace ``~/Builds`` with a different directory if you'd like the build to end up elsewhere. - + .. .. code-block:: bash @@ -209,7 +209,7 @@ System requirements - Windows 10 or Windows 11 -- `The desktop client code `_ +- `The desktop client code `_ - Python 3 - PowerShell - Microsoft Visual Studio 2022 and tools to compile C++ @@ -228,7 +228,7 @@ Setting up Microsoft Visual Studio .. image:: images/desktop-development-with-cpp.png :alt: Desktop development with C++ -Handling the dependencies +Handling the dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^ We handle the dependencies using `KDE Craft `_ because it is easy to set it up and it makes the maintenance much more reliable in all platforms. @@ -267,7 +267,7 @@ Compiling 4. To use the tools installed with Visual Studio, you need the following in your %PATH%: .. image:: images/path.png - :alt: Windows environment variables + :alt: Windows environment variables 5. Alternatively you can use the tools installed with KDE Craft by adding them to %PATH%: @@ -287,7 +287,7 @@ Compiling cd build cmake .. -G Ninja -DCMAKE_INSTALL_PREFIX=. -DCMAKE_PREFIX_PATH=C:\CraftRoot -DCMAKE_BUILD_TYPE=RelWithDebInfo cmake --build . --target install - + 7. Now you can use `Qt Creator `_ to import the build folder with its configurations to be able to work with the code. Windows Installer (i.e. Deployment) Build (Cross-Compile) @@ -366,14 +366,14 @@ To build the most up-to-date version of the client: 2. Create the build directory .. code-block:: bash - + $ mkdir client-build $ cd client-build 3. Configure the client build .. code-block:: bash - + $ cmake -DCMAKE_BUILD_TYPE="Debug" .. .. note:: You must use absolute paths for the ``include`` and ``library`` diff --git a/developer_manual/digging_deeper/config/appconfig.rst b/developer_manual/digging_deeper/config/appconfig.rst index e6be4bebe52..0aa44cb41ae 100644 --- a/developer_manual/digging_deeper/config/appconfig.rst +++ b/developer_manual/digging_deeper/config/appconfig.rst @@ -14,7 +14,7 @@ AppFramework The AppConfig API is also available in the AppFramework, allowing you to use it in your app. All of the methods are available in the ``OCP\AppFramework\Services\IAppConfig`` interface. Any of the methods below will automatically be scoped to your app, meaning you can omit the app id. - + .. code-block:: php registerEventListener(ContentProviderRegisterEvent::class, ContentProvider::class); + use OCA\MyApp\ContextChat\ContentProvider; + use OCP\ContextChat\Events\ContentProviderRegisterEvent; + // ... + $context->registerEventListener(ContentProviderRegisterEvent::class, ContentProvider::class); .. code-block:: php - class ContentProvider implements IContentProvider { - // ... - public function handle(Event $event): void { - if (!$event instanceof ContentProviderRegisterEvent) { - return; - } - $event->registerContentProvider('***appId***', '***providerId***', ContentProvider::class); - } + class ContentProvider implements IContentProvider { + // ... + public function handle(Event $event): void { + if (!$event instanceof ContentProviderRegisterEvent) { + return; + } + $event->registerContentProvider('***appId***', '***providerId***', ContentProvider::class); + } Any interaction with the content manager using the ContentManager's methods or listing the providers in the Assistant should automatically register the provider. @@ -123,17 +123,17 @@ Then, to submit content, wrap it in a list of ``\OCP\ContextChat\ContentItem`` o .. code-block:: php - new ContentItem( - string $itemId, - string $providerId, - string $title, - string $content, - string $documentType, - \DateTime $lastModified, - array $users, - ) + new ContentItem( + string $itemId, + string $providerId, + string $title, + string $content, + string $documentType, + \DateTime $lastModified, + array $users, + ) .. note:: - 1. Ensure that item IDs are unique across all users for a given provider. - 2. The app ID and provider ID both cannot contain double underscores, spaces, or colons. - 3. The ``documentType`` is a natural language term for your document type in English, e.g. ``E-Mail`` or ``Bookmark``. + 1. Ensure that item IDs are unique across all users for a given provider. + 2. The app ID and provider ID both cannot contain double underscores, spaces, or colons. + 3. The ``documentType`` is a natural language term for your document type in English, e.g. ``E-Mail`` or ``Bookmark``. diff --git a/developer_manual/digging_deeper/dashboard.rst b/developer_manual/digging_deeper/dashboard.rst index 99d5c3d001d..a5ac0290e7c 100644 --- a/developer_manual/digging_deeper/dashboard.rst +++ b/developer_manual/digging_deeper/dashboard.rst @@ -131,9 +131,9 @@ conditions only when really needed. .. code-block:: php - public function isEnabled(): bool { - return false; - } + public function isEnabled(): bool { + return false; + } Provide a user interface @@ -210,25 +210,25 @@ There are 3 types of buttons: .. code-block:: php - public function getWidgetButtons(string $userId): array { - return [ - new WidgetButton( - WidgetButton::TYPE_NEW, - 'https://somewhere.org', - $this->l10n->t('Create new element') - ), - new WidgetButton( - WidgetButton::TYPE_MORE, - 'https://my.nextcloud.org/apps/your-app/', - $this->l10n->t('More notifications') - ), - new WidgetButton( - WidgetButton::TYPE_SETUP, - 'https://my.nextcloud.org/apps/settings/user', - $this->l10n->t('Configure') - ), - ]; - } + public function getWidgetButtons(string $userId): array { + return [ + new WidgetButton( + WidgetButton::TYPE_NEW, + 'https://somewhere.org', + $this->l10n->t('Create new element') + ), + new WidgetButton( + WidgetButton::TYPE_MORE, + 'https://my.nextcloud.org/apps/your-app/', + $this->l10n->t('More notifications') + ), + new WidgetButton( + WidgetButton::TYPE_SETUP, + 'https://my.nextcloud.org/apps/settings/user', + $this->l10n->t('Configure') + ), + ]; + } The IIconWidget interface ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -238,11 +238,11 @@ it returns the URL to the img/app.svg file in your app. .. code-block:: php - public function getIconUrl(): string { - return $this->urlGenerator->getAbsoluteURL( - $this->urlGenerator->imagePath(Application::APP_ID, 'app.svg') - ); - } + public function getIconUrl(): string { + return $this->urlGenerator->getAbsoluteURL( + $this->urlGenerator->imagePath(Application::APP_ID, 'app.svg') + ); + } The IOptionWidget interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -253,9 +253,9 @@ the widget item icons should be rounded or kept as squares. .. code-block:: php - public function getWidgetOptions(): WidgetOptions { - return new WidgetOptions(true); - } + public function getWidgetOptions(): WidgetOptions { + return new WidgetOptions(true); + } The IAPIWidget interface ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/developer_manual/digging_deeper/declarative_settings.rst b/developer_manual/digging_deeper/declarative_settings.rst index d4632474e25..85493929562 100644 --- a/developer_manual/digging_deeper/declarative_settings.rst +++ b/developer_manual/digging_deeper/declarative_settings.rst @@ -9,8 +9,8 @@ Declarative settings .. versionadded:: 29.0.0 With Nextcloud 29 there is a new way to define app settings in a declarative way. -This means that you can just register your settings schema -without writing a custom settings handling front-end and back-end code +This means that you can just register your settings schema +without writing a custom settings handling front-end and back-end code (except when more complex settings logic or design is required). Registering settings schema @@ -25,7 +25,7 @@ Additionally, you can register multiple declarative parameter schemes per applic .. note:: - Form fields ids (configkeys) must be unique within an app. + Form fields ids (configkeys) must be unique within an app. Class-based schema registration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -33,42 +33,42 @@ Class-based schema registration To register a declarative settings schema using a class, you need to create a class that implements the ``OCP\Settings\IDeclarativeSettingsForm`` interface: .. code-block:: php - :emphasize-lines: 8,11 - - 'my_declarative_settings_form', // unique form id - 'priority' => 10, // declarative section priority (ordering) - 'section_type' => DeclarativeSettingsTypes::SECTION_TYPE_ADMIN, // admin, personal - 'section_id' => 'my_section_id', // existing section id or your custom section id - 'storage_type' => DeclarativeSettingsTypes::STORAGE_TYPE_INTERNAL, // external, internal (handled by core to store in appconfig and preferences) - 'title' => 'MyApp settings title', // NcSettingsSection name - 'description' => 'My app settings section description', // NcSettingsSection description - 'doc_url' => '', // NcSettingsSection doc_url for documentation or help page, empty string if not needed - 'fields' => [ - [ - 'id' => 'my_field_key', // configkey - 'title' => 'Field title', // name or label - 'description' => 'Additional setting hint or description', // hint - 'type' => DeclarativeSettingsTypes::MULTI_SELECT, - 'options' => ['foo', 'bar', 'baz'], - 'placeholder' => 'Select some multiple options', // input placeholder - 'default' => ['foo', 'bar'], - ], - ] - ]; - } - } + :emphasize-lines: 8,11 + + 'my_declarative_settings_form', // unique form id + 'priority' => 10, // declarative section priority (ordering) + 'section_type' => DeclarativeSettingsTypes::SECTION_TYPE_ADMIN, // admin, personal + 'section_id' => 'my_section_id', // existing section id or your custom section id + 'storage_type' => DeclarativeSettingsTypes::STORAGE_TYPE_INTERNAL, // external, internal (handled by core to store in appconfig and preferences) + 'title' => 'MyApp settings title', // NcSettingsSection name + 'description' => 'My app settings section description', // NcSettingsSection description + 'doc_url' => '', // NcSettingsSection doc_url for documentation or help page, empty string if not needed + 'fields' => [ + [ + 'id' => 'my_field_key', // configkey + 'title' => 'Field title', // name or label + 'description' => 'Additional setting hint or description', // hint + 'type' => DeclarativeSettingsTypes::MULTI_SELECT, + 'options' => ['foo', 'bar', 'baz'], + 'placeholder' => 'Select some multiple options', // input placeholder + 'default' => ['foo', 'bar'], + ], + ] + ]; + } + } The ``OCP\Settings\IDeclarativeSettingsForm`` interface has only one method ``getSchema`` that should return an array with the settings schema. @@ -76,27 +76,27 @@ The ``OCP\Settings\IDeclarativeSettingsForm`` interface has only one method ``ge After that, you can register schema class using ``IRegistrationContext->registerDeclarativeSettings`` method: .. code-block:: php - :emphasize-lines: 9,17 + :emphasize-lines: 9,17 - registerDeclarativeSettings(MyDeclarativeSettingsForm::class); - } - } + public function register(IRegistrationContext $context): void { + $context->registerDeclarativeSettings(MyDeclarativeSettingsForm::class); + } + } Event-based schema registration @@ -106,59 +106,59 @@ To register a declarative settings schema using an event system you need to impl .. code-block:: php - registerSchema('my_app', [ - // your declarative settings schema here - ]); - } - } + $event->registerSchema('my_app', [ + // your declarative settings schema here + ]); + } + } And register the event listener as usually in your ``AppInfo/Application.php`` registration context: .. code-block:: php - :emphasize-lines: 9,10,18 + :emphasize-lines: 9,10,18 - registerEventListener(DeclarativeSettingsRegisterFormEvent::class, RegisterDeclarativeSettingsListener::class); - } - } + public function register(IRegistrationContext $context): void { + $context->registerEventListener(DeclarativeSettingsRegisterFormEvent::class, RegisterDeclarativeSettingsListener::class); + } + } Handling settings storage @@ -177,7 +177,7 @@ Internal (``storage_type='internal'``) storage type is handled by core, you don' Section type admin ****************** -For declarative settings schema with ``section_type`` set to ``DeclarativeSettingsTypes::SECTION_TYPE_ADMIN`` - settings values +For declarative settings schema with ``section_type`` set to ``DeclarativeSettingsTypes::SECTION_TYPE_ADMIN`` - settings values are stored in ``appconfig`` table. Accessible via ``OCP\IConfig->getAppValue`` interface. @@ -185,7 +185,7 @@ Accessible via ``OCP\IConfig->getAppValue`` interface. Section type personal ********************* -For declarative settings schema with ``section_type`` set to ``DeclarativeSettingsTypes::SECTION_TYPE_PERSONAL`` - settings values +For declarative settings schema with ``section_type`` set to ``DeclarativeSettingsTypes::SECTION_TYPE_PERSONAL`` - settings values are user specific and stored in ``preferences`` table. Accessible via ``OCP\IConfig->getUserValue`` interface. @@ -201,103 +201,103 @@ Handling of an external (``storage_type='external'``) storage type is always don Example of DeclarativeSettingsGetValueEvent event listener: .. code-block:: php - :emphasize-lines: 27,28 + :emphasize-lines: 27,28 - getApp() !== 'my_app') { - return; - } + // Always check if the event is related to your app declarative settings + if ($event->getApp() !== 'my_app') { + return; + } - $value = $this->config->getUserValue($event->getUser()->getUID(), $event->getApp(), $event->getFieldId()); - $event->setValue($value); - } - } + $value = $this->config->getUserValue($event->getUser()->getUID(), $event->getApp(), $event->getFieldId()); + $event->setValue($value); + } + } Example of DeclarativeSettingsSetValueEvent event listener: .. code-block:: php - :emphasize-lines: 27 + :emphasize-lines: 27 - getApp() !== 'my_app') { - return; - } + // Always check if the event is related to your app declarative settings + if ($event->getApp() !== 'my_app') { + return; + } - $this->config->setUserValue($event->getUser()->getUID(), $event->getApp(), $event->getFieldId(), $event->getValue()); - } - } + $this->config->setUserValue($event->getUser()->getUID(), $event->getApp(), $event->getFieldId(), $event->getValue()); + } + } Register get/set listeners -------------------------- .. code-block:: php - :emphasize-lines: 9,10,11,12,20,21 + :emphasize-lines: 9,10,11,12,20,21 - registerEventListener(DeclarativeSettingsGetValueEvent::class, GetDeclarativeSettingsValueListener::class); - $context->registerEventListener(DeclarativeSettingsSetValueEvent::class, SetDeclarativeSettingsValueListener::class); - } - } + public function register(IRegistrationContext $context): void { + $context->registerEventListener(DeclarativeSettingsGetValueEvent::class, GetDeclarativeSettingsValueListener::class); + $context->registerEventListener(DeclarativeSettingsSetValueEvent::class, SetDeclarativeSettingsValueListener::class); + } + } @@ -322,7 +322,7 @@ The examples of each field type are listed below. .. note:: - Field order is the same as in the schema array. + Field order is the same as in the schema array. Basic input types @@ -331,124 +331,124 @@ Basic input types For text, password, email, tel, url, number schema is similar: .. figure:: ../images/declarative_settings_input_fields.png - :alt: Declarative settings input fields (text, password, email, tel, url, number) + :alt: Declarative settings input fields (text, password, email, tel, url, number) .. code-block:: php - [ - 'id' => 'my_field_unique_id', // configkey - 'title' => 'Default text field', // label - 'description' => 'Set some simple text setting', // hint - 'type' => DeclarativeSettingsTypes::TEXT, // text, password, email, tel, url, number - 'placeholder' => 'Enter text setting', // placeholder - 'default' => 'foo', - ], + [ + 'id' => 'my_field_unique_id', // configkey + 'title' => 'Default text field', // label + 'description' => 'Set some simple text setting', // hint + 'type' => DeclarativeSettingsTypes::TEXT, // text, password, email, tel, url, number + 'placeholder' => 'Enter text setting', // placeholder + 'default' => 'foo', + ], Checkbox and Multi-checkbox --------------------------- .. figure:: ../images/declarative_settings_checkboxes.png - :alt: checkbox and multi-checkbox field types + :alt: checkbox and multi-checkbox field types .. code-block:: php - [ - 'id' => 'my_checkbox_field', - 'title' => 'Toggle something', - 'description' => 'Select checkbox option setting', - 'type' => DeclarativeSettingsTypes::CHECKBOX, // checkbox, multiple-checkbox - 'label' => 'Verify something if enabled', - 'default' => false, - ], - [ - 'id' => 'my_multicheckbox_field', - 'title' => 'Multiple checkbox toggles, describing one setting, checked options are saved as an JSON object {foo: true, bar: false}', - 'description' => 'Select checkbox option setting', - 'type' => DeclarativeSettingsTypes::MULTI_CHECKBOX, // checkbox, multi-checkbox - 'default' => ['foo' => true, 'bar' => true, 'baz' => true], - 'options' => [ - [ - 'name' => 'Foo', - 'value' => 'foo', // multiple-checkbox configkey - ], - [ - 'name' => 'Bar', - 'value' => 'bar', - ], - [ - 'name' => 'Baz', - 'value' => 'baz', - ], - [ - 'name' => 'Qux', - 'value' => 'qux', - ], - ], - ], + [ + 'id' => 'my_checkbox_field', + 'title' => 'Toggle something', + 'description' => 'Select checkbox option setting', + 'type' => DeclarativeSettingsTypes::CHECKBOX, // checkbox, multiple-checkbox + 'label' => 'Verify something if enabled', + 'default' => false, + ], + [ + 'id' => 'my_multicheckbox_field', + 'title' => 'Multiple checkbox toggles, describing one setting, checked options are saved as an JSON object {foo: true, bar: false}', + 'description' => 'Select checkbox option setting', + 'type' => DeclarativeSettingsTypes::MULTI_CHECKBOX, // checkbox, multi-checkbox + 'default' => ['foo' => true, 'bar' => true, 'baz' => true], + 'options' => [ + [ + 'name' => 'Foo', + 'value' => 'foo', // multiple-checkbox configkey + ], + [ + 'name' => 'Bar', + 'value' => 'bar', + ], + [ + 'name' => 'Baz', + 'value' => 'baz', + ], + [ + 'name' => 'Qux', + 'value' => 'qux', + ], + ], + ], Radio ----- .. figure:: ../images/declarative_settings_radio.png - :alt: radio field type + :alt: radio field type .. code-block:: php - [ - 'id' => 'my_radio_field', - 'title' => 'Radio toggles, describing one setting like single select', - 'description' => 'Select radio option setting', - 'type' => DeclarativeSettingsTypes::RADIO, // radio (NcCheckboxRadioSwitch type radio) - 'label' => 'Select single toggle', - 'default' => 'foo', - 'options' => [ - [ - 'name' => 'First radio', // NcCheckboxRadioSwitch display name - 'value' => 'foo' // NcCheckboxRadioSwitch value - ], - [ - 'name' => 'Second radio', - 'value' => 'bar' - ], - [ - 'name' => 'Third radio', - 'value' => 'baz' - ], - ], - ], + [ + 'id' => 'my_radio_field', + 'title' => 'Radio toggles, describing one setting like single select', + 'description' => 'Select radio option setting', + 'type' => DeclarativeSettingsTypes::RADIO, // radio (NcCheckboxRadioSwitch type radio) + 'label' => 'Select single toggle', + 'default' => 'foo', + 'options' => [ + [ + 'name' => 'First radio', // NcCheckboxRadioSwitch display name + 'value' => 'foo' // NcCheckboxRadioSwitch value + ], + [ + 'name' => 'Second radio', + 'value' => 'bar' + ], + [ + 'name' => 'Third radio', + 'value' => 'baz' + ], + ], + ], Select and Multi-select ----------------------- .. figure:: ../images/declarative_settings_select.png - :alt: select field type + :alt: select field type .. code-block:: php - [ - 'id' => 'my_select_field', - 'title' => 'Selection', - 'description' => 'Select some option setting', - 'type' => DeclarativeSettingsTypes::SELECT, // select, radio, multi-select - 'options' => ['foo', 'bar', 'baz'], - 'placeholder' => 'Select some option setting', - 'default' => 'foo', - ], + [ + 'id' => 'my_select_field', + 'title' => 'Selection', + 'description' => 'Select some option setting', + 'type' => DeclarativeSettingsTypes::SELECT, // select, radio, multi-select + 'options' => ['foo', 'bar', 'baz'], + 'placeholder' => 'Select some option setting', + 'default' => 'foo', + ], .. figure:: ../images/declarative_settings_multi_select.png - :alt: multi-select field type + :alt: multi-select field type .. code-block:: php - [ - 'id' => 'my_multi_select_field', // configkey - 'title' => 'Multi-selection', // name or label - 'description' => 'Select some option setting', // hint - 'type' => DeclarativeSettingsTypes::MULTI_SELECT, // select, radio, multi-select - 'options' => ['foo', 'bar', 'baz'], // simple options for select, radio, multi-select - 'placeholder' => 'Select some multiple options', // input placeholder - 'default' => ['foo', 'bar'], - ], + [ + 'id' => 'my_multi_select_field', // configkey + 'title' => 'Multi-selection', // name or label + 'description' => 'Select some option setting', // hint + 'type' => DeclarativeSettingsTypes::MULTI_SELECT, // select, radio, multi-select + 'options' => ['foo', 'bar', 'baz'], // simple options for select, radio, multi-select + 'placeholder' => 'Select some multiple options', // input placeholder + 'default' => ['foo', 'bar'], + ], Sensitive field type @@ -460,27 +460,27 @@ The values of such fields are stored in an encrypted form in the database and ar .. code-block:: php - [ - 'id' => 'test_sensitive_field', - 'title' => 'Sensitive text field', - 'description' => 'Set some secure value setting that is stored encrypted', - 'type' => DeclarativeSettingsTypes::TEXT, - 'label' => 'Sensitive field', - 'placeholder' => 'Set secure value', - 'default' => '', - 'sensitive' => true, // only for TEXT, PASSWORD types - ], - [ - 'id' => 'test_sensitive_field_2', - 'title' => 'Sensitive password field', - 'description' => 'Set some password setting that is stored encrypted', - 'type' => DeclarativeSettingsTypes::PASSWORD, - 'label' => 'Sensitive field', - 'placeholder' => 'Set secure value', - 'default' => '', - 'sensitive' => true, // only for TEXT, PASSWORD types - ], + [ + 'id' => 'test_sensitive_field', + 'title' => 'Sensitive text field', + 'description' => 'Set some secure value setting that is stored encrypted', + 'type' => DeclarativeSettingsTypes::TEXT, + 'label' => 'Sensitive field', + 'placeholder' => 'Set secure value', + 'default' => '', + 'sensitive' => true, // only for TEXT, PASSWORD types + ], + [ + 'id' => 'test_sensitive_field_2', + 'title' => 'Sensitive password field', + 'description' => 'Set some password setting that is stored encrypted', + 'type' => DeclarativeSettingsTypes::PASSWORD, + 'label' => 'Sensitive field', + 'placeholder' => 'Set secure value', + 'default' => '', + 'sensitive' => true, // only for TEXT, PASSWORD types + ], .. figure:: ../images/declarative_settings_sensitive.png - :alt: sensitive fields + :alt: sensitive fields diff --git a/developer_manual/digging_deeper/files-metadata.rst b/developer_manual/digging_deeper/files-metadata.rst index c00e3b39915..0e1384dc558 100644 --- a/developer_manual/digging_deeper/files-metadata.rst +++ b/developer_manual/digging_deeper/files-metadata.rst @@ -66,14 +66,14 @@ on a background job by requesting a re-run by calling the method ``MetadataLiveE class Application extends App implements IBootstrap { public function __construct(array $params = []) { parent::__construct('my_app', $params); - } + } public function register(IRegistrationContext $context): void { $context->registerEventListener(MetadataLiveEvent::class, UpdateFilesMetadata::class); $context->registerEventListener(MetadataBackgroundEvent::class, UpdateFilesMetadata::class); } - public function boot(IBootContext $context): void { + public function boot(IBootContext $context): void { } } diff --git a/developer_manual/digging_deeper/groupware/calendar_provider.rst b/developer_manual/digging_deeper/groupware/calendar_provider.rst index 259801f3e0a..55c5e4ab456 100644 --- a/developer_manual/digging_deeper/groupware/calendar_provider.rst +++ b/developer_manual/digging_deeper/groupware/calendar_provider.rst @@ -71,10 +71,10 @@ Calendars that only return `ICalendar` are implicitly read-only. If your app's c } -Handling iMIP data +Handling iMIP data ~~~~~~~~~~~~~~~~~~ -You may implement the ``IHandleIMipMessage`` interface to process iMIP data you receive in a client and want to pass on for processing to the backend. +You may implement the ``IHandleIMipMessage`` interface to process iMIP data you receive in a client and want to pass on for processing to the backend. Please be aware that there are some security considerations to take into account. You can find more information on these and the conditions that have to be fulfilled for iMIP data to be processed in the `RFC `_ @@ -162,7 +162,7 @@ There are some basic methods that need to be implemented on each calendar object Removal of entries !!!!!!!!!!!!!!!!!! -Removal of calendar events is not allowed in this example. Otherwise, the backend needs to be updated. +Removal of calendar events is not allowed in this example. Otherwise, the backend needs to be updated. .. code-block:: php @@ -424,7 +424,7 @@ Removal of calendars The calendar should not be removed by means of the CalDAV interface. Thus, nothing is done here. .. code-block:: php - + childExists($name)) { return new CalendarObject($this, $name); @@ -510,14 +510,14 @@ Finally, there is the method ``getChildren`` to fetch all events of a calendar. .. code-block:: php getChild($childName); }); - + return $children; } @@ -532,7 +532,7 @@ Its sole method will return a list of entries. In contrast to the ``getChildren( .. code-block:: php principalUri; } @@ -565,7 +565,7 @@ Return all groups uris of the user, there is the ``getGroups`` method. Here, no .. code-block:: php mailManager->has()) { return; } - + // retrieve types of providers available (array of id's and labels) $types = $this->mailManager->types(); @@ -62,12 +62,12 @@ To use mail as a service provided by another app, your app needs to instantiate } public function acquireMailService(): void { - + // determine if any providers are available if (!$this->mailManager->has()) { return; } - + // retrieve services available for a user (array of service objects) $services = $this->mailManager->services('user1'); @@ -77,12 +77,12 @@ To use mail as a service provided by another app, your app needs to instantiate } public function sendMessage(): void { - + // determine if any providers are available if (!$this->mailManager->has()) { return; } - + // retrieve a single service with a specific mail address (service objects) $service = $this->mailManager->findServiceByAddress('user@testing.com'); @@ -160,10 +160,10 @@ Step 2: Create a Mail Service Class The mail service class is the main class that other apps use to access mail functionality in your app. This class is also returned by the mail provider class. -This class needs to implement the `IService` interface and have all the required methods defined. Because functionality varies between protocols this class also needs to be extended with the appropriate supported function interfaces like 'IMessageSend' which provides mail sending capabilities. +This class needs to implement the `IService` interface and have all the required methods defined. Because functionality varies between protocols this class also needs to be extended with the appropriate supported function interfaces like 'IMessageSend' which provides mail sending capabilities. .. code-block:: php - + namespace OCA\BigHostingApp\Provider; use OCP\Mail\Provider\Address; @@ -217,13 +217,13 @@ Step 3: Register the Mail Provider The registration is performed at the initial stages of your app being loaded by the Nextcloud system, inside the 'AppInfo/Application.php' file .. code-block:: php - + namespace OCA\BigHostingApp\AppInfo; use OCA\BigHostingApp\Provider\MailProvider; use OCP\AppFramework\App; use OCP\AppFramework\Bootstrap\IRegistrationContext; - + class Application extends App { public const APP_ID = 'BigHostingApp'; @@ -239,4 +239,4 @@ The registration is performed at the initial stages of your app being loaded by } - } \ No newline at end of file + } diff --git a/developer_manual/digging_deeper/out_of_office.rst b/developer_manual/digging_deeper/out_of_office.rst index caf6b9b04f1..1cfba3e0f72 100644 --- a/developer_manual/digging_deeper/out_of_office.rst +++ b/developer_manual/digging_deeper/out_of_office.rst @@ -18,31 +18,31 @@ interface. It provides the following methods: .. code-block:: php - /** - * Check if the feature is enabled on this instance - */ - public function isEnabled(): bool; + /** + * Check if the feature is enabled on this instance + */ + public function isEnabled(): bool; .. code-block:: php - /** - * Get the user's ongoing out-of-office data, if any - */ - public function getCurrentOutOfOfficeData(IUser $user): ?IOutOfOfficeData; + /** + * Get the user's ongoing out-of-office data, if any + */ + public function getCurrentOutOfOfficeData(IUser $user): ?IOutOfOfficeData; .. code-block:: php - /** - * Reset the absence cache to null - */ - public function clearCache(string $userId): void; + /** + * Reset the absence cache to null + */ + public function clearCache(string $userId): void; .. code-block:: php - /** - * Is the absence in effect at this moment - */ - public function isInEffect(IOutOfOfficeData $data): bool; + /** + * Is the absence in effect at this moment + */ + public function isInEffect(IOutOfOfficeData $data): bool; Listening to events ------------------- @@ -51,7 +51,7 @@ All events have one common method to retrieve data about the affected out-of-of .. code-block:: php - public function getData(): IOutOfOfficeData; + public function getData(): IOutOfOfficeData; The following events are emitted by the out-of-office feature: diff --git a/developer_manual/digging_deeper/projects.rst b/developer_manual/digging_deeper/projects.rst index 27f3520454c..f3441e09169 100644 --- a/developer_manual/digging_deeper/projects.rst +++ b/developer_manual/digging_deeper/projects.rst @@ -147,32 +147,32 @@ as plain JavaScript: import Vue from 'vue' import ItemPickerDialog from './components/ItemPickerDialog' - OCP.Collaboration.registerType('myapp', { - action: () => { - return new Promise((resolve, reject) => { - const container = document.createElement('div') - container.id = 'myapp-item-select' - const body = document.getElementById('body-user') - body.appendChild(container) - const ComponentVM = new Vue({ - render: h => h(ItemPickerDialog), - }) - ComponentVM.$mount(container) - ComponentVM.$root.$on('close', () => { - ComponentVM.$el.remove() - ComponentVM.$destroy() - reject(new Error('User cancelled resource selection')) - }) - ComponentVM.$root.$on('select', (id) => { - resolve(id) - ComponentVM.$el.remove() - ComponentVM.$destroy() - }) - }) - }, - typeString: t('myapp', 'Link to an item'), - typeIconClass: 'icon-file', - }) + OCP.Collaboration.registerType('myapp', { + action: () => { + return new Promise((resolve, reject) => { + const container = document.createElement('div') + container.id = 'myapp-item-select' + const body = document.getElementById('body-user') + body.appendChild(container) + const ComponentVM = new Vue({ + render: h => h(ItemPickerDialog), + }) + ComponentVM.$mount(container) + ComponentVM.$root.$on('close', () => { + ComponentVM.$el.remove() + ComponentVM.$destroy() + reject(new Error('User cancelled resource selection')) + }) + ComponentVM.$root.$on('select', (id) => { + resolve(id) + ComponentVM.$el.remove() + ComponentVM.$destroy() + }) + }) + }, + typeString: t('myapp', 'Link to an item'), + typeIconClass: 'icon-file', + }) This will allow other apps to link to your items. We also want to link to other apps' items. Since all apps with projects support are listening on the above LoadAdditionalScriptsEvent, @@ -181,21 +181,21 @@ we can simply dispatch it when we render our main page template. .. code-block:: php - eventDispatcher = $eventDispatcher; - } + public function __construct(string $appName, IRequest $request, IEventDispatcher $eventDispatcher) { + parent::__construct($appName, $request); + $this->eventDispatcher = $eventDispatcher; + } - public function index() { - $this->eventDispatcher->dispatchTyped(new \OCP\Collaboration\Resources\LoadAdditionalScriptsEvent()); - return new TemplateResponse('my_app', 'main'); - } - } + public function index() { + $this->eventDispatcher->dispatchTyped(new \OCP\Collaboration\Resources\LoadAdditionalScriptsEvent()); + return new TemplateResponse('my_app', 'main'); + } + } In our Vue app, we can then render the pre-built projects picker available in the npm package ``nextcloud-vue-collections``. diff --git a/developer_manual/digging_deeper/publicpage.rst b/developer_manual/digging_deeper/publicpage.rst index 9974301e3c5..d3698a2500a 100644 --- a/developer_manual/digging_deeper/publicpage.rst +++ b/developer_manual/digging_deeper/publicpage.rst @@ -26,13 +26,13 @@ your ``routes.php`` could look like: .. code-block:: php - [ - [ 'name' => 'PublicAPI#get', 'url' => '/api/{token}', 'verb' => 'GET' ], - [ 'name' => 'PublicDisplay#get', 'url' => '/display/{token}', 'verb' => 'GET' ], - ] - ]; + [ + [ 'name' => 'PublicAPI#get', 'url' => '/api/{token}', 'verb' => 'GET' ], + [ 'name' => 'PublicDisplay#get', 'url' => '/display/{token}', 'verb' => 'GET' ], + ] + ]; Implementing an API called from a public share page --------------------------------------------------- @@ -42,46 +42,46 @@ As said the PublicShareController is a very basic controller. You need to implem .. code-block:: php - getToken() === 'secretToken'; - } - - /** - * Allows you to specify if this share is password protected - */ - protected function isPasswordProtected(): bool { - return true; - } - - /** - * Your normal controller function. The following annotation will allow guests - * to open the page as well - */ - #[PublicPage] - public function get() { - // Work your magic - } - } + getToken() === 'secretToken'; + } + + /** + * Allows you to specify if this share is password protected + */ + protected function isPasswordProtected(): bool { + return true; + } + + /** + * Your normal controller function. The following annotation will allow guests + * to open the page as well + */ + #[PublicPage] + public function get() { + // Work your magic + } + } You can also chose to overwrite the ``shareNotFound`` function. That is called when the @@ -100,57 +100,57 @@ you also implement the ``verifyPassword`` and ``showShare`` functions. .. code-block: php - getToken() === 'secretToken'; - } - - /** - * Allows you to specify if this share is password protected - */ - protected function isPasswordProtected(): bool { - return true; - } - - /** - * Verify the entered password by the user - */ - protected function verifyPassword(string $password): bool { - return $password === 'secretpassword'; - } - - public function showShare(): TemplateResponse { - return new TemplateResponse('yourapp', 'yourtemplate'); - } - - /** - * Your normal controller function. The following annotation will allow guests - * to open the page as well - */ - #[PublicPage] - public function get() { - // Work your magic - } - } + getToken() === 'secretToken'; + } + + /** + * Allows you to specify if this share is password protected + */ + protected function isPasswordProtected(): bool { + return true; + } + + /** + * Verify the entered password by the user + */ + protected function verifyPassword(string $password): bool { + return $password === 'secretpassword'; + } + + public function showShare(): TemplateResponse { + return new TemplateResponse('yourapp', 'yourtemplate'); + } + + /** + * Your normal controller function. The following annotation will allow guests + * to open the page as well + */ + #[PublicPage] + public function get() { + // Work your magic + } + } Additionally you can overwrite the ``showAuthenticate`` and ``showAuthFailed`` functions diff --git a/developer_manual/digging_deeper/reference.rst b/developer_manual/digging_deeper/reference.rst index ae9f1c8e9b3..66424602757 100644 --- a/developer_manual/digging_deeper/reference.rst +++ b/developer_manual/digging_deeper/reference.rst @@ -75,9 +75,9 @@ This component will take care of resolving the links itself. .. code-block:: html + :arguments="richParameters" + :autolink="true" + :reference-limit="0" /> NcRichText can be imported like this: @@ -349,38 +349,38 @@ and an example response: { "ocs": { - "meta": { - "status": "ok", - "statuscode": 200, - "message": "OK" - }, - "data": [ - { - "id": "github-issue-pr", - "title": "GitHub issues, pull requests and comments", - "icon_url": "https://my.nextcloud.org/apps/integration_github/img/app-dark.svg", - "order": 10, - "search_providers_ids": [ - "github-search-issues", - "github-search-repos" - ] - }, - { - "id": "openstreetmap-point", - "title": "Map location (by OpenStreetMap)", - "icon_url": "https://my.nextcloud.org/apps/integration_openstreetmap/img/app-dark.svg", - "order": 10, - "search_providers_ids": [ - "openstreetmap-search-location" - ] - }, - { - "id": "files", - "title": "Files", - "icon_url": "https://my.nextcloud.org/apps/files/img/folder.svg", - "order": 0 - } - ] + "meta": { + "status": "ok", + "statuscode": 200, + "message": "OK" + }, + "data": [ + { + "id": "github-issue-pr", + "title": "GitHub issues, pull requests and comments", + "icon_url": "https://my.nextcloud.org/apps/integration_github/img/app-dark.svg", + "order": 10, + "search_providers_ids": [ + "github-search-issues", + "github-search-repos" + ] + }, + { + "id": "openstreetmap-point", + "title": "Map location (by OpenStreetMap)", + "icon_url": "https://my.nextcloud.org/apps/integration_openstreetmap/img/app-dark.svg", + "order": 10, + "search_providers_ids": [ + "openstreetmap-search-location" + ] + }, + { + "id": "files", + "title": "Files", + "icon_url": "https://my.nextcloud.org/apps/files/img/folder.svg", + "order": 0 + } + ] } } diff --git a/developer_manual/digging_deeper/repair.rst b/developer_manual/digging_deeper/repair.rst index 0fe4ce98df7..3484c5fb3da 100644 --- a/developer_manual/digging_deeper/repair.rst +++ b/developer_manual/digging_deeper/repair.rst @@ -28,26 +28,26 @@ The following repairstep will log a message when executed. class MyRepairStep implements IRepairStep { - /** @var LoggerInterface */ - protected $logger; - - public function __construct(LoggerInterface $logger) { - $this->logger = $logger; - } - - /** - * Returns the step's name - */ - public function getName() { - return 'A demonstration repair step!'; - } - - /** - * @param IOutput $output - */ - public function run(IOutput $output) { - $this->logger->warning("Hello world from MyRepairStep!", ["app" => "MyApp"]); - } + /** @var LoggerInterface */ + protected $logger; + + public function __construct(LoggerInterface $logger) { + $this->logger = $logger; + } + + /** + * Returns the step's name + */ + public function getName() { + return 'A demonstration repair step!'; + } + + /** + * @param IOutput $output + */ + public function run(IOutput $output) { + $this->logger->warning("Hello world from MyRepairStep!", ["app" => "MyApp"]); + } } Outputting information @@ -70,13 +70,13 @@ The following function will sleep for 10 seconds and show the progress: * @param IOutput $output */ public function run(IOutput $output) { - $output->info("This step will take 10 seconds."); - $output->startProgress(10); - for ($i = 0; $i < 10; $i++) { - sleep(1); - $output->advance(1); - } - $output->finishProgress(); + $output->info("This step will take 10 seconds."); + $output->startProgress(10); + for ($i = 0; $i < 10; $i++) { + sleep(1); + $output->advance(1); + } + $output->finishProgress(); } Register a repair-step @@ -90,16 +90,16 @@ of the app: - myapp - My App - A test app - ... - - - OCA\MyApp\Migration\MyRepairStep - - + xsi:noNamespaceSchemaLocation="https://apps.nextcloud.com/schema/apps/info.xsd"> + myapp + My App + A test app + ... + + + OCA\MyApp\Migration\MyRepairStep + + diff --git a/developer_manual/digging_deeper/search.rst b/developer_manual/digging_deeper/search.rst index a5d3f30b1a9..05b24bbb5ba 100644 --- a/developer_manual/digging_deeper/search.rst +++ b/developer_manual/digging_deeper/search.rst @@ -165,7 +165,7 @@ The class would typically be saved into a file in ``lib/Search`` of your app but Advanced search provider ------------------------- +------------------------ Since Nextcloud 28.0, it is possible to use advanced search providers by implementing ``\OCP\Search\IFilteringProvider``. This interface allows to supports other filtering types. @@ -187,7 +187,7 @@ This interface allows to supports other filtering types. // TODO Implement functions from simple search provider - public function getSupportedFilters(): array { + public function getSupportedFilters(): array { return [ 'term', 'since', @@ -199,11 +199,11 @@ This interface allows to supports other filtering types. ]; } - public function getAlternateIds(): array { + public function getAlternateIds(): array { return []; } - public function getCustomFilters(): array { + public function getCustomFilters(): array { return [ new FilterDefinition('custom_int', FilterDefinition::TYPE_INT), new FilterDefinition('custom_user', FilterDefinition::TYPE_USER), @@ -215,11 +215,11 @@ This interface allows to supports other filtering types. // Retrieve filters /** @var $since ?DateTimeImmutable */ $since = $query->getFilter('since')?->get(); - /** @var $user ?IUser */ + /** @var $user ?IUser */ $user = $query->getFilter('custom_user')?->get(); - // TODO Do actual search - + // TODO Do actual search + return new SearchResult(/* … */); } } @@ -517,7 +517,7 @@ The unified search is available via OCS, which means client application like the .. note:: This method was added in Nextcloud 21. If your app also targets Nextcloud 20 you should either not use it or add a version check to invoke the method only conditionally. -Declare in-app search +Declare in-app search --------------------- If your application also have in-app search (like ``mail`` or ``talk``), your provider can also implements interface ``\OCP\Search\IInAppSearch``. diff --git a/developer_manual/digging_deeper/settings.rst b/developer_manual/digging_deeper/settings.rst index 319f606fa2f..200fc50f06d 100644 --- a/developer_manual/digging_deeper/settings.rst +++ b/developer_manual/digging_deeper/settings.rst @@ -111,7 +111,7 @@ on the survey_client solution. /** * The section ID, e.g. 'sharing' * - * @return string + * @return string */ public function getSection() { return 'survey_client'; @@ -263,8 +263,8 @@ An example implementation of the IIconSection interface: * Whether the form should be rather on the top or bottom of * the settings navigation. The sections are arranged in ascending order of * the priority values. It is required to return a value between 0 and 99. - * - * @return int + * + * @return int */ public function getPriority() { return 80; @@ -272,8 +272,8 @@ An example implementation of the IIconSection interface: /** * The relative path to an icon describing the section - * - * @return string + * + * @return string */ public function getIcon() { return $this->urlGenerator->imagePath('yourapp', 'icon.svg'); diff --git a/developer_manual/digging_deeper/snowflake_ids.rst b/developer_manual/digging_deeper/snowflake_ids.rst index d6d55a980bb..b8a8dd719b4 100644 --- a/developer_manual/digging_deeper/snowflake_ids.rst +++ b/developer_manual/digging_deeper/snowflake_ids.rst @@ -30,8 +30,8 @@ In Nextcloud migrations it looks like: if (!$schema->hasTable('my_table')) { $table = $schema->createTable('my_table'); $table->addColumn( - 'id', - Types::BIGINT, + 'id', + Types::BIGINT, ['notnull' => true, 'unsigned' => true] ); $table->setPrimaryKey(['id']); @@ -43,7 +43,7 @@ In Nextcloud migrations it looks like: Generate a Snowflake ID ----------------------- -To generate a new ID, call ``nextId`` function on the generator: +To generate a new ID, call ``nextId`` function on the generator: .. code-block:: php @@ -56,7 +56,7 @@ To generate a new ID, call ``nextId`` function on the generator: class MyObjectFactory { public function __construct( - private readonly IGenerator $generator, + private readonly IGenerator $generator, ) { // TODO Add your implementation } @@ -89,10 +89,10 @@ It’s also possible to decode IDs in your code, for example to get creation tim use OCP\Snowflake\IDecoder; class MyObject { - private string $id; + private string $id; public function __construct( - private readonly IDecoder $decoder, + private readonly IDecoder $decoder, ) { // TODO Add your implementation } diff --git a/developer_manual/digging_deeper/task_processing.rst b/developer_manual/digging_deeper/task_processing.rst index 1f77f9ffa47..7d0f711f9f8 100644 --- a/developer_manual/digging_deeper/task_processing.rst +++ b/developer_manual/digging_deeper/task_processing.rst @@ -193,19 +193,19 @@ Input and output shape keys can have one of a pre-defined set of types, which ar .. code-block:: php enum EShapeType: int { - case Number = 0; - case Text = 1; - case Image = 2; - case Audio = 3; - case Video = 4; - case File = 5; - case Enum = 6; - case ListOfNumbers = 10; - case ListOfTexts = 11; - case ListOfImages = 12; - case ListOfAudio = 13; - case ListOfVideo = 14; - case ListOfFiles = 15; + case Number = 0; + case Text = 1; + case Image = 2; + case Audio = 3; + case Video = 4; + case File = 5; + case Enum = 6; + case ListOfNumbers = 10; + case ListOfTexts = 11; + case ListOfImages = 12; + case ListOfAudio = 13; + case ListOfVideo = 14; + case ListOfFiles = 15; } When consuming the task processing API, ``Image``, ``Audio``, ``Video`` and ``File`` slots are filled with Nextcloud file IDs, so instead of supplying the image data directly as a string to the task you create a file for it and pass the id. Similarly, if the task outputs an image, you will receive a file ID in that slot. @@ -516,31 +516,31 @@ If you would like to implement providers that handle additional task types, you use OCP\IL10N; class AudioToImage implements ITaskType { - public const ID = 'myapp:audiotoimage'; - - public function getId(): string { - return self::ID; - } - - public function getName(): string { - return 'Get Spectrogram'; - } - - public function getDescription(): string { - return 'Turns audio into an image'; - } - - public function getInputShape(): array { - return [ - 'audio' => new ShapeDescriptor('Audio', 'The audio', EShapeType::Audio), - ]; - } - - public function getOutputShape(): array { - return [ - 'spectrogram' => new ShapeDescriptor('Spectrogram', 'The audio spectrogram', EShapeType::Image), - ]; - } + public const ID = 'myapp:audiotoimage'; + + public function getId(): string { + return self::ID; + } + + public function getName(): string { + return 'Get Spectrogram'; + } + + public function getDescription(): string { + return 'Turns audio into an image'; + } + + public function getInputShape(): array { + return [ + 'audio' => new ShapeDescriptor('Audio', 'The audio', EShapeType::Audio), + ]; + } + + public function getOutputShape(): array { + return [ + 'spectrogram' => new ShapeDescriptor('Spectrogram', 'The audio spectrogram', EShapeType::Image), + ]; + } } Internal task types diff --git a/developer_manual/digging_deeper/time.rst b/developer_manual/digging_deeper/time.rst index 8f4e53896d5..294d8e9df16 100644 --- a/developer_manual/digging_deeper/time.rst +++ b/developer_manual/digging_deeper/time.rst @@ -13,31 +13,31 @@ The factory extends the ``\PSR\Clock\ClockInterface`` with the following methods - OCA\TwoFactor_Test\Provider\TwoFactorTestProvider - + + OCA\TwoFactor_Test\Provider\TwoFactorTestProvider + Providing an icon (optional) ---------------------------- diff --git a/developer_manual/digging_deeper/web_host_metadata.rst b/developer_manual/digging_deeper/web_host_metadata.rst index 482025ddc2b..32ff1fe07fe 100644 --- a/developer_manual/digging_deeper/web_host_metadata.rst +++ b/developer_manual/digging_deeper/web_host_metadata.rst @@ -146,4 +146,4 @@ The handler class is registered via the :ref:`bootstrap mechanism .. _`RFC6415`: https://tools.ietf.org/html/rfc6415 -.. _`RFC7033`: https://tools.ietf.org/html/rfc7033 \ No newline at end of file +.. _`RFC7033`: https://tools.ietf.org/html/rfc7033 diff --git a/developer_manual/exapp_development/DevSetup.rst b/developer_manual/exapp_development/DevSetup.rst index 7e5411bc17f..0d2462b8fa2 100644 --- a/developer_manual/exapp_development/DevSetup.rst +++ b/developer_manual/exapp_development/DevSetup.rst @@ -20,29 +20,29 @@ in which case uninstall the release version of AppAPI and perform the following Clone the latest main branch: - .. code-block:: bash + .. code-block:: bash - git clone https://github.com/nextcloud/app_api.git && cd app_api + git clone https://github.com/nextcloud/app_api.git && cd app_api or clone a specific version by specifying the version tag: - .. code-block:: bash + .. code-block:: bash - git clone https://github.com/nextcloud/app_api.git --branch && cd app_api + git clone https://github.com/nextcloud/app_api.git --branch && cd app_api where ```` is the version you want to install. Then, build frontend assets in development mode: - .. code-block:: bash + .. code-block:: bash - npm ci && npm run dev + npm ci && npm run dev Enable AppAPI from the directory where the ``occ`` command resides: - .. code-block:: bash + .. code-block:: bash - ./occ app:enable --force app_api + ./occ app:enable --force app_api Deploy daemons types ******************** @@ -89,8 +89,8 @@ and actually forwarded to the container: .. code-block:: - ... - volumes: - ... - - /var/run/docker.sock:/var/run/docker.sock - ... + ... + volumes: + ... + - /var/run/docker.sock:/var/run/docker.sock + ... diff --git a/developer_manual/exapp_development/Introduction.rst b/developer_manual/exapp_development/Introduction.rst index e6b7d770b4c..e3a81c2b2ae 100644 --- a/developer_manual/exapp_development/Introduction.rst +++ b/developer_manual/exapp_development/Introduction.rst @@ -9,11 +9,11 @@ Overview The main tasks of the AppAPI ecosystem are: - * Providing a reliable and fast method for authenticating applications - * Supporting various application deployment options - * Offering a clear and straightforward application administration interface - * Ensuring a reliable implementation of all the necessary missing APIs for applications - * Supplying clear, understandable documentation and support on how to implement libraries in other programming languages for writing next-gen applications for Nextcloud + * Providing a reliable and fast method for authenticating applications + * Supporting various application deployment options + * Offering a clear and straightforward application administration interface + * Ensuring a reliable implementation of all the necessary missing APIs for applications + * Supplying clear, understandable documentation and support on how to implement libraries in other programming languages for writing next-gen applications for Nextcloud The system should support the expansion and integration of new deployment methods, avoiding any tight coupling with a specific deployment type. Applications should be capable of indicating the deployment methods they can accommodate. diff --git a/developer_manual/exapp_development/development_overview/ExAppDevelopmentSteps.rst b/developer_manual/exapp_development/development_overview/ExAppDevelopmentSteps.rst index 8219f55c922..1cbc18e26ba 100644 --- a/developer_manual/exapp_development/development_overview/ExAppDevelopmentSteps.rst +++ b/developer_manual/exapp_development/development_overview/ExAppDevelopmentSteps.rst @@ -29,11 +29,11 @@ Next is to setup the ExApp skeleton. There are several ExApp examples available so you can have a look at them and start from. The ExApp template and examples: - - ``[Python]`` `App Skeleton `_ - - ``[Python]`` `UI Example Skeleton `_ - - ``[Python]`` `More complex ExApp UI example with 3rd-party service `_ - - ``[GoLang]`` `Go Lang ExApp example `_ - - etc. + - ``[Python]`` `App Skeleton `_ + - ``[Python]`` `UI Example Skeleton `_ + - ``[Python]`` `More complex ExApp UI example with 3rd-party service `_ + - ``[GoLang]`` `Go Lang ExApp example `_ + - etc. They contain the basic structure of the ExApp, including: @@ -52,9 +52,9 @@ More details are available in the :ref:`ExAppOverview` section. The basic development process consists of the following steps: - Implement the ExApp <-> Nextcloud :ref:`lifecycle methods `: - #. ``/heartbeat``: ExApp heartbeat method - #. ``/init``: ExApp initialization method - #. ``/enabled``: ExApp enable/disable method + #. ``/heartbeat``: ExApp heartbeat method + #. ``/init``: ExApp initialization method + #. ``/enabled``: ExApp enable/disable method - Implement the ExApp backend API and logic - Implement the ExApp frontend (Nextcloud Vue.js app) [optional] @@ -79,9 +79,9 @@ Currently, there are 3 main compute devices to target with custom Docker images: .. note:: - If the Deploy daemon configured with the GPU compute device, - AppAPI will try to pull the Docker image with the GPU support first (``:-``, `ref PR `_). - If the image is not found, AppAPI will try to pull the base (CPU) image (``:``). + If the Deploy daemon configured with the GPU compute device, + AppAPI will try to pull the Docker image with the GPU support first (``:-``, `ref PR `_). + If the image is not found, AppAPI will try to pull the base (CPU) image (``:``). Dockerfile diff --git a/developer_manual/exapp_development/development_overview/ExAppHarpIntegration.rst b/developer_manual/exapp_development/development_overview/ExAppHarpIntegration.rst index 5c3d2689ca8..f793c0d3b3d 100644 --- a/developer_manual/exapp_development/development_overview/ExAppHarpIntegration.rst +++ b/developer_manual/exapp_development/development_overview/ExAppHarpIntegration.rst @@ -13,11 +13,11 @@ Adapting ExApps to HaRP Summary ------- -HaRP is a reverse proxy system designed to simplify the deployment workflow +HaRP is a reverse proxy system designed to simplify the deployment workflow for Nextcloud 32’s AppAPI. -It enables direct communication between clients and ExApps, bypassing -the Nextcloud instance to improve performance and reduce the complexity +It enables direct communication between clients and ExApps, bypassing +the Nextcloud instance to improve performance and reduce the complexity traditionally associated with `DockerSocketProxy` setups. HaRP provides an `FRP-based `_ @@ -28,11 +28,11 @@ The script installs or starts the FRP client and executes your app process. .. warning:: - We strongly recommend starting support for HaRP in ExApps from the start - of Nextcloud 32, as the old `DSP `_ + We strongly recommend starting support for HaRP in ExApps from the start + of Nextcloud 32, as the old `DSP `_ way will be deprecated and marked for removal in Nextcloud 35. - - Adding HaRP support is fully compatible with the existing DSP system, + + Adding HaRP support is fully compatible with the existing DSP system, so you won’t need to maintain two separate release types of your ExApp. Key integration considerations @@ -57,7 +57,7 @@ Steps needed to adapt an ExApp -------------------------------------- 1. Copy the `start.sh `_ -script from the exapps_dev folder of the HaRP repository into your Docker image +script from the exapps_dev folder of the HaRP repository into your Docker image (e.g., using a `COPY` instruction). 2. In your ExApp's Dockerfile, set the `ENTRYPOINT` to execute `start.sh` followed by @@ -68,11 +68,11 @@ run the command you provide as arguments. 3. Ensure the `curl` command-line utility is installed in your ExApp's Docker image, as it's needed by the following script to download the FRP client. -4. Add the following lines to your Dockerfile to automatically include the FRP +4. Add the following lines to your Dockerfile to automatically include the FRP client binaries in your Docker image: .. code-block:: dockerfile - + # Download and install FRP client RUN set -ex; \ ARCH=$(uname -m); \ @@ -90,7 +90,7 @@ client binaries in your Docker image: rm -rf /tmp/frp /tmp/frp.tar.gz .. note:: - + For Alpine 3.21 Linux you can just install FRP from repo using apk add frp command. Running your ExApp with a non-root user @@ -105,7 +105,7 @@ Running your ExApp with a non-root user To run the main process as a non-root user while remaining compatible with HaRP and AppAPI, ensure the following: -1. Keep image default user as `root`, drop to less privileged service user at runtime. +1. Keep image default user as `root`, drop to less privileged service user at runtime. - Make it easy for AppAPI to perform privileged operations (copying files, setting permissions, running `update-ca-certificates`) by leaving the @@ -163,15 +163,15 @@ ensure the following: - **Create `/frpc.toml`** or the directory that will contain it at image build time and set ownership to the service user so at runtime `start.sh` can write to it without requiring root. - - **Create directory `/certs/frp`** and make it readable by the service user. + - **Create directory `/certs/frp`** and make it readable by the service user. AppAPI will copy cert files into that folder by using a `docker cp ...` command - with the default container user (which is still `root`). By setting the directory + with the default container user (which is still `root`). By setting the directory owner to the service user, we will ensure the service user can read the certs at runtime. Use some similar commands in your Dockerfile: .. code-block:: dockerfile - + RUN touch /frpc.toml && \ mkdir -p /certs/frp && \ chown $USER:$USER /frpc.toml && \ @@ -190,7 +190,7 @@ ensure the following: ENV HOME=/home/$USER ENV GOSU_VERSION=1.19 - # Install dependencies and create service user. You might want to + # Install dependencies and create service user. You might want to # add additional packages depending on your app requirements. # Make sure curl and FRP are installed. RUN apk update && \ diff --git a/developer_manual/exapp_development/development_overview/ExAppLifecycle.rst b/developer_manual/exapp_development/development_overview/ExAppLifecycle.rst index 1129b8e1598..b7df38ca51e 100644 --- a/developer_manual/exapp_development/development_overview/ExAppLifecycle.rst +++ b/developer_manual/exapp_development/development_overview/ExAppLifecycle.rst @@ -17,10 +17,10 @@ ExApp lifecycle methods When the ExApp is being installed in Nextcloud, there are several lifecycle steps happening. The ExApp lifecycle requires the following API endpoint handlers (in order): - 0. ``healthcheck``: Docker container healthcheck - 1. ``/heartbeat``: **[required]** ExApp heartbeat handler - 2. ``/init``: **[optional]** ExApp initialization handler - 3. ``/enabled``: **[required]** ExApp enable/disable handler + 0. ``healthcheck``: Docker container healthcheck + 1. ``/heartbeat``: **[required]** ExApp heartbeat handler + 2. ``/init``: **[optional]** ExApp initialization handler + 3. ``/enabled``: **[required]** ExApp enable/disable handler Healthcheck @@ -31,7 +31,7 @@ You can define any custom container startup logic here if needed. .. note:: - The AppAPI healthcheck timeout is 15 minutes. + The AppAPI healthcheck timeout is 15 minutes. Heartbeat @@ -47,8 +47,8 @@ This step fails if the ExApp does not respond within 10 minutes. .. note:: - This endpoint should be available **without AppAPIAuth authentication**. - There is a 10 minute timeout for the ExApp to startup and respond to the ``/heartbeat`` request. + This endpoint should be available **without AppAPIAuth authentication**. + There is a 10 minute timeout for the ExApp to startup and respond to the ``/heartbeat`` request. .. _ex_app_lifecycle_init: @@ -62,8 +62,8 @@ This is a trigger for the ExApp to start its initialization process, e.g. downlo .. note:: - The default init timeout (``init_timeout``) is 40 minutes. It can be changed in the AppAPI admin settings - or via the command ``occ config:app:set app_api init_timeout --value 40 --type mixed``. + The default init timeout (``init_timeout``) is 40 minutes. It can be changed in the AppAPI admin settings + or via the command ``occ config:app:set app_api init_timeout --value 40 --type mixed``. URL: ``POST http://localhost:2345/init`` @@ -71,8 +71,8 @@ AppAPI expects a response with HTTP status 200. .. note:: - Even if the ExApp does not not implement ``/init`` endpoint and AppAPI receives a ``HTTP 501 NOT IMPLEMENTED`` or ``HTTP 404 NOT FOUND`` response, - AppAPI can still enable the ExApp. + Even if the ExApp does not not implement ``/init`` endpoint and AppAPI receives a ``HTTP 501 NOT IMPLEMENTED`` or ``HTTP 404 NOT FOUND`` response, + AppAPI can still enable the ExApp. The ExApp should update the init progress via the ``PUT /ocs/v2.php/apps/app_api/ex-app/status`` API request containing a ``{ "progress": }`` payload. @@ -92,7 +92,7 @@ AppAPI expects a response with HTTP status 200. Any other status code will be co .. note:: - The AppAPI timeout for the ``enabled`` handler is 30 seconds. + The AppAPI timeout for the ``enabled`` handler is 30 seconds. ExApp lifecycle scheme @@ -103,25 +103,25 @@ Let's review a simple ExApp lifecycle scheme: .. mermaid:: - sequenceDiagram - participant Nextcloud - participant ExApp - loop Heartbeat - Nextcloud->>ExApp: HTTP GET /heartbeat - ExApp-->>Nextcloud: /heartbeat HTTP 200 - end - Nextcloud->>ExApp: HTTP POST /init - ExApp->>Nextcloud: /init HTTP OK 200 - loop Init - ExApp->>ExApp: Download models, starter data, etc. - ExApp-->>Nextcloud: PUT /ocs/v2.php/apps/app_api/ex-app/status { "progress": 50 } - end - Nextcloud->>ExApp: HTTP PUT /enabled?enabled=1 - ExApp-->>Nextcloud: Register all needed APIs via OCS API - ExApp->>Nextcloud: /enabled HTTP 200 - Nextcloud->>ExApp: HTTP PUT /enabled?enabled=0 - ExApp-->>Nextcloud: Unregister all APIs via OCS API - ExApp->>Nextcloud: /enabled HTTP 200 + sequenceDiagram + participant Nextcloud + participant ExApp + loop Heartbeat + Nextcloud->>ExApp: HTTP GET /heartbeat + ExApp-->>Nextcloud: /heartbeat HTTP 200 + end + Nextcloud->>ExApp: HTTP POST /init + ExApp->>Nextcloud: /init HTTP OK 200 + loop Init + ExApp->>ExApp: Download models, starter data, etc. + ExApp-->>Nextcloud: PUT /ocs/v2.php/apps/app_api/ex-app/status { "progress": 50 } + end + Nextcloud->>ExApp: HTTP PUT /enabled?enabled=1 + ExApp-->>Nextcloud: Register all needed APIs via OCS API + ExApp->>Nextcloud: /enabled HTTP 200 + Nextcloud->>ExApp: HTTP PUT /enabled?enabled=0 + ExApp-->>Nextcloud: Unregister all APIs via OCS API + ExApp->>Nextcloud: /enabled HTTP 200 Nextcloud-side ExApp lifecycle methods @@ -132,8 +132,8 @@ You can find available AppAPI Nextcloud OCS APIs :ref:`here `, :ref:`filesactionmenu `), :ref:`occ commands `, etc. + The ExApp should register all needed APIs during the ``enabled`` method call, + such as the UI (:ref:`top-menu `, :ref:`filesactionmenu `), :ref:`occ commands `, etc. AppAPI Authentication @@ -144,8 +144,8 @@ The ExApp should validate the authentication using the same algorithm as AppAPI .. note:: - Is it up to the developer to apply rate limits, bruteforce protection, and other security measures - to the ExApp API endpoints. + Is it up to the developer to apply rate limits, bruteforce protection, and other security measures + to the ExApp API endpoints. Cookies diff --git a/developer_manual/exapp_development/development_overview/ExAppOverview.rst b/developer_manual/exapp_development/development_overview/ExAppOverview.rst index 2306b1b2cab..2d6404f1819 100644 --- a/developer_manual/exapp_development/development_overview/ExAppOverview.rst +++ b/developer_manual/exapp_development/development_overview/ExAppOverview.rst @@ -15,10 +15,10 @@ The typical ExApp folder structure is the following: - **appinfo/**: contains the ExApp metadata, which is based on the regular :doc:`Nextcloud PHP appinfo <../../app_development/info>`, but with additional new fields under the ``external-app`` key. - **ex_app/**: the ExApp specific folder, which contains the ExApp frontend and backend parts. - - **lib/**: contains the ExApp backend part, which can be written in any language. - - **src/**: contains the ExApp frontend part, which is a regular Nextcloud Vue.js application, with small adjustments to the script loading paths (see :ref:`ExApp specific frontend changes `). - - **img/**: contains the ExApp images. - - **css/**: contains the ExApp CSS files. + - **lib/**: contains the ExApp backend part, which can be written in any language. + - **src/**: contains the ExApp frontend part, which is a regular Nextcloud Vue.js application, with small adjustments to the script loading paths (see :ref:`ExApp specific frontend changes `). + - **img/**: contains the ExApp images. + - **css/**: contains the ExApp CSS files. - **l10n**: contains the :ref:`ExApp translations `. - **translationfiles**: contains the source translation (``.po``, ``.mo``) files for the ExApp. - **other folders or files**: depends on your case, e.g. screenshots, scripts, etc. @@ -34,18 +34,18 @@ It should contain the following fields: .. code-block:: - - - ghcr.io - nextcloud/skeleton - latest - - + + + ghcr.io + nextcloud/skeleton + latest + + - **docker-install**: contains the Docker image information for the ExApp. - - **registry**: the Docker registry where the image is stored. - - **image**: the Docker image name. - - **image-tag**: the Docker image tag (version tag). + - **registry**: the Docker registry where the image is stored. + - **image**: the Docker image name. + - **image-tag**: the Docker image tag (version tag). Backend @@ -56,7 +56,7 @@ The only requirement here is to follow the microservice architecture and ExApp < .. note:: - There is a limitation of AppAPI ExApp proxy - the websocket connections are not supported. + There is a limitation of AppAPI ExApp proxy - the websocket connections are not supported. Each ExApp container has environment variables set by AppAPI; you can find out more about them :ref:`here `. @@ -112,20 +112,20 @@ For example, the **vuex** router has the following base URL configuration: .. code-block:: - ... - const router = new VueRouter({ - mode: 'history', - base: generateUrl(`${APP_API_ROUTER_BASE}/${EX_APP_ID}/${EX_APP_MENU_ENTRY_NAME}`, ''), // setting base to AppAPI embedded URL - linkActiveClass: 'active', - ... + ... + const router = new VueRouter({ + mode: 'history', + base: generateUrl(`${APP_API_ROUTER_BASE}/${EX_APP_ID}/${EX_APP_MENU_ENTRY_NAME}`, ''), // setting base to AppAPI embedded URL + linkActiveClass: 'active', + ... The same applies to the frontend API requests to the ExApp backend API: .. code-block:: - ... - axios.get(generateUrl(`${APP_API_PROXY_URL_PREFIX}/${EX_APP_ID}/some_api_endpoint`)) - ... + ... + axios.get(generateUrl(`${APP_API_PROXY_URL_PREFIX}/${EX_APP_ID}/some_api_endpoint`)) + ... .. _ex_app_translations: @@ -147,32 +147,32 @@ Here is an example using translationtool adjusted for Python: --- a/translations/translationtool/src/translationtool.php +++ b/translations/translationtool/src/translationtool.php @@ -67,7 +67,7 @@ public function createPotFile() { - $this->createFakeFileForVueFiles(); - $this->createFakeFileForLocale(); - $translatableFiles = $this->findTranslatableFiles( - - ['.php', '.js', '.jsx', '.mjs', '.html', '.ts', '.tsx'], - + ['.php', '.js', '.jsx', '.mjs', '.html', '.ts', '.tsx', '.py'], - ['.min.js'] - ); + $this->createFakeFileForVueFiles(); + $this->createFakeFileForLocale(); + $translatableFiles = $this->findTranslatableFiles( + - ['.php', '.js', '.jsx', '.mjs', '.html', '.ts', '.tsx'], + + ['.php', '.js', '.jsx', '.mjs', '.html', '.ts', '.tsx', '.py'], + ['.min.js'] + ); @@ -79,6 +79,8 @@ public function createPotFile() { - $keywords = ''; - if (substr($entry, -4) === '.php') { - $keywords = '--keyword=t --keyword=n:1,2'; - + } elseif (substr($entry, -3) === '.py') { - + $keywords = '--keyword=_ --keyword=_n:1,2'; - } else { - $keywords = '--keyword=t:2 --keyword=n:2,3'; - } + $keywords = ''; + if (substr($entry, -4) === '.php') { + $keywords = '--keyword=t --keyword=n:1,2'; + + } elseif (substr($entry, -3) === '.py') { + + $keywords = '--keyword=_ --keyword=_n:1,2'; + } else { + $keywords = '--keyword=t:2 --keyword=n:2,3'; + } @@ -86,6 +88,8 @@ public function createPotFile() { - $language = '--language='; - if (substr($entry, -4) === '.php') { - $language .= 'PHP'; - + } elseif (substr($entry, -3) === '.py') { - + $language .= 'Python'; - } else { - $language .= 'Javascript'; - } + $language = '--language='; + if (substr($entry, -4) === '.php') { + $language .= 'PHP'; + + } elseif (substr($entry, -3) === '.py') { + + $language .= 'Python'; + } else { + $language .= 'Javascript'; + } where we declare the methods used in source code for translating strings. @@ -194,7 +194,7 @@ And this can be done with simple bash scripts, as `in our example for Python `_: for Python example ExApp transforms ``translationfiles//*.(po|mo)`` into the locale folder structure: ``//LC_MESSAGES/*.(po|mo)``. This can be adjusted to your needs, depending on the language you are using. .. note:: - Your translations conversion should be also included in `Dockerfile `_ build process, so that the ExApp translations are available in the Docker image. + Your translations conversion should be also included in `Dockerfile `_ build process, so that the ExApp translations are available in the Docker image. Makefile @@ -214,7 +214,7 @@ It is recommended to use the following default set of commands: - ``copy_translations``: copies translations to needed location depending on your ExApp backend programming language. .. note:: - These Makefiles are typically written to work in the `nextcloud-docker-dev `_ development environment. + These Makefiles are typically written to work in the `nextcloud-docker-dev `_ development environment. For a complete example, you can take a look at our `Makefile for the 3rd-party service example `_. This example also requires the ``xmlstarlet`` program to be installed so that the Makefile can automatically detect the ExApp version from the info.xml file. diff --git a/developer_manual/exapp_development/faq/BehindCompanyProxy.rst b/developer_manual/exapp_development/faq/BehindCompanyProxy.rst index fae0b80abb7..30f3a121b29 100644 --- a/developer_manual/exapp_development/faq/BehindCompanyProxy.rst +++ b/developer_manual/exapp_development/faq/BehindCompanyProxy.rst @@ -109,7 +109,7 @@ Method 2: Set System-Wide Environment Variables .. code-block:: bash - sudo nano /etc/environment + sudo nano /etc/environment 2. **Add Proxy Environment Variables** @@ -117,12 +117,12 @@ Method 2: Set System-Wide Environment Variables .. code-block:: bash - http_proxy="http://proxy.example.com:8080" - https_proxy="http://proxy.example.com:8080" + http_proxy="http://proxy.example.com:8080" + https_proxy="http://proxy.example.com:8080" - # If your proxy requires authentication: - http_proxy="http://username:password@proxy.example.com:8080" - https_proxy="http://username:password@proxy.example.com:8080" + # If your proxy requires authentication: + http_proxy="http://username:password@proxy.example.com:8080" + https_proxy="http://username:password@proxy.example.com:8080" Replace the placeholders with your actual proxy details. @@ -136,7 +136,7 @@ Method 2: Set System-Wide Environment Variables .. code-block:: bash - sudo -E -u www-data php occ app_api:app:register test-deploy docker_socket_proxy --info-xml https://raw.githubusercontent.com/nextcloud/test-deploy/main/appinfo/info.xml --test-deploy-mode --no-ansi --no-warnings + sudo -E -u www-data php occ app_api:app:register test-deploy docker_socket_proxy --info-xml https://raw.githubusercontent.com/nextcloud/test-deploy/main/appinfo/info.xml --test-deploy-mode --no-ansi --no-warnings It should now work without connectivity issues. diff --git a/developer_manual/exapp_development/faq/DockerSocketProxy.rst b/developer_manual/exapp_development/faq/DockerSocketProxy.rst index b64da5d07a1..e5cbbedaf7f 100644 --- a/developer_manual/exapp_development/faq/DockerSocketProxy.rst +++ b/developer_manual/exapp_development/faq/DockerSocketProxy.rst @@ -16,7 +16,7 @@ There are two parts of reverse proxy configuration: .. note:: - For remote Docker Socket Proxy setup, it should expose the ports on the host. + For remote Docker Socket Proxy setup, it should expose the ports on the host. .. _faq_nextcloud-aio-docker-socket-proxy: @@ -32,8 +32,8 @@ See `Nextcloud in Docker AIO (all-in-one) `_ only the Docker Engine APIs we actually use in AppAPI, - and it is additionally secured with haproxy authentication. + For local Deploy daemon setup, other implementations of Docker Socket Proxy may be enough. + But for remote Deploy daemon setup, we recommend using our DSP, + as `we allow `_ only the Docker Engine APIs we actually use in AppAPI, + and it is additionally secured with haproxy authentication. diff --git a/developer_manual/exapp_development/faq/GpuSupport.rst b/developer_manual/exapp_development/faq/GpuSupport.rst index 3c350ddb8b0..cd9ece345ca 100644 --- a/developer_manual/exapp_development/faq/GpuSupport.rst +++ b/developer_manual/exapp_development/faq/GpuSupport.rst @@ -15,9 +15,9 @@ and the necessary Docker runtime toolkits installed on the Deploy daemon host: .. note:: - If you encounter any issues with GPU support, it is highly dependent on the specific GPU device, - software libraries and therefore ExApps support of different hardware, or other factors. - Please, feel free to ask for help by creating an issue. + If you encounter any issues with GPU support, it is highly dependent on the specific GPU device, + software libraries and therefore ExApps support of different hardware, or other factors. + Please, feel free to ask for help by creating an issue. How to limit the number of GPUs per ExApp? diff --git a/developer_manual/exapp_development/faq/index.rst b/developer_manual/exapp_development/faq/index.rst index 97dd9ddddb9..f37b00f78ca 100644 --- a/developer_manual/exapp_development/faq/index.rst +++ b/developer_manual/exapp_development/faq/index.rst @@ -8,17 +8,17 @@ or provide a brief answer. .. note:: - This section will be updated with time, as new questions arise. - If you have a question that is not listed here or the answer is not enough for you, please feel free to - ask it by creating an issue in the `AppAPI repository `_. + This section will be updated with time, as new questions arise. + If you have a question that is not listed here or the answer is not enough for you, please feel free to + ask it by creating an issue in the `AppAPI repository `_. .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - DockerContainerRegistry - DockerSocketProxy - GpuSupport - Scaling - BehindCompanyProxy - Troubleshooting + DockerContainerRegistry + DockerSocketProxy + GpuSupport + Scaling + BehindCompanyProxy + Troubleshooting diff --git a/developer_manual/exapp_development/tech_details/Authentication.rst b/developer_manual/exapp_development/tech_details/Authentication.rst index faa6a709ba1..e6af596d6cf 100644 --- a/developer_manual/exapp_development/tech_details/Authentication.rst +++ b/developer_manual/exapp_development/tech_details/Authentication.rst @@ -16,16 +16,16 @@ Authentication flow .. mermaid:: - sequenceDiagram - participant ExApp - box Nextcloud - participant Nextcloud - participant AppAPI - end - ExApp->>+Nextcloud: Request to API - Nextcloud->>+AppAPI: Validate request - AppAPI-->>-Nextcloud: Request accepted/rejected - Nextcloud-->>-ExApp: Response (200/401) + sequenceDiagram + participant ExApp + box Nextcloud + participant Nextcloud + participant AppAPI + end + ExApp->>+Nextcloud: Request to API + Nextcloud->>+AppAPI: Validate request + AppAPI-->>-Nextcloud: Request accepted/rejected + Nextcloud-->>-ExApp: Response (200/401) .. _auth-headers: @@ -44,29 +44,29 @@ Authentication flow in details ****************************** .. mermaid:: - :zoom: - - sequenceDiagram - autonumber - participant ExApp - box Nextcloud - participant Nextcloud - participant AppAPI - end - ExApp->>+Nextcloud: Request to API - Nextcloud->>Nextcloud: Check if AUTHORIZATION-APP-API header exists - Nextcloud-->>ExApp: Reject if AUTHORIZATION-APP-API header not exists - Nextcloud->>Nextcloud: Check if AppAPI app is enabled - Nextcloud-->>ExApp: Reject if AppAPI is not exists or disabled - Nextcloud->>+AppAPI: Validate request - AppAPI-->>AppAPI: Check if ExApp exists and enabled - AppAPI-->>Nextcloud: Reject if ExApp not exists or disabled - AppAPI-->>AppAPI: Validate shared secret from AUTHORIZATION-APP-API - AppAPI-->>Nextcloud: Reject if secret does not match - AppAPI-->>AppAPI: Check if user is not empty and active - AppAPI-->>Nextcloud: Set active user - AppAPI->>-Nextcloud: Request accepted/rejected - Nextcloud->>-ExApp: Response (200/401) + :zoom: + + sequenceDiagram + autonumber + participant ExApp + box Nextcloud + participant Nextcloud + participant AppAPI + end + ExApp->>+Nextcloud: Request to API + Nextcloud->>Nextcloud: Check if AUTHORIZATION-APP-API header exists + Nextcloud-->>ExApp: Reject if AUTHORIZATION-APP-API header not exists + Nextcloud->>Nextcloud: Check if AppAPI app is enabled + Nextcloud-->>ExApp: Reject if AppAPI is not exists or disabled + Nextcloud->>+AppAPI: Validate request + AppAPI-->>AppAPI: Check if ExApp exists and enabled + AppAPI-->>Nextcloud: Reject if ExApp not exists or disabled + AppAPI-->>AppAPI: Validate shared secret from AUTHORIZATION-APP-API + AppAPI-->>Nextcloud: Reject if secret does not match + AppAPI-->>AppAPI: Check if user is not empty and active + AppAPI-->>Nextcloud: Set active user + AppAPI->>-Nextcloud: Request accepted/rejected + Nextcloud->>-ExApp: Response (200/401) AppAPIAuth @@ -82,9 +82,9 @@ After successful authentication, AppAPI sets the `app_api` session key to ``true .. code-block:: php - $this->session->set('app_api', true); + $this->session->set('app_api', true); .. note:: - The Nextcloud server verifies this session key and allows **CORS protection** and **Two-Factor authentication** to be bypassed for requests coming from ExApps. - Also, the rate limit is not applied to requests coming from ExApps. + The Nextcloud server verifies this session key and allows **CORS protection** and **Two-Factor authentication** to be bypassed for requests coming from ExApps. + Also, the rate limit is not applied to requests coming from ExApps. diff --git a/developer_manual/exapp_development/tech_details/Deployment.rst b/developer_manual/exapp_development/tech_details/Deployment.rst index 490ae1510af..a993baad4db 100644 --- a/developer_manual/exapp_development/tech_details/Deployment.rst +++ b/developer_manual/exapp_development/tech_details/Deployment.rst @@ -21,35 +21,35 @@ Before that, you will need to configure your Docker socket to be accessible by t If you use the remote Docker Engine API, you will need to expose it so that it is accessible by the Nextcloud instance and import certificates. .. note:: - For now, only the Docker daemon ``accepts-deploy-id: docker-install`` is supported. - For development and manually deployed apps in Docker, there is ``accepts-deploy-id: manual-install``. + For now, only the Docker daemon ``accepts-deploy-id: docker-install`` is supported. + For development and manually deployed apps in Docker, there is ``accepts-deploy-id: manual-install``. This can be done by the ``occ`` **app_api:daemon:register** command: .. code-block:: bash - app_api:daemon:register [--net NET] [--haproxy_password PASSWORD] [--compute_device DEVICE] [--set-default] [--] + app_api:daemon:register [--net NET] [--haproxy_password PASSWORD] [--compute_device DEVICE] [--set-default] [--] Arguments ********* - * ``name`` - unique name of the daemon (e.g. ``docker_local_sock``) - * ``display-name`` - name of the daemon (e.g. ``My Local Docker``, will be displayed in the UI) - * ``accepts-deploy-id`` - type of deployment (``docker-install`` or ``manual-install``) - * ``protocol`` - protocol used to connect to the daemon (``http`` or ``https``) - * ``host`` - host of the daemon (e.g. ``/var/run/docker.sock`` or ``host:port``) - * ``nextcloud_url`` - Nextcloud URL, Daemon config required option (e.g. ``https://nextcloud.local``) + * ``name`` - unique name of the daemon (e.g. ``docker_local_sock``) + * ``display-name`` - name of the daemon (e.g. ``My Local Docker``, will be displayed in the UI) + * ``accepts-deploy-id`` - type of deployment (``docker-install`` or ``manual-install``) + * ``protocol`` - protocol used to connect to the daemon (``http`` or ``https``) + * ``host`` - host of the daemon (e.g. ``/var/run/docker.sock`` or ``host:port``) + * ``nextcloud_url`` - Nextcloud URL, Daemon config required option (e.g. ``https://nextcloud.local``) Options ******* - * ``--net [network-name]`` - ``[required]`` network name to bind docker container to (default: ``host``) - * ``--haproxy_password PASSWORD`` - ``[optional]`` password for HAProxy Basic auth if ``AppAPI Docker Socket Proxy`` is used - * ``--compute_device DEVICE`` - ``[optional]`` GPU device to expose to the daemon (defaults to ``cpu``, but ``cuda`` and ``rocm`` are also supported) - * ``--set-default`` - ``[optional]`` sets the newly created daemon as the default + * ``--net [network-name]`` - ``[required]`` network name to bind docker container to (default: ``host``) + * ``--haproxy_password PASSWORD`` - ``[optional]`` password for HAProxy Basic auth if ``AppAPI Docker Socket Proxy`` is used + * ``--compute_device DEVICE`` - ``[optional]`` GPU device to expose to the daemon (defaults to ``cpu``, but ``cuda`` and ``rocm`` are also supported) + * ``--set-default`` - ``[optional]`` sets the newly created daemon as the default .. note:: - Common configurations are tested by the CI in our repository, see `workflows on GitHub `_. + Common configurations are tested by the CI in our repository, see `workflows on GitHub `_. Example ******* @@ -58,7 +58,7 @@ Example of ``occ`` **app_api:daemon:register** command: .. code-block:: bash - sudo -E -u www-data php occ app_api:daemon:register docker_local_sock "My Local Docker" docker-install http /var/run/docker.sock "https://nextcloud.local" --net nextcloud + sudo -E -u www-data php occ app_api:daemon:register docker_local_sock "My Local Docker" docker-install http /var/run/docker.sock "https://nextcloud.local" --net nextcloud ExApp registration @@ -69,22 +69,22 @@ This can be done by the ``occ`` **app_api:app:register** command: .. code-block:: bash - app_api:app:register [--info-xml INFO-XML] [--json-info JSON-INFO] [--] + app_api:app:register [--info-xml INFO-XML] [--json-info JSON-INFO] [--] Arguments ********* - * ``appid`` - unique name of the ExApp (e.g. ``app_python_skeleton``, must be the same as in deployed container) - * ``daemon-config-name`` - unique name of the daemon (e.g. ``docker_local_sock``) + * ``appid`` - unique name of the ExApp (e.g. ``app_python_skeleton``, must be the same as in deployed container) + * ``daemon-config-name`` - unique name of the daemon (e.g. ``docker_local_sock``) Options ******* - * ``--info-xml INFO-XML`` *[optional]* - path to info.xml file (url or local absolute path) - * ``--json-info JSON-INFO`` *[optional]* - ExApp deploy JSON info (json string) + * ``--info-xml INFO-XML`` *[optional]* - path to info.xml file (url or local absolute path) + * ``--json-info JSON-INFO`` *[optional]* - ExApp deploy JSON info (json string) .. warning:: - After successful deployment (pull, create, and start container), there is a heartbeat check with a 90 second timeout (will be configurable). + After successful deployment (pull, create, and start container), there is a heartbeat check with a 90 second timeout (will be configurable). Manual install for development ****************************** @@ -97,11 +97,11 @@ For all examples and applications we release, we usually add the ``manual_instal .. code-block:: - sudo -E -u www-data php occ app_api:app:register nc_py_api manual_install --json-info \ + sudo -E -u www-data php occ app_api:app:register nc_py_api manual_install --json-info \ "{\"id\":\"nc_py_api\",\"name\":\"nc_py_api\",\"daemon_config_name\":\"manual_install\",\"version\":\"1.0.0\",\"secret\":\"12345\",\"port\":$APP_PORT}" \ .. note:: - App deployment/startup should be done by the developer when ``manual-install`` DeployConfig type is used. + App deployment/startup should be done by the developer when ``manual-install`` DeployConfig type is used. .. _ex_app_env_vars: @@ -111,24 +111,24 @@ Deploy environment variables Deploy environment variables are used to configure the ExApp container. The following variables are required and built automatically: - * ``AA_VERSION`` - AppAPI version - * ``APP_SECRET`` - generated shared secret used for AppAPI authentication - * ``APP_ID`` - ExApp app ID - * ``APP_DISPLAY_NAME`` - ExApp display name - * ``APP_VERSION`` - ExApp version - * ``APP_HOST`` - host ExApp is listening on - * ``APP_PORT`` - port ExApp is listening on (randomly selected by AppAPI) - * ``APP_PERSISTENT_STORAGE`` - path to mounted volume for persistent data storage between ExApp updates - * ``NEXTCLOUD_URL`` - Nextcloud URL to connect to + * ``AA_VERSION`` - AppAPI version + * ``APP_SECRET`` - generated shared secret used for AppAPI authentication + * ``APP_ID`` - ExApp app ID + * ``APP_DISPLAY_NAME`` - ExApp display name + * ``APP_VERSION`` - ExApp version + * ``APP_HOST`` - host ExApp is listening on + * ``APP_PORT`` - port ExApp is listening on (randomly selected by AppAPI) + * ``APP_PERSISTENT_STORAGE`` - path to mounted volume for persistent data storage between ExApp updates + * ``NEXTCLOUD_URL`` - Nextcloud URL to connect to Application installation scheme ------------------------------- - 1. AppAPI deploys the application and launches it. - 2. For `N` seconds (default ``90``), AppAPI checks the ``/heartbeat`` endpoint with a ``GET`` request. - 3. AppAPI sends a ``POST`` request to the ``/init`` endpoint. If the ExApp does not implement the ``/init`` endpoint and AppAPI receives a 501 or 404 status code, AppAPI enables the application and goes straight to step 5. - 4. The ExApp sends an integer from ``0`` to ``100`` to the OCS endpoint ``apps/app_api/apps/status`` indicating the initialization progress. After sending ``100``, the application is considered initialized. - 5. AppAPI sends a ``PUT`` request to the ``/enabled`` endpoint. + 1. AppAPI deploys the application and launches it. + 2. For `N` seconds (default ``90``), AppAPI checks the ``/heartbeat`` endpoint with a ``GET`` request. + 3. AppAPI sends a ``POST`` request to the ``/init`` endpoint. If the ExApp does not implement the ``/init`` endpoint and AppAPI receives a 501 or 404 status code, AppAPI enables the application and goes straight to step 5. + 4. The ExApp sends an integer from ``0`` to ``100`` to the OCS endpoint ``apps/app_api/apps/status`` indicating the initialization progress. After sending ``100``, the application is considered initialized. + 5. AppAPI sends a ``PUT`` request to the ``/enabled`` endpoint. ExApp info.xml schema --------------------- @@ -139,12 +139,12 @@ It has the same structure as other Nextcloud appinfo/info.xml files, but with so .. code-block:: xml - ... - - - ghcr.io - nextcloud/talk_bot - latest - - - ... + ... + + + ghcr.io + nextcloud/talk_bot + latest + + + ... diff --git a/developer_manual/exapp_development/tech_details/InstallationFlow.rst b/developer_manual/exapp_development/tech_details/InstallationFlow.rst index 7f4b6798a12..8515f4c2086 100644 --- a/developer_manual/exapp_development/tech_details/InstallationFlow.rst +++ b/developer_manual/exapp_development/tech_details/InstallationFlow.rst @@ -14,8 +14,8 @@ The suffix will be added as follows: .. code:: - return $imageParams['image_src'] . '/' . - $imageParams['image_name'] . '-' . $daemonConfig['computeDevice']['id'] . ':' . $imageParams['image_tag']; + return $imageParams['image_src'] . '/' . + $imageParams['image_name'] . '-' . $daemonConfig['computeDevice']['id'] . ':' . $imageParams['image_tag']; For ``cpu``, AppAPI will first try to get the image from ``ghcr.io/nextcloud/skeleton-cpu:latest``. In case the image is not found, ``ghcr.io/nextcloud/skeleton:latest`` will be pulled. @@ -30,10 +30,10 @@ The first thing AppAPI does is deploy the application. In the case of Docker, this means: - 1. performing an image pull - 2. creating container from the docker image - 3. if the container supports `healthcheck` - AppAPI waits for the `healthy` status - 4. waiting until the “/heartbeat” endpoint becomes available with a ``GET`` request + 1. performing an image pull + 2. creating container from the docker image + 3. if the container supports `healthcheck` - AppAPI waits for the `healthy` status + 4. waiting until the “/heartbeat” endpoint becomes available with a ``GET`` request The application, in response to the "/heartbeat" request, should return: ``{"status": "ok"}``. @@ -52,8 +52,8 @@ AppAPI will get 404 or 501 error on it's request, but you can consider that init In case you want to implement "/init" endpoint, your application should: - 1. In "/init" handler: return a Response with empty JSON data on AppAPI call. - 2. In background job: send an OCS request to ``PUT /ocs/v1.php/apps/app_api/ex-app/status`` with the progress value. + 1. In "/init" handler: return a Response with empty JSON data on AppAPI call. + 2. In background job: send an OCS request to ``PUT /ocs/v1.php/apps/app_api/ex-app/status`` with the progress value. .. warning:: @@ -69,7 +69,7 @@ with a short explanation at what stage this error occurred. Example of request payload with error:: - {"progress": 67, "error": "connection error to huggingface."} + {"progress": 67, "error": "connection error to huggingface."} Enabled ------- @@ -82,30 +82,30 @@ To enable or disable the application, a PUT request is sent to the ``/enabled`` The ``enabled`` parameter accepts an integer value: - * `1` to enable the application - * `0` to disable the application + * `1` to enable the application + * `0` to disable the application For example, to enable the application, the request would be:: - PUT http://ex-app:2432/enabled?enabled=1 + PUT http://ex-app:2432/enabled?enabled=1 Similarly, to disable the application, the request would be:: - PUT http://ex-app:2432/enabled?enabled=0 + PUT http://ex-app:2432/enabled?enabled=0 This approach ensures that the application's state can be easily toggled using a simple query parameter. .. note:: The ``/enabled`` endpoint shares both **enabling** and **disabling**, - so the app should determine what is going on using the ``enabled`` input parameter of the request. + so the app should determine what is going on using the ``enabled`` input parameter of the request. Inside the ``/enabled`` handler, the application should register all actions related to the Nextcloud, such as the UI and other stuff. The response for this request should contain:: - {"error": ""} + {"error": ""} for success, and if some error occurs during **enabling**, it should be present and not be empty:: - {"error": "i can't handle enabling"} + {"error": "i can't handle enabling"} This is all the steps involved in the ExApp installation flow. diff --git a/developer_manual/exapp_development/tech_details/Translations.rst b/developer_manual/exapp_development/tech_details/Translations.rst index 7b36ac81572..5b2df26a1c4 100644 --- a/developer_manual/exapp_development/tech_details/Translations.rst +++ b/developer_manual/exapp_development/tech_details/Translations.rst @@ -15,7 +15,7 @@ For the front-end part, AppAPI will inject the current user's locale ``l10n/`), Files (for :ref:`FileAction `) and Settings (for :ref:`DeclarativeSettings `). + ExApp l10n files are included only on the ExApp UI pages (:ref:`Top Menu `), Files (for :ref:`FileAction `) and Settings (for :ref:`DeclarativeSettings `). Back-end @@ -49,7 +49,7 @@ This will allow the server to access the ExApp's strings with translations. .. note:: - Only the ``l10n`` folder must be present on the server side; ``appinfo/info.xml`` could lead to misdetection by the server as a PHP app folder. + Only the ``l10n`` folder must be present on the server side; ``appinfo/info.xml`` could lead to misdetection by the server as a PHP app folder. diff --git a/developer_manual/exapp_development/tech_details/api/appconfig.rst b/developer_manual/exapp_development/tech_details/api/appconfig.rst index 079ffc83c02..8a7b08ced09 100644 --- a/developer_manual/exapp_development/tech_details/api/appconfig.rst +++ b/developer_manual/exapp_development/tech_details/api/appconfig.rst @@ -5,7 +5,7 @@ AppConfig The ExApp AppConfig API is similar to the standard Nextcloud **appconfig** API. .. note:: - Since Nextcloud 32, sensitive config values are encrypted in the database. + Since Nextcloud 32, sensitive config values are encrypted in the database. Set app config value @@ -22,11 +22,11 @@ Request data .. code-block:: json - { - "configKey": "key", - "configValue": "value" - "sensitive": "store value encrypted in the database (0/1, default: 0)" - } + { + "configKey": "key", + "configValue": "value" + "sensitive": "store value encrypted in the database (0/1, default: 0)" + } Response data @@ -37,27 +37,27 @@ On error, OCS Bad Request is returned. .. code-block:: json - { - "ocs": - { - "meta": - { - "status":"ok", - "statuscode":100, - "message":"OK", - "totalitems":"", - "itemsperpage":"" - }, - "data": - { - "id":1084, - "appid":"app_id", - "configkey":"key", - "configvalue":"value", - "sensitive":1 - } - } - } + { + "ocs": + { + "meta": + { + "status":"ok", + "statuscode":100, + "message":"OK", + "totalitems":"", + "itemsperpage":"" + }, + "data": + { + "id":1084, + "appid":"app_id", + "configkey":"key", + "configvalue":"value", + "sensitive":1 + } + } + } Get app config values ^^^^^^^^^^^^^^^^^^^^^ @@ -71,9 +71,9 @@ Request data .. code-block:: json - { - "configKeys": ["key1", "key2", "key3"] - } + { + "configKeys": ["key1", "key2", "key3"] + } Response data ************* @@ -82,25 +82,25 @@ List of ExApp config values are returned. .. code-block:: json - { - "ocs": - { - "meta": - { - "status":"ok", - "statuscode":100, - "message":"OK", - "totalitems":"", - "itemsperpage":"" - }, - "data":[ - { - "configkey":"test_key", - "configvalue":"123" - } - ] - } - } + { + "ocs": + { + "meta": + { + "status":"ok", + "statuscode":100, + "message":"OK", + "totalitems":"", + "itemsperpage":"" + }, + "data":[ + { + "configkey":"test_key", + "configvalue":"123" + } + ] + } + } Delete app config values ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -114,9 +114,9 @@ Request data .. code-block:: json - { - "configKeys": ["key1", "key2", "key3"] - } + { + "configKeys": ["key1", "key2", "key3"] + } Response ******** @@ -125,17 +125,17 @@ Returns the number of configuration values removed. .. code-block:: json - { - "ocs": - { - "meta": - { - "status":"ok", - "statuscode":100, - "message":"OK", - "totalitems":"", - "itemsperpage":"" - }, - "data":1 - } - } + { + "ocs": + { + "meta": + { + "status":"ok", + "statuscode":100, + "message":"OK", + "totalitems":"", + "itemsperpage":"" + }, + "data":1 + } + } diff --git a/developer_manual/exapp_development/tech_details/api/events_listener.rst b/developer_manual/exapp_development/tech_details/api/events_listener.rst index 215540f79ba..bcc76290214 100644 --- a/developer_manual/exapp_development/tech_details/api/events_listener.rst +++ b/developer_manual/exapp_development/tech_details/api/events_listener.rst @@ -12,8 +12,8 @@ Please let us know if there are any specific event we should add support to. .. note:: - Unlike PHP events, all information from events comes to the ExApp **asynchronously**, more like a notification system - in order to not slow down the server. + Unlike PHP events, all information from events comes to the ExApp **asynchronously**, more like a notification system + in order to not slow down the server. Register ^^^^^^^^ @@ -25,15 +25,15 @@ Params .. code-block:: json - { - "eventType": "node_event", - "actionHandler": "/action_handler_route" - "eventSubtypes": [], - } + { + "eventType": "node_event", + "actionHandler": "/action_handler_route" + "eventSubtypes": [], + } .. note:: ``eventSubtypes`` is an optional parameter, when it is not specified all event subtypes will be propagated to ExApp. - Url in ``actionHandler`` is relative to the ExApp root, starting slash is not required. + Url in ``actionHandler`` is relative to the ExApp root, starting slash is not required. Unregister ^^^^^^^^^^ @@ -47,20 +47,20 @@ To unregister EventsListener, you just need to provide an `eventType` for the re .. code-block:: json - { - "eventType": "node_event" - } + { + "eventType": "node_event" + } Event payload ^^^^^^^^^^^^^ .. code-block:: json - { - "event_type": "node_event", - "event_subtype": "NodeCreatedEvent", - "event_data": "associative array depending on `event_subtype`" - } + { + "event_type": "node_event", + "event_subtype": "NodeCreatedEvent", + "event_data": "associative array depending on `event_subtype`" + } Events types ^^^^^^^^^^^^ @@ -71,12 +71,12 @@ Node Events ``node_event`` - events about File `Nodes` Supported event sub-types: - * ``NodeCreatedEvent`` - * ``NodeTouchedEvent`` - * ``NodeWrittenEvent`` - * ``NodeDeletedEvent`` - * ``NodeRenamedEvent`` - * ``NodeCopiedEvent`` + * ``NodeCreatedEvent`` + * ``NodeTouchedEvent`` + * ``NodeWrittenEvent`` + * ``NodeDeletedEvent`` + * ``NodeRenamedEvent`` + * ``NodeCopiedEvent`` For all Node events, ``event_data`` contains a ``target`` key which has the same format as in :ref:`FileActionsMenu payload `. diff --git a/developer_manual/exapp_development/tech_details/api/exapp.rst b/developer_manual/exapp_development/tech_details/api/exapp.rst index 83bc8275c64..68ae68f314f 100644 --- a/developer_manual/exapp_development/tech_details/api/exapp.rst +++ b/developer_manual/exapp_development/tech_details/api/exapp.rst @@ -24,13 +24,13 @@ The response data is a JSON array of ExApp objects with the following attributes .. code-block:: json - { - "id": "appid of the ExApp", - "name": "name of the ExApp", - "version": "version of the ExApp", - "enabled": "true/false flag", - "last_check_time": "timestamp of last successful Nextcloud->ExApp connection check", - } + { + "id": "appid of the ExApp", + "name": "name of the ExApp", + "version": "version of the ExApp", + "enabled": "true/false flag", + "last_check_time": "timestamp of last successful Nextcloud->ExApp connection check", + } Set ExApp init progress ^^^^^^^^^^^^^^^^^^^^^^^ @@ -39,7 +39,7 @@ Used during ExApp :ref:`initialization step `. .. note:: - AppAPIAuth required. + AppAPIAuth required. OCS endpoint: ``PUT /apps/app_api/ex-app/status`` @@ -48,10 +48,10 @@ Request data .. code-block:: json - { - "progress": "progress value", - "error": "optional, error string message" - } + { + "progress": "progress value", + "error": "optional, error string message" + } Response data ************* @@ -72,9 +72,9 @@ Returns the base URL of the Nextcloud instance: .. code-block:: json - { - "base_url": "http(s)://nextcloud.example.com" - } + { + "base_url": "http(s)://nextcloud.example.com" + } Make Requests to ExApps @@ -129,8 +129,8 @@ OCS endpoint: ``GET /apps/app_api/api/v1/ex-app/state`` .. note:: - This endpoint can be called by ExApp even if it is disabled on the Nextcloud side, - and requires :doc:`AppAPIAuth <../Authentication>`. + This endpoint can be called by ExApp even if it is disabled on the Nextcloud side, + and requires :doc:`AppAPIAuth <../Authentication>`. Response data ************* diff --git a/developer_manual/exapp_development/tech_details/api/fileactionsmenu.rst b/developer_manual/exapp_development/tech_details/api/fileactionsmenu.rst index 07a88561828..e107519d07d 100644 --- a/developer_manual/exapp_development/tech_details/api/fileactionsmenu.rst +++ b/developer_manual/exapp_development/tech_details/api/fileactionsmenu.rst @@ -9,7 +9,7 @@ AppAPI takes responsibility to register FileActionsMenu; ExApps only need to reg .. note:: - The FileActionsMenu is rendered only for enabled ExApps. + The FileActionsMenu is rendered only for enabled ExApps. Register ^^^^^^^^ @@ -23,25 +23,25 @@ Complete list of params (including optional): .. code-block:: json - { - "name": "unique_name_of_file_actions_menu", - "displayName": "Display name (for UI listing)", - "actionHandler": "/action_handler_route" - "mime": "mime of files where to display action menu", - "icon": "img/icon.svg", - "permissions": "permissions", - "order": "order_in_file_actions_menu", - } + { + "name": "unique_name_of_file_actions_menu", + "displayName": "Display name (for UI listing)", + "actionHandler": "/action_handler_route" + "mime": "mime of files where to display action menu", + "icon": "img/icon.svg", + "permissions": "permissions", + "order": "order_in_file_actions_menu", + } .. note:: Urls ``icon`` and ``actionHandler`` are relative to the ExApp root, starting slash is not required. Optional params *************** - * `permissions` - File permissions required to display action menu, default: **31** (all permissions) - * `order` - Order in file actions menu, default: **0** - * `icon` - Url to icon, default: **null** - * `mime` - One mime or mimes separated by commas, default: **file** + * `permissions` - File permissions required to display action menu, default: **31** (all permissions) + * `order` - Order in file actions menu, default: **0** + * `icon` - Url to icon, default: **null** + * `mime` - One mime or mimes separated by commas, default: **file** Unregister ^^^^^^^^^^ @@ -55,9 +55,9 @@ To unregister FileActionsMenu, you just need to provide the name of the register .. code-block:: json - { - "name": "unique_name_of_file_action_menu" - } + { + "name": "unique_name_of_file_action_menu" + } .. _node_info: @@ -69,25 +69,25 @@ The following data is sent to the ExApp FileActionsMenu handler from the context .. code-block:: json - { - "fileId": "123", - "name": "filename", - "directory": "relative/to/user/path/to/directory", - "etag": "file_etag", - "mime": "file_full_mime", - "fileType": "dir/file", - "mtime": "last modify time(integer)", - "size": "integer", - "favorite": "nc_favorite_flag", - "permissions": "file_permissions_for_owner", - "shareOwner": "optional, str", - "shareOwnerId": "optional, str", - "shareTypes": "optional, int", - "shareAttributes": "optional, int", - "sharePermissions": "optional, int", - "userId": "string", - "instanceId": "string", - } + { + "fileId": "123", + "name": "filename", + "directory": "relative/to/user/path/to/directory", + "etag": "file_etag", + "mime": "file_full_mime", + "fileType": "dir/file", + "mtime": "last modify time(integer)", + "size": "integer", + "favorite": "nc_favorite_flag", + "permissions": "file_permissions_for_owner", + "shareOwner": "optional, str", + "shareOwnerId": "optional, str", + "shareTypes": "optional, int", + "shareAttributes": "optional, int", + "sharePermissions": "optional, int", + "userId": "string", + "instanceId": "string", + } Redirect to ExApp UI page (top menu) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -119,12 +119,12 @@ User action .. mermaid:: - sequenceDiagram - User->>FileActionMenu: Press on registered ExApp action - FileActionMenu->>AppAPI: send action context payload - AppAPI->>ExApp: forward request to handler - ExApp->>AppAPI: handler accepted action status - AppAPI->>User: Alert (action sent or error) + sequenceDiagram + User->>FileActionMenu: Press on registered ExApp action + FileActionMenu->>AppAPI: send action context payload + AppAPI->>ExApp: forward request to handler + ExApp->>AppAPI: handler accepted action status + AppAPI->>User: Alert (action sent or error) Action results @@ -135,9 +135,9 @@ e.g. on a location configured in ExApp settings (``appconfig_ex``) or ExApp user .. mermaid:: - sequenceDiagram - ExApp->>Nextcloud: Upload result file - ExApp->>AppAPI: Send notification about action results + sequenceDiagram + ExApp->>Nextcloud: Upload result file + ExApp->>AppAPI: Send notification about action results Examples ^^^^^^^^ diff --git a/developer_manual/exapp_development/tech_details/api/index.rst b/developer_manual/exapp_development/tech_details/api/index.rst index 9e279aa7550..28e617c08c1 100644 --- a/developer_manual/exapp_development/tech_details/api/index.rst +++ b/developer_manual/exapp_development/tech_details/api/index.rst @@ -6,22 +6,22 @@ AppAPI Nextcloud APIs .. note:: - AppAPIAuth is required for all AppAPI OCS APIs, except ``ExApp``. + AppAPIAuth is required for all AppAPI OCS APIs, except ``ExApp``. .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - logging - appconfig - preferences - exapp - routes - utils - fileactionsmenu - topmenu - settings - notifications - events_listener - occ_command - talkbots - other_ocs + logging + appconfig + preferences + exapp + routes + utils + fileactionsmenu + topmenu + settings + notifications + events_listener + occ_command + talkbots + other_ocs diff --git a/developer_manual/exapp_development/tech_details/api/logging.rst b/developer_manual/exapp_development/tech_details/api/logging.rst index 5ba952b6e4a..5eb0b112aa3 100644 --- a/developer_manual/exapp_development/tech_details/api/logging.rst +++ b/developer_manual/exapp_development/tech_details/api/logging.rst @@ -6,8 +6,8 @@ There is a logging API that can be used to log messages from ExApps in Nextcloud .. note:: - You can retrieve the Nextcloud `loglevel` for internal ExApp usage - from private `app_api` (after authentication) capabilities. + You can retrieve the Nextcloud `loglevel` for internal ExApp usage + from private `app_api` (after authentication) capabilities. Send log message (OCS) ^^^^^^^^^^^^^^^^^^^^^^ @@ -19,10 +19,10 @@ Request data .. code-block:: json - { - "level": "log_lvl(integer)", - "message": "message", - } + { + "level": "log_lvl(integer)", + "message": "message", + } The possible values of ``log_lvl`` are described here: `Nextcloud Log level `_ diff --git a/developer_manual/exapp_development/tech_details/api/notifications.rst b/developer_manual/exapp_development/tech_details/api/notifications.rst index 0d9f80bfbce..0835f543e7d 100644 --- a/developer_manual/exapp_development/tech_details/api/notifications.rst +++ b/developer_manual/exapp_development/tech_details/api/notifications.rst @@ -18,33 +18,33 @@ Example payload. .. code-block:: json - { - "params": { - "object": "app_api", - "object_id": "app_api_id", - "subject_type": "app_api_ex_app", - "subject_params": { - "rich_subject": "Image {file} successfully upscaled!", - "rich_subject_params": { - "file": { - "type": "file", - "id": 123, - "name": "upscaled_image_name", - "path": "path/to/upscaled_image_name" - } - }, - "rich_message": "{user} checkout results!", - "rich_message_params": { - "user": { - "type": "user", - "id": "admin", - "name": "admin" - } - }, - "link": "http(s)://nextcloud.local/index.php/apps/files/?fileid=123" - } - } - } + { + "params": { + "object": "app_api", + "object_id": "app_api_id", + "subject_type": "app_api_ex_app", + "subject_params": { + "rich_subject": "Image {file} successfully upscaled!", + "rich_subject_params": { + "file": { + "type": "file", + "id": 123, + "name": "upscaled_image_name", + "path": "path/to/upscaled_image_name" + } + }, + "rich_message": "{user} checkout results!", + "rich_message_params": { + "user": { + "type": "user", + "id": "admin", + "name": "admin" + } + }, + "link": "http(s)://nextcloud.local/index.php/apps/files/?fileid=123" + } + } + } Params @@ -52,12 +52,12 @@ Params Required payload params: - * ``object`` - ``[required]`` should be set to default value, not used yet - * ``object_id`` - ``[required]`` should be set to default value, not used yet - * ``subject_type`` - ``[required]`` subject type should be set to default value, not used yet - * ``subject_params`` - ``[required]`` - * ``rich_subject`` - ``[optional]`` rich subject (title) string - * ``rich_subject_params`` - ``[optional]`` rich subject (title) params to replace rich objects in string - * ``rich_message`` - ``[optional]`` rich message string - * ``rich_message_params`` - ``[optional`` rich message params to replace objects in string - * ``link`` - absolute url to set for notification link + * ``object`` - ``[required]`` should be set to default value, not used yet + * ``object_id`` - ``[required]`` should be set to default value, not used yet + * ``subject_type`` - ``[required]`` subject type should be set to default value, not used yet + * ``subject_params`` - ``[required]`` + * ``rich_subject`` - ``[optional]`` rich subject (title) string + * ``rich_subject_params`` - ``[optional]`` rich subject (title) params to replace rich objects in string + * ``rich_message`` - ``[optional]`` rich message string + * ``rich_message_params`` - ``[optional`` rich message params to replace objects in string + * ``link`` - absolute url to set for notification link diff --git a/developer_manual/exapp_development/tech_details/api/occ_command.rst b/developer_manual/exapp_development/tech_details/api/occ_command.rst index 2e09fa33b68..e00703ef7d9 100644 --- a/developer_manual/exapp_development/tech_details/api/occ_command.rst +++ b/developer_manual/exapp_development/tech_details/api/occ_command.rst @@ -103,6 +103,6 @@ To unregister an OCC CLI command, you just need to provide a command `name`: .. code-block:: json - { - "name": "occ_command_name" - } + { + "name": "occ_command_name" + } diff --git a/developer_manual/exapp_development/tech_details/api/other_ocs.rst b/developer_manual/exapp_development/tech_details/api/other_ocs.rst index 44b752b5e56..b3a6b33bc5b 100644 --- a/developer_manual/exapp_development/tech_details/api/other_ocs.rst +++ b/developer_manual/exapp_development/tech_details/api/other_ocs.rst @@ -5,8 +5,8 @@ With AppAPI authentication, it is possible for ExApps to use any other OCS APIs .. note:: - To access these APIs, they have to be supported by AppAPI, - and the ExApp must grant access to them (in ``info.xml``) accordingly. + To access these APIs, they have to be supported by AppAPI, + and the ExApp must grant access to them (in ``info.xml``) accordingly. 1. Calendar 2. Contacts diff --git a/developer_manual/exapp_development/tech_details/api/preferences.rst b/developer_manual/exapp_development/tech_details/api/preferences.rst index 54aca6d79d3..5184ff84d52 100644 --- a/developer_manual/exapp_development/tech_details/api/preferences.rst +++ b/developer_manual/exapp_development/tech_details/api/preferences.rst @@ -6,7 +6,7 @@ The ExApp preferences API is similar to the standard preferences API. It is a user specific setting. .. note:: - Since Nextcloud 32, sensitive config values are encrypted in the database. + Since Nextcloud 32, sensitive config values are encrypted in the database. Set user config value @@ -21,11 +21,11 @@ Request data .. code-block:: json - { - "configKey": "key", - "configValue": "value", - "sensitive": "store value encrypted in the database (0/1, default: 0)" - } + { + "configKey": "key", + "configValue": "value", + "sensitive": "store value encrypted in the database (0/1, default: 0)" + } Response data @@ -36,27 +36,27 @@ On error, OCS Bad Request is returned. .. code-block:: json - { - "ocs": - { - "meta": - { - "status":"ok", - "statuscode":100, - "message":"OK", - "totalitems":"", - "itemsperpage":"" - }, - "data": - { - "id":983, - "appid":"app_id", - "configkey":"test key", - "configvalue":"123", - "sensitive":0 - } - } - } + { + "ocs": + { + "meta": + { + "status":"ok", + "statuscode":100, + "message":"OK", + "totalitems":"", + "itemsperpage":"" + }, + "data": + { + "id":983, + "appid":"app_id", + "configkey":"test key", + "configvalue":"123", + "sensitive":0 + } + } + } Get user config values ^^^^^^^^^^^^^^^^^^^^^^ @@ -70,9 +70,9 @@ Request data .. code-block:: json - { - "configKeys": ["key1", "key2", "key3"] - } + { + "configKeys": ["key1", "key2", "key3"] + } Response data ************* @@ -81,29 +81,29 @@ List of ExApp preferences values are returned. .. code-block:: json - { - "ocs": - { - "meta": - { - "status":"ok", - "statuscode":100, - "message":"OK", - "totalitems":"", - "itemsperpage":"" - }, - "data":[ - { - "configkey":"test key", - "configvalue":"123" - }, - { - "configkey":"test key2", - "configvalue":"321" - } - ] - } - } + { + "ocs": + { + "meta": + { + "status":"ok", + "statuscode":100, + "message":"OK", + "totalitems":"", + "itemsperpage":"" + }, + "data":[ + { + "configkey":"test key", + "configvalue":"123" + }, + { + "configkey":"test key2", + "configvalue":"321" + } + ] + } + } Delete user config values @@ -118,26 +118,26 @@ Request data .. code-block:: json - { - "configKeys": ["key1", "key2", "key3"] - } + { + "configKeys": ["key1", "key2", "key3"] + } Response ******** .. code-block:: json - { - "ocs": - { - "meta": - { - "status":"ok", - "statuscode":100, - "message":"OK", - "totalitems":"", - "itemsperpage":"" - }, - "data":2 - } - } + { + "ocs": + { + "meta": + { + "status":"ok", + "statuscode":100, + "message":"OK", + "totalitems":"", + "itemsperpage":"" + }, + "data":2 + } + } diff --git a/developer_manual/exapp_development/tech_details/api/routes.rst b/developer_manual/exapp_development/tech_details/api/routes.rst index b8739088b9a..8cb44522994 100644 --- a/developer_manual/exapp_development/tech_details/api/routes.rst +++ b/developer_manual/exapp_development/tech_details/api/routes.rst @@ -18,19 +18,19 @@ Example .. code-block:: - ... - - - - .* - GET,POST,PUT,DELETE - USER - [] - [401, 500] - - - - ... + ... + + + + .* + GET,POST,PUT,DELETE + USER + [] + [401, 500] + + + + ... where the fields are: diff --git a/developer_manual/exapp_development/tech_details/api/settings.rst b/developer_manual/exapp_development/tech_details/api/settings.rst index b08edf0e11f..15d7b2e9ee6 100644 --- a/developer_manual/exapp_development/tech_details/api/settings.rst +++ b/developer_manual/exapp_development/tech_details/api/settings.rst @@ -10,13 +10,13 @@ they will be stored in the database and can be retrieved using :doc:`preferences .. note:: - These settings are rendered only for enabled ExApps. + These settings are rendered only for enabled ExApps. .. warning:: - ``section_id`` from **scheme** should be already registered by any PHP application. + ``section_id`` from **scheme** should be already registered by any PHP application. - **AppAPI** provides two sections which you can use for that: ``ai_integration_team`` and ``declarative_settings``. + **AppAPI** provides two sections which you can use for that: ``ai_integration_team`` and ``declarative_settings``. Register Settings ^^^^^^^^^^^^^^^^^ @@ -30,9 +30,9 @@ Complete list of params (including optional): .. code-block:: json - { - "formScheme": "settings scheme" - } + { + "formScheme": "settings scheme" + } Unregister Menu Entry ^^^^^^^^^^^^^^^^^^^^^ @@ -44,168 +44,168 @@ Params .. code-block:: json - { - "formId": "formId from scheme" - } + { + "formId": "formId from scheme" + } Example of settings scheme in Python: .. code-block:: python - { - "id": "settings_example", - "priority": 10, - "section_type": "admin", - "section_id": "ai_integration_team", - "title": "AppAPI declarative settings", - "description": "These fields are rendered dynamically from declarative schema", - "fields": [ - { - "id": "field1", - "title": "Multi-selection", - "description": "Select some option setting", - "type": 'multi-select', - "options": ["foo", "bar", "baz"], - "placeholder": "Select some multiple options", - "default": ["foo", "bar"], - }, - { - "id": "some_real_setting", - 'title': 'Choose init status check background job interval', - 'description': 'How often AppAPI should check for initialization status', - 'type': 'radio', - 'placeholder': 'Choose init status check background job interval', - 'default': '40m', - 'options': [ - { - 'name': 'Each 40 minutes', - 'value': '40m', - }, - { - 'name': 'Each 60 minutes', - 'value': '60m', - }, - { - 'name': 'Each 120 minutes', - 'value': '120m', - }, - { - 'name': 'Each day', - 'value': f"{60 * 24}m", - }, - ], - }, - { - 'id': 'test_ex_app_field_1', - 'title': 'Default text field', - 'description': 'Set some simple text setting', - 'type': 'text', - 'placeholder': 'Enter text setting', - 'default': 'foo', - }, - { - 'id': 'test_ex_app_field_1_1', - 'title': 'Email field', - 'description': 'Set email config', - 'type': 'email', - 'placeholder': 'Enter email', - 'default': '', - }, - { - 'id': 'test_ex_app_field_1_2', - 'title': 'Tel field', - 'description': 'Set tel config', - 'type': 'tel', - 'placeholder': 'Enter your tel', - 'default': '', - }, - { - 'id': 'test_ex_app_field_1_3', - 'title': 'Url (website) field', - 'description': 'Set url config', - 'type': url', - 'placeholder': 'Enter url', - 'default': '', - }, - { - 'id': 'test_ex_app_field_1_4', - 'title': 'Number field', - 'description': 'Set number config', - 'type': 'number', - 'placeholder': 'Enter number value', - 'default': 0, - }, - { - 'id': 'test_ex_app_field_2', - 'title': 'Password', - 'description': 'Set some secure value setting', - 'type': password', - 'placeholder': 'Set secure value', - 'default': '', - }, - { - 'id': 'test_ex_app_field_3', - 'title': 'Selection', - 'description': 'Select some option setting', - 'type': 'select', - 'options': ['foo', 'bar', 'baz'], - 'placeholder': 'Select some option setting', - 'default': 'foo', - }, - { - 'id': 'test_ex_app_field_4', - 'title': 'Toggle something', - 'description': 'Select checkbox option setting', - 'type': 'checkbox', - 'label': 'Verify something if enabled', - 'default': False, - }, - { - 'id': 'test_ex_app_field_5', - 'title': 'Multiple checkbox toggles, describing one setting, checked options are saved as a JSON object {foo: true, bar: false}', - 'description': 'Select checkbox option setting', - 'type': 'multi-checkbox', - 'default': {'foo': True, 'bar': True}, - 'options': [ - { - 'name':'Foo', - 'value': 'foo', - }, - { - 'name': 'Bar', - 'value': 'bar', - }, - { - 'name': 'Baz', - 'value': 'baz', - }, - { - 'name': 'Qux', - 'value': 'qux', - }, - ], - }, - { - 'id': 'test_ex_app_field_6', - 'title': 'Radio toggles, describing one setting like single select', - 'description': 'Select radio option setting', - 'type': 'radio', - 'label': 'Select single toggle', - 'default': 'foo', - 'options': [ - { - 'name': 'First radio', - 'value': 'foo' - }, - { - 'name': 'Second radio', - 'value': 'bar' - }, - { - 'name': 'Second radio', - 'value': 'baz' - }, - ], - }, - ] - } + { + "id": "settings_example", + "priority": 10, + "section_type": "admin", + "section_id": "ai_integration_team", + "title": "AppAPI declarative settings", + "description": "These fields are rendered dynamically from declarative schema", + "fields": [ + { + "id": "field1", + "title": "Multi-selection", + "description": "Select some option setting", + "type": 'multi-select', + "options": ["foo", "bar", "baz"], + "placeholder": "Select some multiple options", + "default": ["foo", "bar"], + }, + { + "id": "some_real_setting", + 'title': 'Choose init status check background job interval', + 'description': 'How often AppAPI should check for initialization status', + 'type': 'radio', + 'placeholder': 'Choose init status check background job interval', + 'default': '40m', + 'options': [ + { + 'name': 'Each 40 minutes', + 'value': '40m', + }, + { + 'name': 'Each 60 minutes', + 'value': '60m', + }, + { + 'name': 'Each 120 minutes', + 'value': '120m', + }, + { + 'name': 'Each day', + 'value': f"{60 * 24}m", + }, + ], + }, + { + 'id': 'test_ex_app_field_1', + 'title': 'Default text field', + 'description': 'Set some simple text setting', + 'type': 'text', + 'placeholder': 'Enter text setting', + 'default': 'foo', + }, + { + 'id': 'test_ex_app_field_1_1', + 'title': 'Email field', + 'description': 'Set email config', + 'type': 'email', + 'placeholder': 'Enter email', + 'default': '', + }, + { + 'id': 'test_ex_app_field_1_2', + 'title': 'Tel field', + 'description': 'Set tel config', + 'type': 'tel', + 'placeholder': 'Enter your tel', + 'default': '', + }, + { + 'id': 'test_ex_app_field_1_3', + 'title': 'Url (website) field', + 'description': 'Set url config', + 'type': url', + 'placeholder': 'Enter url', + 'default': '', + }, + { + 'id': 'test_ex_app_field_1_4', + 'title': 'Number field', + 'description': 'Set number config', + 'type': 'number', + 'placeholder': 'Enter number value', + 'default': 0, + }, + { + 'id': 'test_ex_app_field_2', + 'title': 'Password', + 'description': 'Set some secure value setting', + 'type': password', + 'placeholder': 'Set secure value', + 'default': '', + }, + { + 'id': 'test_ex_app_field_3', + 'title': 'Selection', + 'description': 'Select some option setting', + 'type': 'select', + 'options': ['foo', 'bar', 'baz'], + 'placeholder': 'Select some option setting', + 'default': 'foo', + }, + { + 'id': 'test_ex_app_field_4', + 'title': 'Toggle something', + 'description': 'Select checkbox option setting', + 'type': 'checkbox', + 'label': 'Verify something if enabled', + 'default': False, + }, + { + 'id': 'test_ex_app_field_5', + 'title': 'Multiple checkbox toggles, describing one setting, checked options are saved as a JSON object {foo: true, bar: false}', + 'description': 'Select checkbox option setting', + 'type': 'multi-checkbox', + 'default': {'foo': True, 'bar': True}, + 'options': [ + { + 'name':'Foo', + 'value': 'foo', + }, + { + 'name': 'Bar', + 'value': 'bar', + }, + { + 'name': 'Baz', + 'value': 'baz', + }, + { + 'name': 'Qux', + 'value': 'qux', + }, + ], + }, + { + 'id': 'test_ex_app_field_6', + 'title': 'Radio toggles, describing one setting like single select', + 'description': 'Select radio option setting', + 'type': 'radio', + 'label': 'Select single toggle', + 'default': 'foo', + 'options': [ + { + 'name': 'First radio', + 'value': 'foo' + }, + { + 'name': 'Second radio', + 'value': 'bar' + }, + { + 'name': 'Second radio', + 'value': 'baz' + }, + ], + }, + ] + } diff --git a/developer_manual/exapp_development/tech_details/api/talkbots.rst b/developer_manual/exapp_development/tech_details/api/talkbots.rst index 12fe74c0704..3aa0f487acb 100644 --- a/developer_manual/exapp_development/tech_details/api/talkbots.rst +++ b/developer_manual/exapp_development/tech_details/api/talkbots.rst @@ -16,11 +16,11 @@ Request data .. code-block:: json - { - "name": "Talk bot display name", - "route": "/talk_bot_webhook_route_on_ex_app", - "description": "Talk bot description", - } + { + "name": "Talk bot display name", + "route": "/talk_bot_webhook_route_on_ex_app", + "description": "Talk bot description", + } Unregister ExApp Talk bot (OCS) @@ -35,7 +35,7 @@ Request data .. code-block:: json - { - "route": "/route_of_talk_bot" - } + { + "route": "/route_of_talk_bot" + } diff --git a/developer_manual/exapp_development/tech_details/api/topmenu.rst b/developer_manual/exapp_development/tech_details/api/topmenu.rst index 624314797ca..c852711f299 100644 --- a/developer_manual/exapp_development/tech_details/api/topmenu.rst +++ b/developer_manual/exapp_development/tech_details/api/topmenu.rst @@ -9,7 +9,7 @@ AppAPI takes responsibility to register TopMenu and proxy all requests to the Ex .. note:: - The TopMenu is rendered only for enabled ExApps. + The TopMenu is rendered only for enabled ExApps. Register Menu Entry ^^^^^^^^^^^^^^^^^^^ @@ -23,12 +23,12 @@ Complete list of params (including optional): .. code-block:: json - { - "name": "unique_name_of_top_menu", - "displayName": "Display name", - "icon": "img/icon.svg", - "adminRequired": "0 or 1", - } + { + "name": "unique_name_of_top_menu", + "displayName": "Display name", + "icon": "img/icon.svg", + "adminRequired": "0 or 1", + } .. note:: ``icon`` is relative to the ExApp root, starting slash is not required. @@ -36,8 +36,8 @@ Complete list of params (including optional): Optional params *************** - * `icon` - Url to icon, default: **null** - * `adminRequired` - Value indicating whether the entry should be visible to all or only to admins + * `icon` - Url to icon, default: **null** + * `adminRequired` - Value indicating whether the entry should be visible to all or only to admins Unregister Menu Entry ^^^^^^^^^^^^^^^^^^^^^ @@ -51,9 +51,9 @@ To unregister TopMenu, just provide the name of registered TopMenu: .. code-block:: json - { - "name": "unique_name_of_top_menu" - } + { + "name": "unique_name_of_top_menu" + } Set Initial state ^^^^^^^^^^^^^^^^^ @@ -65,12 +65,12 @@ Params .. code-block:: json - { - "type": "top_menu", - "name": "unique_name_of_top_menu", - "key": "key_name", - "value": "array with value(s)", - } + { + "type": "top_menu", + "name": "unique_name_of_top_menu", + "key": "key_name", + "value": "array with value(s)", + } Remove Initial state ^^^^^^^^^^^^^^^^^^^^ @@ -82,11 +82,11 @@ Params .. code-block:: json - { - "type": "top_menu", - "name": "unique_name_of_top_menu", - "key": "key_name", - } + { + "type": "top_menu", + "name": "unique_name_of_top_menu", + "key": "key_name", + } Add script ^^^^^^^^^^ @@ -98,15 +98,15 @@ Params .. code-block:: json - { - "type": "top_menu", - "name": "unique_name_of_script", - "path": "Url to script, e.g.: js/ui_example-main", - "afterAppId": "optional value", - } + { + "type": "top_menu", + "name": "unique_name_of_script", + "path": "Url to script, e.g.: js/ui_example-main", + "afterAppId": "optional value", + } .. note:: Url to script is relative to the ExApp root, starting slash is not required, - ".js" extension is not needed and will be appended automatically by server. + ".js" extension is not needed and will be appended automatically by server. Remove script ^^^^^^^^^^^^^ @@ -118,11 +118,11 @@ Params .. code-block:: json - { - "type": "top_menu", - "name": "unique_name_of_script", - "path": "Url to script", - } + { + "type": "top_menu", + "name": "unique_name_of_script", + "path": "Url to script", + } Add style ^^^^^^^^^ @@ -134,14 +134,14 @@ Params .. code-block:: json - { - "type": "top_menu", - "name": "unique_name_of_style", - "path": "Url to style, e.g.: css/my-style", - } + { + "type": "top_menu", + "name": "unique_name_of_style", + "path": "Url to style, e.g.: css/my-style", + } .. note:: Url to style is relative to the ExApp root, starting slash is not required, - ".css" extension is not needed and will be appended automatically by server. + ".css" extension is not needed and will be appended automatically by server. Remove style ^^^^^^^^^^^^ @@ -153,8 +153,8 @@ Params .. code-block:: json - { - "type": "top_menu", - "name": "unique_name_of_style", - "path": "Url to style", - } + { + "type": "top_menu", + "name": "unique_name_of_style", + "path": "Url to style", + } diff --git a/developer_manual/exapp_development/tech_details/api/utils.rst b/developer_manual/exapp_development/tech_details/api/utils.rst index c9c3b8a97b7..c98b35e9a2d 100644 --- a/developer_manual/exapp_development/tech_details/api/utils.rst +++ b/developer_manual/exapp_development/tech_details/api/utils.rst @@ -17,14 +17,14 @@ Returns a list of user IDs only. .. code-block:: json - {"ocs": { - "meta": { - "status": "ok", - "statuscode": 100, - "message": "OK", - "totalitems": "", - "itemsperpage": "" - }, - "data": ["admin", "alice", "bob", "jane", "john"] - } - } + {"ocs": { + "meta": { + "status": "ok", + "statuscode": 100, + "message": "OK", + "totalitems": "", + "itemsperpage": "" + }, + "data": ["admin", "alice", "bob", "jane", "john"] + } + } diff --git a/developer_manual/getting_started/coding_standards/html_css.rst b/developer_manual/getting_started/coding_standards/html_css.rst index 20de48a4600..d297bffa559 100644 --- a/developer_manual/getting_started/coding_standards/html_css.rst +++ b/developer_manual/getting_started/coding_standards/html_css.rst @@ -14,16 +14,16 @@ HTML .. code-block:: html - + **DON'T** .. code-block:: html - + CSS --- diff --git a/developer_manual/getting_started/coding_standards/index.rst b/developer_manual/getting_started/coding_standards/index.rst index 120bd04f22b..c4688699df7 100644 --- a/developer_manual/getting_started/coding_standards/index.rst +++ b/developer_manual/getting_started/coding_standards/index.rst @@ -88,11 +88,11 @@ Coding standards The most part of Nextcloud is written in PHP, Typescript / JavaScript, so we have some more fine grained coding standards for those languages: .. toctree:: - :maxdepth: 1 + :maxdepth: 1 - php - javascript - html_css + php + javascript + html_css License headers --------------- @@ -108,7 +108,7 @@ If you create a new file please use this header: * SPDX-FileCopyrightText: [year] [your name] [] * SPDX-License-Identifier: AGPL-3.0-or-later */ - + The year should then be the creation time and the email address is optional. If you edit an existing file please, please keep the existing license header as it is and just add your copyright notice, if you consider your changes substantial enough to claim copyright. @@ -130,7 +130,7 @@ file is preferred please see the example below The Nextcloud GmbH part only applies to employees of the company not to contributors. -For more, general information on SPDX headers and their usage for reuse-compliance, please see +For more, general information on SPDX headers and their usage for reuse-compliance, please see * `REUSE `_ * `SPDX `_ diff --git a/developer_manual/getting_started/coding_standards/javascript.rst b/developer_manual/getting_started/coding_standards/javascript.rst index 99d0e110fed..6e54416e030 100644 --- a/developer_manual/getting_started/coding_standards/javascript.rst +++ b/developer_manual/getting_started/coding_standards/javascript.rst @@ -3,7 +3,7 @@ JavaScript and Typescript ========================= .. contents:: - :local: + :local: General rules and advice ------------------------ @@ -27,23 +27,23 @@ Filesystem structure For vanilla JavaScript we recommend the following structure: - ``appid/``: Root of the app - - ``js/``: JavaScript files - - ``appid.js``: Your app entry point - - ``css/``: Location for all CSS files - - ``appid.css`` + - ``js/``: JavaScript files + - ``appid.js``: Your app entry point + - ``css/``: Location for all CSS files + - ``appid.css`` When using a bundler to compile Typescript (or JavaScript) we recommend the following structure: - ``appid/``: Root of the app - - ``js/``: Compiled JavaScript files - - ``css/``: Compiled CSS output - - ``src/``: Root of all source files - - ``components/``: Location of Vue components - - ``composables/``: Location of Vue composables - - ``services/``: Location for service files like API abstractions - - ``stores/``: Location of Pinia stores - - ``views/``: Location of views - - ``main.ts``: Main entry point of your app + - ``js/``: Compiled JavaScript files + - ``css/``: Compiled CSS output + - ``src/``: Root of all source files + - ``components/``: Location of Vue components + - ``composables/``: Location of Vue composables + - ``services/``: Location for service files like API abstractions + - ``stores/``: Location of Pinia stores + - ``views/``: Location of views + - ``main.ts``: Main entry point of your app Filenames """"""""" @@ -64,18 +64,18 @@ Naming and casing - Use **camelCase** for - - functions - - methods - - properties - - variables + - functions + - methods + - properties + - variables - Use **PascalCase** for - - classes - - enums - - types - - interfaces - - Vue components + - classes + - enums + - types + - interfaces + - Vue components - For readability only capitalize the first letter of abbreviations like ``callHttpApi()`` instead of ``callHTTPAPI()``. - Sub-components should be prefixed. @@ -84,184 +84,184 @@ Naming and casing E.g. if you have a settings view, do not call it ``Settings`` but ``SettingsView`` or ``UserSettings`` etc. .. list-table:: Use camelCase for functions, methods, properties, and variables - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - const fileId = 123 - const obj = { - myProperty: false, - } - doSomething() + const fileId = 123 + const obj = { + myProperty: false, + } + doSomething() - - - .. code-block:: javascript + - + .. code-block:: javascript - const file_id = 123 - const obj = { - 'my-property': false, - } - do_something() + const file_id = 123 + const obj = { + 'my-property': false, + } + do_something() .. list-table:: Use PascalCase for classes, interfaces, types and Vue components - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - class MyClass { /* ... */ } - interface IRequest { /* ... */ } - type Arguments = string[] + class MyClass { /* ... */ } + interface IRequest { /* ... */ } + type Arguments = string[] - - - .. code-block:: javascript + - + .. code-block:: javascript - class myClass { /* ... */ } - interface I_request { /* ... */ } - type arguments = string[] + class myClass { /* ... */ } + interface I_request { /* ... */ } + type arguments = string[] Indentation """"""""""" - Use tabs instead of spaces for indenting - tab width is 4 spaces. - - You can align e.g. comments using spaces if needed. + - You can align e.g. comments using spaces if needed. Semicolons """""""""" .. list-table:: Avoid semicolons where not needed. - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - const text = 'foo' - doSomething() + const text = 'foo' + doSomething() - - - .. code-block:: javascript + - + .. code-block:: javascript - const text = 'foo'; - doSomething(); + const text = 'foo'; + doSomething(); - * - - .. code-block:: javascript + * - + .. code-block:: javascript - const text = 'foo' - ;(someProp as SomeType).handle() + const text = 'foo' + ;(someProp as SomeType).handle() - - + - Strings ^^^^^^^ .. list-table:: Use single quotes. - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - const text = 'foo' + const text = 'foo' - - - .. code-block:: javascript + - + .. code-block:: javascript - const text = "foo" + const text = "foo" .. list-table:: Prefer template literals for readability. - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - const text = `Hello ${username}!` + const text = `Hello ${username}!` - - - .. code-block:: javascript + - + .. code-block:: javascript - const text = 'Hello ' + username + const text = 'Hello ' + username Arrays ^^^^^^ .. list-table:: Avoid multiple properties on the same line - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - const arr = [ - 'first', - 'second', - 'third', - ] + const arr = [ + 'first', + 'second', + 'third', + ] - - - .. code-block:: javascript + - + .. code-block:: javascript - const arr = ['first', 'second', 'third'] + const arr = ['first', 'second', 'third'] .. list-table:: Use dangling commas, this reduces the diff when adding new properties. - :widths: 50 50 - :header-rows: 1 - - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript - - const arr = [ - 'first', - 'second', - 'third', - ] - - - - .. code-block:: javascript - - const arr = [ - 'first', - 'second', - 'third' - ] - * - - .. code-block:: diff - - const arr = [ - 'first', - 'second', - + 'third', - ] - - - - .. code-block:: diff - - const arr = [ - 'first', - - 'second' - + 'second', - + 'third' - ] + :widths: 50 50 + :header-rows: 1 + + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript + + const arr = [ + 'first', + 'second', + 'third', + ] + + - + .. code-block:: javascript + + const arr = [ + 'first', + 'second', + 'third' + ] + * - + .. code-block:: diff + + const arr = [ + 'first', + 'second', + + 'third', + ] + + - + .. code-block:: diff + + const arr = [ + 'first', + - 'second' + + 'second', + + 'third' + ] Functions ^^^^^^^^^ @@ -277,339 +277,339 @@ Functions - When using implicit return values in arrow functions with multi-line body use parenthesis around the body. .. list-table:: No space between function name and parameters - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - doSomething(1, false) + doSomething(1, false) - - - .. code-block:: javascript + - + .. code-block:: javascript - doSomething (1, false) + doSomething (1, false) .. list-table:: Braces on same line as the definition. - :widths: 50 50 - :header-rows: 1 - - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript - - function foo(name: string): boolean { - // do something - } - - - - .. code-block:: javascript - - function foo(name: string): boolean - { - // do something - } - * - - .. code-block:: javascript - - function bar( - firstName: string, - lastName: string, - ): boolean { - // do something - } - - - - .. code-block:: javascript - - function bar( - firstName: string, - lastName: string, - ): boolean - { - // do something - } - * - - .. code-block:: javascript - - const arrow = (name: string) => { - // do something - } - - - - .. code-block:: javascript - - const arrow = (name: string) => - { - // do something - } + :widths: 50 50 + :header-rows: 1 + + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript + + function foo(name: string): boolean { + // do something + } + + - + .. code-block:: javascript + + function foo(name: string): boolean + { + // do something + } + * - + .. code-block:: javascript + + function bar( + firstName: string, + lastName: string, + ): boolean { + // do something + } + + - + .. code-block:: javascript + + function bar( + firstName: string, + lastName: string, + ): boolean + { + // do something + } + * - + .. code-block:: javascript + + const arrow = (name: string) => { + // do something + } + + - + .. code-block:: javascript + + const arrow = (name: string) => + { + // do something + } .. list-table:: Use consistent new lines in function parameters - :widths: 50 50 - :header-rows: 1 - - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript - - function doSomething(num: number, enable: boolean) { - // ... - } - - - - .. code-block:: javascript - - function doSomething(num: number, - enable: boolean) { - // ... - } - * - - .. code-block:: javascript - - function doSomething( - num: number, - enable: boolean, - ) { - // ... - } - - - - .. code-block:: javascript - - function doSomething( - num: number, enable: boolean, - ) { - // ... - } + :widths: 50 50 + :header-rows: 1 + + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript + + function doSomething(num: number, enable: boolean) { + // ... + } + + - + .. code-block:: javascript + + function doSomething(num: number, + enable: boolean) { + // ... + } + * - + .. code-block:: javascript + + function doSomething( + num: number, + enable: boolean, + ) { + // ... + } + + - + .. code-block:: javascript + + function doSomething( + num: number, enable: boolean, + ) { + // ... + } .. list-table:: Prefer regular top-level functions. - :widths: 50 50 - :header-rows: 1 - - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript - - export function doSomething(num: number, enable: boolean) { - // ... - } - - - - .. code-block:: javascript - - export const doSomething = (num: number, enable: boolean) => { - // ... - } - * - - .. code-block:: javascript - - someArray.map((item) => item.name) - // or - someArray.map((item) => { - return item.name - }) - - - - .. code-block:: javascript - - // while this is valid and work - someArray.map(function (item) { - return item.name - }) - // there is a caveat with accessing "this" - someArray.map(function (item) { - // "this" is not the previous context - // but the context of the callback function. - // Thus this.category will be undefined. - return `${this.category}: ${item.name}` - }) + :widths: 50 50 + :header-rows: 1 + + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript + + export function doSomething(num: number, enable: boolean) { + // ... + } + + - + .. code-block:: javascript + + export const doSomething = (num: number, enable: boolean) => { + // ... + } + * - + .. code-block:: javascript + + someArray.map((item) => item.name) + // or + someArray.map((item) => { + return item.name + }) + + - + .. code-block:: javascript + + // while this is valid and work + someArray.map(function (item) { + return item.name + }) + // there is a caveat with accessing "this" + someArray.map(function (item) { + // "this" is not the previous context + // but the context of the callback function. + // Thus this.category will be undefined. + return `${this.category}: ${item.name}` + }) .. list-table:: Always use parenthesis for arrow function parameters. - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - myArray.map((item) => item.name) + myArray.map((item) => item.name) - - - .. code-block:: javascript + - + .. code-block:: javascript - myArray.map(item => item.name) + myArray.map(item => item.name) - * - - .. code-block:: javascript + * - + .. code-block:: javascript - myArray.map((item, index) => getName(item, index)) + myArray.map((item, index) => getName(item, index)) - - + - .. list-table:: Use parenthesis for multi-line body of arrow functions. - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - myArray.map((item) => ( - item.value - ? 'yes' - : 'no' - )) + myArray.map((item) => ( + item.value + ? 'yes' + : 'no' + )) - - - .. code-block:: javascript + - + .. code-block:: javascript - myArray.map((item) => item.value - ? 'yes' - : 'no' - ) + myArray.map((item) => item.value + ? 'yes' + : 'no' + ) - * - - .. code-block:: javascript + * - + .. code-block:: javascript - myArray.map((item) => ({ - prop: item.value, - other: true, - })) + myArray.map((item) => ({ + prop: item.value, + other: true, + })) - - + - Objects ^^^^^^^ .. list-table:: Only quote properties when needed. - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - const obj = { - noQuotesNeeded: true, - 'quotes-needed': false, - } + const obj = { + noQuotesNeeded: true, + 'quotes-needed': false, + } - - - .. code-block:: javascript + - + .. code-block:: javascript - const obj = { - 'noQuotesNeeded': true, - 'quotes-needed': false, - } + const obj = { + 'noQuotesNeeded': true, + 'quotes-needed': false, + } .. list-table:: Prefer shorthand properties - :widths: 50 50 - :header-rows: 1 - - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript - - const name = 'jdoe' - // ... - const obj = { - name, - id: 123, - } - - - - .. code-block:: javascript - - const name = 'jdoe' - // ... - const obj = { - name: name, - id: 123, - } + :widths: 50 50 + :header-rows: 1 + + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript + + const name = 'jdoe' + // ... + const obj = { + name, + id: 123, + } + + - + .. code-block:: javascript + + const name = 'jdoe' + // ... + const obj = { + name: name, + id: 123, + } .. list-table:: Avoid multiple properties on the same line - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - const obj = { - first: 1, - second: 'two', - } + const obj = { + first: 1, + second: 'two', + } - - - .. code-block:: javascript + - + .. code-block:: javascript - const obj = { first: 1, second: 'two' } + const obj = { first: 1, second: 'two' } .. list-table:: Add spaces around content when needed - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - const obj = { prop: true } + const obj = { prop: true } - - - .. code-block:: javascript + - + .. code-block:: javascript - const obj = {prop: true} + const obj = {prop: true} .. list-table:: Use dangling commas, this reduces the diff when adding new properties. - :widths: 50 50 - :header-rows: 1 - - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript - - const obj = { - first: 1, - second: 2, - } - - - - .. code-block:: javascript - - const obj = { - first: 1, - second: 2 - } - * - - .. code-block:: diff - - const obj = { - first: 1, - second: 2, - + third: 3, - } - - - - .. code-block:: diff - - const obj = { - first: 1, - - second: 2 - + second: 2, - + third: 3 - } + :widths: 50 50 + :header-rows: 1 + + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript + + const obj = { + first: 1, + second: 2, + } + + - + .. code-block:: javascript + + const obj = { + first: 1, + second: 2 + } + * - + .. code-block:: diff + + const obj = { + first: 1, + second: 2, + + third: 3, + } + + - + .. code-block:: diff + + const obj = { + first: 1, + - second: 2 + + second: 2, + + third: 3 + } Operators ^^^^^^^^^ @@ -635,25 +635,25 @@ Here's why: ' \t\r\n ' == 0 // true .. list-table:: Use explicit comparisons - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - if (array.length > 0) { /* ... */ } + if (array.length > 0) { /* ... */ } - - - .. code-block:: javascript + - + .. code-block:: javascript - if (array.length) { /* ... */ } - * - - - - .. code-block:: javascript + if (array.length) { /* ... */ } + * - + - + .. code-block:: javascript - if (array) { /* this is always true! */ } + if (array) { /* this is always true! */ } Control structures ^^^^^^^^^^^^^^^^^^ @@ -663,54 +663,54 @@ Control structures - Always use break in switch statements and prevent a default block with warnings if it shouldn't be accessed .. list-table:: Always use braces. - :widths: 50 50 - :header-rows: 1 + :widths: 50 50 + :header-rows: 1 - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript - if (myVar === 'hi') { - doSomething() - } + if (myVar === 'hi') { + doSomething() + } - - - .. code-block:: javascript + - + .. code-block:: javascript - if (array.length > 0) doSomething() - * - - .. code-block:: javascript + if (array.length > 0) doSomething() + * - + .. code-block:: javascript - for (let i = 0; i < 4; i++) { - // your code - } + for (let i = 0; i < 4; i++) { + // your code + } - - - .. code-block:: javascript + - + .. code-block:: javascript - for (let i = 0; i < 4; i++) - // your code + for (let i = 0; i < 4; i++) + // your code .. list-table:: Split long conditions into multiple lines. - :widths: 50 50 - :header-rows: 1 - - * - ✅ Do - - ❌ Don't - * - - .. code-block:: javascript - - if (something === 'something' - || condition2 - && condition3 - ) { - // your code - } - - - - .. code-block:: javascript - - if (something === 'something' || condition2 && condition3) { - // your code - } + :widths: 50 50 + :header-rows: 1 + + * - ✅ Do + - ❌ Don't + * - + .. code-block:: javascript + + if (something === 'something' + || condition2 + && condition3 + ) { + // your code + } + + - + .. code-block:: javascript + + if (something === 'something' || condition2 && condition3) { + // your code + } diff --git a/developer_manual/getting_started/development_process.rst b/developer_manual/getting_started/development_process.rst index 3c335a7c198..6a02f5f528f 100644 --- a/developer_manual/getting_started/development_process.rst +++ b/developer_manual/getting_started/development_process.rst @@ -40,7 +40,7 @@ Bugfixes If a contribution fixes a bug that also affects older Nextcloud or app releases, it may qualify for a *backport*. Backporting a fix means applying the change on an older version of the code. Git calls this operation *cherry picking*. -Whenever a critical bug (i.e. security vulnerability) is fixed, it is backported to all applicable major releases and - once merged - published in the next set of maintenance releases for all still supported majors (e.g. 28.0.3 -> 28.0.4). +Whenever a critical bug (i.e. security vulnerability) is fixed, it is backported to all applicable major releases and - once merged - published in the next set of maintenance releases for all still supported majors (e.g. 28.0.3 -> 28.0.4). Backporting Considerations ************************** @@ -76,7 +76,7 @@ When assessing whether a bug is critical enough to backport, here are some possi - Does the main tracking Issue have a lot of upvotes/subscribers/comments? - Is it possible to take a "wait and see" attitude about backporting (i.e. continue to test the fix in main/master branch and wait one maintenance cycle to re-evaluate and only backport if further data from the field suggests its important enough and/or low-risk enough to do so)? -Use your best judgement. +Use your best judgement. If appropriate, mention any major concerns in the backport PR so other code reviewers can consider them. diff --git a/developer_manual/getting_started/devenv.rst b/developer_manual/getting_started/devenv.rst index 39c19588f94..429376adb69 100644 --- a/developer_manual/getting_started/devenv.rst +++ b/developer_manual/getting_started/devenv.rst @@ -6,7 +6,7 @@ Development environment ======================= -We have a tutorial available on setting up your development environment using docker. You can find the tutorial `here `_. We recommend you to follow that tutorial. +We have a tutorial available on setting up your development environment using docker. You can find the tutorial `here `_. We recommend you to follow that tutorial. This page describes how to set up your development environment without docker. diff --git a/developer_manual/how_to/index.rst b/developer_manual/how_to/index.rst index b9a762640fe..8f1c62dc1be 100644 --- a/developer_manual/how_to/index.rst +++ b/developer_manual/how_to/index.rst @@ -138,9 +138,9 @@ SAML setup with onelogin - Audience: https://localhost/apps/user_saml/saml/metadata - Recipient: https://localhost/apps/user_saml/saml/acs - ACS (Consumer) URL Validator: https://localhost/apps/user_saml/saml/acs - + - go to "Parameters" - + - Add "User.email" -> email (and add to assertion) - Add "User.FirstName" -> first name (and add to assertion) - Add "User.LastName" -> last name (and add to assertion) @@ -260,12 +260,12 @@ WebAuthn without SSL --- a/3rdparty/web-auth/webauthn-lib/src/AuthenticatorAttestationResponseValidator.php +++ b/3rdparty/web-auth/webauthn-lib/src/AuthenticatorAttestationResponseValidator.php @@ -150,7 +150,7 @@ class AuthenticatorAttestationResponseValidator - + if (!in_array($facetId, $securedRelyingPartyId, true)) { $scheme = $parsedRelyingPartyId['scheme'] ?? ''; - Assertion::eq('https', $scheme, 'Invalid scheme. HTTPS required.'); + #Assertion::eq('https', $scheme, 'Invalid scheme. HTTPS required.'); } - + /* @see 7.1.6 */ diff --git a/developer_manual/html_css_design/content.rst b/developer_manual/html_css_design/content.rst index 7d3406eb69a..1385240ba25 100644 --- a/developer_manual/html_css_design/content.rst +++ b/developer_manual/html_css_design/content.rst @@ -12,39 +12,39 @@ Your application will be directly injected into the ``#content`` div. .. code-block:: html -
-
- -
-
- -
-
-
-
-
- -
-
    - -
-
- -
-
-
-
- -
-
- -
-
- -
-
-
-
+
+
+ +
+
+ +
+
+
+
+
+ +
+
    + +
+
+ +
+
+
+
+ +
+
+ +
+
+ +
+
+
+
Rules and information @@ -57,5 +57,5 @@ Rules and information * Do not use ``#content-wrapper`` anymore * If your app is injecting itself by replacing the #content element, make sure to keep the ``#content`` id * If you use the ``app-content-list`` standard, the ``app-content-details`` div will be hidden in mobile mode (full screen). - You will need to add the ``showdetails`` class to the ``app-content-list`` to show the main content. + You will need to add the ``showdetails`` class to the ``app-content-list`` to show the main content. On mobile view, the whole list/details section (depending on which is shown) will scroll the body diff --git a/developer_manual/html_css_design/css.rst b/developer_manual/html_css_design/css.rst index ab5faf991b8..edafad41784 100644 --- a/developer_manual/html_css_design/css.rst +++ b/developer_manual/html_css_design/css.rst @@ -279,9 +279,9 @@ Dos and Don'ts * - Use physical properties ``margin-left`` - Use logical properties ``margin-inline-start`` - Using logical properties automatically adapts to LTR/RTL - * - Use ``left`` or ``right`` + * - Use ``left`` or ``right`` - Use inset-inline-start/end - - Keep positioning direction-aware + - Keep positioning direction-aware * - Use text-align: left/right - Use text-align: start/end - Text aligns correctly in both modes @@ -292,7 +292,7 @@ Dos and Don'ts - Use float: inline-start/end - Float respects direction * - Assume RTL “just works” - - Test your app with RTL languages + - Test your app with RTL languages - Using the correct css value is not always enough to avoid bugs @@ -305,4 +305,4 @@ Dos and Don'ts - \ No newline at end of file + diff --git a/developer_manual/html_css_design/list.rst b/developer_manual/html_css_design/list.rst index 8c2873f3fef..5e699fa405e 100644 --- a/developer_manual/html_css_design/list.rst +++ b/developer_manual/html_css_design/list.rst @@ -82,7 +82,7 @@ Rules and information * In case of a popovermenu, see the :ref:`popover menu `. * As always, the **JS** is still needed to toggle the ``open`` class on this menu * If you use the ``app-content-list`` standard, the ``app-content-details`` div will be hidden in mobile mode (full screen). - You will need to add the ``showdetails`` class to the ``app-content-list`` to show the main content. + You will need to add the ``showdetails`` class to the ``app-content-list`` to show the main content. On mobile view, the whole list/details section (depending on which is shown) will scroll the body. .. _popovermenulist: diff --git a/developer_manual/prologue/bugtracker/triaging.rst b/developer_manual/prologue/bugtracker/triaging.rst index f6a07b3a45f..f38cb8d5716 100644 --- a/developer_manual/prologue/bugtracker/triaging.rst +++ b/developer_manual/prologue/bugtracker/triaging.rst @@ -92,7 +92,7 @@ If you are unsure, just add a comment: "might be a duplicate of #" When the issue is a feature request, you can be helpful in the same way: merge related requests by adding information of one to the other and closing the first. .. note:: Be polite: when you need to request information or feedback be clear and polite, and you will get more information in less time. Think about how you'd like to be treated, were you to report a bug! -.. note:: You can answer more quickly and friendly using one of `these templates `_. +.. note:: You can answer more quickly and friendly using one of `these templates `_. .. note:: Often our GitHub issue tracker is a place for discussions about solutions. Be friendly, inclusive and respect other people's position. Determining relevance of issue diff --git a/developer_manual/prologue/compatibility_app_ecosystem.rst b/developer_manual/prologue/compatibility_app_ecosystem.rst index ba786a3bea5..d473491ca28 100644 --- a/developer_manual/prologue/compatibility_app_ecosystem.rst +++ b/developer_manual/prologue/compatibility_app_ecosystem.rst @@ -28,8 +28,8 @@ There are three procedures in place to facilitate communication to app developer - The steps should be explicitly written, so the documentation shall not rely upon links to external resources for the steps. While it is encouraged to add an external links as additional reference, it is a hard requirement that the documentation is readable and actionable without browsing to this link. - The change author's name should be added to the section so readers can reach out to the author if they have questions or if something is unclear. - Timeline: the documentation is required to be handed in when finalizing the pull request and should be merged timely close to the actual change. - - + + Other documentation requirements -------------------------------- A change that affects administrators who upgrade their Nextcloud should be documented in the release notes section of the admin documentation of that release. diff --git a/developer_manual/server/architecture/files.rst b/developer_manual/server/architecture/files.rst index 6130c6203be..9fb0533a128 100644 --- a/developer_manual/server/architecture/files.rst +++ b/developer_manual/server/architecture/files.rst @@ -145,4 +145,4 @@ Mimetype management and detection View.php ^^^^^^^^ -Legacy View api \ No newline at end of file +Legacy View api diff --git a/developer_manual/server/code-back-end.rst b/developer_manual/server/code-back-end.rst index 63e979b5c4a..cf85c10789e 100644 --- a/developer_manual/server/code-back-end.rst +++ b/developer_manual/server/code-back-end.rst @@ -7,7 +7,7 @@ When changing back-end PHP code, in general, no additional steps are needed befo However, if new files were created, you will need to run the following command to update the autoloader files: .. code-block:: console - + build/autoloaderchecker.sh After that, please also include the autoloader file changes in your commits. diff --git a/developer_manual/server/code-front-end.rst b/developer_manual/server/code-front-end.rst index d8139f1c66b..889546e7ffb 100644 --- a/developer_manual/server/code-front-end.rst +++ b/developer_manual/server/code-front-end.rst @@ -49,13 +49,13 @@ We still use Handlebars templates in some places in Files and Settings. We will If you don’t have Handlebars installed yet, you can do it with this terminal command: .. code-block:: console - + sudo npm install -g handlebars Then inside the root folder of your local Nextcloud development installation, run this command in the terminal every time you changed a ``.handlebars`` file to compile it: .. code-block:: console - + ./build/compile-handlebars-templates.sh Before checking in JS changes, make sure to also build for production: diff --git a/developer_manual/server/unit-testing.rst b/developer_manual/server/unit-testing.rst index 61231cc53d7..4f934fb5dd4 100644 --- a/developer_manual/server/unit-testing.rst +++ b/developer_manual/server/unit-testing.rst @@ -108,8 +108,8 @@ Every database to test needs to accessible either - Database: oc_autotest - User: oc_autotest - Password: owncloud - -- or via docker by setting the USEDOCKER environment variable. + +- or via docker by setting the USEDOCKER environment variable. Notes on how to setup databases for this test can be found in https://github.com/nextcloud/server/blob/master/autotest.sh. diff --git a/requirements.txt b/requirements.txt index 75a2d874e46..86de5627318 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,7 +9,7 @@ importlib-metadata==8.7.1 Jinja2==3.1.6 MarkupSafe==3.0.3 packaging==24.2 -Pillow==12.1.0 +Pillow==12.2.0 Pygments==2.19.2 PyYAML==6.0.3 reportlab==4.4.7 @@ -27,11 +27,12 @@ sphinxcontrib-htmlhelp==2.1.0 sphinxcontrib-jquery==4.1 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-mermaid==1.2.3 +sphinx-lint==1.0.2 sphinx-notfound-page==1.1.0 sphinxcontrib-phpdomain==0.13.2 sphinxcontrib-qthelp==2.0.0 sphinxcontrib-serializinghtml==2.0.0 sphinx-toolbox==4.1.1 sphinx-reredirects==1.1.0 -urllib3==2.6.3 +urllib3==2.7.0 zipp==3.23.0 diff --git a/user_manual/conf.py b/user_manual/conf.py index 7ff8635dec4..a2df4e2fe76 100644 --- a/user_manual/conf.py +++ b/user_manual/conf.py @@ -6,7 +6,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html # ## Note that additional configuration elements shared by all Nextcloud docs -## are loaded from `../conf.py`. +## are loaded from `../conf.py`. # -- Path setup -------------------------------------------------------------- @@ -31,7 +31,7 @@ 'sphinx.ext.todo', 'rst2pdf.pdfbuilder', 'sphinx.ext.intersphinx', -] +] templates_path = [ '../_shared_assets/templates', diff --git a/user_manual/contents.rst b/user_manual/contents.rst index b47c55abe6b..0781d2f5daa 100644 --- a/user_manual/contents.rst +++ b/user_manual/contents.rst @@ -11,7 +11,7 @@ Table of contents webinterface files/index groupware/index - talk/index + talk/index desktop/index userpreferences universal_access diff --git a/user_manual/desktop/faq.rst b/user_manual/desktop/faq.rst index 9542997afa5..e1823e88970 100644 --- a/user_manual/desktop/faq.rst +++ b/user_manual/desktop/faq.rst @@ -4,11 +4,11 @@ FAQ How the "Edit locally" functionality works ------------------------------------------ -This functionality depends on the desktop client ability to register the nc:// protocol handler. That is the handler used by the server to open a file locally. This will allow the desktop client to open a document with the local editor when you click on the option "Edit locally" in your Nextcloud instance. +This functionality depends on the desktop client ability to register the nc:// protocol handler. That is the handler used by the server to open a file locally. This will allow the desktop client to open a document with the local editor when you click on the option "Edit locally" in your Nextcloud instance. -.. note:: +.. note:: Without properly registering the mime, independent of the browser and distro being used, the desktop client will fail to open a document with the local editor when you click on the option "Edit locally" in your Nextcloud instance. - + The browser will warn you of the failure: "Failed to launch 'nc://...' because the scheme does not have a registered handler." How to enable it @@ -24,7 +24,7 @@ We use AppImage due to its universal compatibility but to take full advantage of On Windows ^^^^^^^^^^ -The MSI installer will alter your system registry to register the nc:// protocol handler. +The MSI installer will alter your system registry to register the nc:// protocol handler. Alternatively, you can manually register the nc:// protocol handler: @@ -33,7 +33,7 @@ Alternatively, you can manually register the nc:// protocol handler: .. code-block:: none Windows Registry Editor Version 5.00 - + [HKEY_CLASSES_ROOT\nc\shell\open\command] @="\"C:\\Program Files\\Nextcloud\\nextcloud.exe\" \"%1\"" diff --git a/user_manual/desktop/installation.rst b/user_manual/desktop/installation.rst index 0d6fc99d4be..e5922684e56 100644 --- a/user_manual/desktop/installation.rst +++ b/user_manual/desktop/installation.rst @@ -11,7 +11,7 @@ at time of publication. It means that the |version| release series is supporting stable server major versions. See https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule for supported major versions. - + Installation on macOS and Windows is the same as for any software application: download the program and then double-click it to launch the installation, and then follow the installation wizard. After it is installed and diff --git a/user_manual/desktop/updatechannel.rst b/user_manual/desktop/updatechannel.rst index fd747767c8f..35eb031e09b 100644 --- a/user_manual/desktop/updatechannel.rst +++ b/user_manual/desktop/updatechannel.rst @@ -2,9 +2,9 @@ Update channels =============== -Whether you want the latest features, want to help with testing, or just want to wait until everything is perfectly ready to go, we’ve got options for you. +Whether you want the latest features, want to help with testing, or just want to wait until everything is perfectly ready to go, we’ve got options for you. -The desktop client has 4 update channels: *Enterprise*, *Stable*, *Beta* and *Daily*. +The desktop client has 4 update channels: *Enterprise*, *Stable*, *Beta* and *Daily*. diff --git a/user_manual/desktop/usage.rst b/user_manual/desktop/usage.rst index a935cea9d1e..594f6082a89 100644 --- a/user_manual/desktop/usage.rst +++ b/user_manual/desktop/usage.rst @@ -186,10 +186,10 @@ Sharing From Your Desktop ------------------------- The Nextcloud desktop sync client integrates with your file manager. Finder on -macOS and Explorer on Windows. Linux users must install an additional package -depending on the used file manager. Available are e.g. ``nautilus-nextcloud`` -(Ubuntu/Debian), ``dolphin-nextcloud`` (Kubuntu), ``nemo-nextcloud`` and -``caja-nextcloud``. You can create share links, and share with internal +macOS and Explorer on Windows. Linux users must install an additional package +depending on the used file manager. Available are e.g. ``nautilus-nextcloud`` +(Ubuntu/Debian), ``dolphin-nextcloud`` (Kubuntu), ``nemo-nextcloud`` and +``caja-nextcloud``. You can create share links, and share with internal Nextcloud users the same way as in your Nextcloud Web interface. In your file explorer, click on a file and in the context menu go to diff --git a/user_manual/external_storage/external_storage.rst b/user_manual/external_storage/external_storage.rst index 64774187a5d..100addf85f3 100644 --- a/user_manual/external_storage/external_storage.rst +++ b/user_manual/external_storage/external_storage.rst @@ -2,9 +2,9 @@ Configuring External Storage ============================ -The External Storage application allows you to mount external storage services, +The External Storage application allows you to mount external storage services, such as Amazon S3, SMB/CIFS file servers and FTP servers… -in Nextcloud. Your Nextcloud server administrator controls which of these are -available to you. Please see `Configuring External Storage (GUI) +in Nextcloud. Your Nextcloud server administrator controls which of these are +available to you. Please see `Configuring External Storage (GUI) `_ in the Nextcloud Administrator's manual for configuration how-tos and examples. diff --git a/user_manual/external_storage/index.rst b/user_manual/external_storage/index.rst index cedd7c89dc3..efe7df1fbbe 100644 --- a/user_manual/external_storage/index.rst +++ b/user_manual/external_storage/index.rst @@ -6,4 +6,4 @@ External Storage :maxdepth: 1 external_storage - + diff --git a/user_manual/files/access_webdav.rst b/user_manual/files/access_webdav.rst index 3a5e4cbee59..8dfbb0ad35f 100644 --- a/user_manual/files/access_webdav.rst +++ b/user_manual/files/access_webdav.rst @@ -108,7 +108,7 @@ share:: :alt: Screenshot of configuring Nautilus file manager to use WebDAV .. note:: The same method works for other file managers that use GVFS, - such as MATE's Caja and Cinnamon's Nemo. + such as MATE's Caja and Cinnamon's Nemo. Accessing files with KDE and Dolphin file manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -488,26 +488,26 @@ To create a folder with the current date as name: .. code-block:: bash - $ curl -u user:pass -X MKCOL "https://example.com/nextcloud/remote.php/dav/files/USERNAME/$(date '+%d-%b-%Y')" + $ curl -u user:pass -X MKCOL "https://example.com/nextcloud/remote.php/dav/files/USERNAME/$(date '+%d-%b-%Y')" To upload a file ``error.log`` into that directory: .. code-block:: bash - $ curl -u user:pass -T error.log "https://example.com/nextcloud/remote.php/dav/files/USERNAME/$(date '+%d-%b-%Y')/error.log" + $ curl -u user:pass -T error.log "https://example.com/nextcloud/remote.php/dav/files/USERNAME/$(date '+%d-%b-%Y')/error.log" To move a file: .. code-block:: bash - $ curl -u user:pass -X MOVE --header 'Destination: https://example.com/nextcloud/remote.php/dav/files/USERNAME/target.jpg' https://example.com/nextcloud/remote.php/dav/files/USERNAME/source.jpg + $ curl -u user:pass -X MOVE --header 'Destination: https://example.com/nextcloud/remote.php/dav/files/USERNAME/target.jpg' https://example.com/nextcloud/remote.php/dav/files/USERNAME/source.jpg To get the properties of files in the root folder: .. code-block:: bash - $ curl -X PROPFIND -H "Depth: 1" -u user:pass https://example.com/nextcloud/remote.php/dav/files/USERNAME/ | xml_pp - + $ curl -X PROPFIND -H "Depth: 1" -u user:pass https://example.com/nextcloud/remote.php/dav/files/USERNAME/ | xml_pp + /nextcloud/remote.php/dav/files/USERNAME/ diff --git a/user_manual/files/desktop_mobile_sync.rst b/user_manual/files/desktop_mobile_sync.rst index eabee18bc05..1df71083c34 100644 --- a/user_manual/files/desktop_mobile_sync.rst +++ b/user_manual/files/desktop_mobile_sync.rst @@ -24,7 +24,7 @@ Mobile clients Visit your Personal page in your Nextcloud Web interface to find download links for Android and iOS mobile sync clients. Or, visit the `Nextcloud download page -`_. +`_. Bidirectional sync (2-way-sync) has not yet been fully implemented in the Android client. See `this issue on GitHub `_ diff --git a/user_manual/files/federated_cloud_sharing.rst b/user_manual/files/federated_cloud_sharing.rst index 74e3f7d9b1f..b263a7de552 100644 --- a/user_manual/files/federated_cloud_sharing.rst +++ b/user_manual/files/federated_cloud_sharing.rst @@ -2,8 +2,8 @@ Using Federation Shares ======================= -Federation Sharing allows you to mount file shares from remote Nextcloud servers, in effect -creating your own cloud of Nextclouds. You can create direct share links with +Federation Sharing allows you to mount file shares from remote Nextcloud servers, in effect +creating your own cloud of Nextclouds. You can create direct share links with users on other Nextcloud servers. Creating a new Federation Share @@ -17,13 +17,13 @@ by default. Follow these steps to create a new share with other Nextcloud or own in this form: ``@``. The form automatically confirms the address that you type and labels it as "remote". Click on the label. - .. figure:: ../images/direct-share-1.png + .. figure:: ../images/direct-share-1.png 2. When your local Nextcloud server makes a successful connection with the remote Nextcloud server you'll see a confirmation. Your only share option is **Can edit**. - -Click the Share button anytime to see who you have shared your file with. Remove -your linked share anytime by clicking the trash can icon. This only unlinks the + +Click the Share button anytime to see who you have shared your file with. Remove +your linked share anytime by clicking the trash can icon. This only unlinks the share, and does not delete any files. Creating a new Federated Cloud Share via email @@ -31,25 +31,25 @@ Creating a new Federated Cloud Share via email Use this method when you are sharing with users on ownCloud 8.x and older. -What if you do not know the username or URL? Then you can have Nextcloud create -the link for you and email it to your recipient. +What if you do not know the username or URL? Then you can have Nextcloud create +the link for you and email it to your recipient. .. figure:: ../images/create_public_share-6.png -When your recipient receives your email they will have to take a number of -steps to complete the share link. First they must open the link you sent them in +When your recipient receives your email they will have to take a number of +steps to complete the share link. First they must open the link you sent them in a Web browser, and then click the **Add to your Nextcloud** button. .. figure:: ../images/create_public_share-8.png -The **Add to your Nextcloud** button changes to a form field, and your recipient +The **Add to your Nextcloud** button changes to a form field, and your recipient needs to enter the URL of their Nextcloud or ownCloud server in this field and press the return key, or click the arrow. .. figure:: ../images/create_public_share-9.png -Next, they will see a dialog asking to confirm. All they have to do is click +Next, they will see a dialog asking to confirm. All they have to do is click the **Add remote share** button and they're finished. - -Remove your linked share anytime by clicking the trash can icon. This only + +Remove your linked share anytime by clicking the trash can icon. This only unlinks the share, and does not delete any files. diff --git a/user_manual/files/transfer_ownership.rst b/user_manual/files/transfer_ownership.rst index 9ec2597bb31..8fe0b72c8e7 100644 --- a/user_manual/files/transfer_ownership.rst +++ b/user_manual/files/transfer_ownership.rst @@ -12,13 +12,13 @@ be transferred to the new owner. #. Pick a new owner by typing their name into the search field next to *New owner*. #. Click on *Transfer*. - .. note:: The username autocompletion or listing may be limited due to administrative visibility configuration. - See `administrator documentation `_ for details. + .. note:: The username autocompletion or listing may be limited due to administrative visibility configuration. + See `administrator documentation `_ for details. #. The target user receives a notification where they are being asked whether to accept or reject the incoming transfer. - .. figure:: ../images/transfer_ownership-accept.png + .. figure:: ../images/transfer_ownership-accept.png #. If accepted, the target user finds the transferred files and folders in their root under a folder *Transferred from [user] on [timestamp]*. diff --git a/user_manual/files/version_control.rst b/user_manual/files/version_control.rst index f71b73cbeb9..b82e0065827 100644 --- a/user_manual/files/version_control.rst +++ b/user_manual/files/version_control.rst @@ -46,4 +46,4 @@ When a version has a name, it will be excluded from the automatic expiration pro Deleting a version ------------------ -You can also manually delete a version without waiting for the automatic expiration process. \ No newline at end of file +You can also manually delete a version without waiting for the automatic expiration process. diff --git a/user_manual/groupware/contacts.rst b/user_manual/groupware/contacts.rst index 4c602e4c1c7..fb77c1fd0ad 100644 --- a/user_manual/groupware/contacts.rst +++ b/user_manual/groupware/contacts.rst @@ -41,13 +41,13 @@ To Import Contacts Using a VCF/vCard File: 1. On top left of the screen you have "Import contacts" button that is shown only when you don't have any contacts yet. 2. Find "Settings" at the bottom of the left sidebar, next to the gear button: - .. figure:: ../images/contact_bottombar.png - :alt: Contact settings gear button + .. figure:: ../images/contact_bottombar.png + :alt: Contact settings gear button 3. Click the gear button. The Contacts app "Import" button will appear: - .. figure:: ../images/contact_uploadbutton.png - :alt: Contacts Upload Field + .. figure:: ../images/contact_uploadbutton.png + :alt: Contacts Upload Field .. note:: The Contacts app only supports import of vCards version 3.0 and 4.0. @@ -98,12 +98,12 @@ Contact Picture To add a picture for your new contacts, click on the upload button: .. figure:: ../images/contact_picture.png - :alt: Contact picture (upload button) + :alt: Contact picture (upload button) After you have set a contact picture, it will look like this: .. figure:: ../images/contact_picture_set.png - :alt: Contact picture (set) + :alt: Contact picture (set) If you want to upload a new one, remove it, view it in full size or download it, click on the contacts picture for the following options to appear: @@ -173,7 +173,7 @@ available address books, certain options for each address book, and enables you to create new address books, simply by specifying an address books name: .. figure:: ../images/contact_manageaddressbook.png - :alt: Add address book in the contacts settings + :alt: Add address book in the contacts settings The Contacts settings is also where you can share, export and delete addressbooks. You will find the CardDAV URLs there. @@ -191,7 +191,7 @@ Informal collaboration takes place within organizations: an event to organize fo For all these reasons, Nextcloud supports Teams, a feature embedded in the Contacts app, where every user is able to create its own team, a user-defined aggregate of accounts. Teams can be used later on to share files and folders, added to Talk conversations, like a regular group. .. figure:: ./images/circle.png - :alt: Teams in the Contacts app left menu + :alt: Teams in the Contacts app left menu Create a team ~~~~~~~~~~~~~ diff --git a/user_manual/groupware/mail.rst b/user_manual/groupware/mail.rst index 8ea7a99b1ca..bc1f4c8c307 100644 --- a/user_manual/groupware/mail.rst +++ b/user_manual/groupware/mail.rst @@ -65,7 +65,7 @@ This setting allows you to show messages set as favorite in a separate section o 1. Visit mail settings 2. Go to *Appearance* -3. Enable sorting favorites up +3. Enable sorting favorites up .. _mail-scheduled-messages: diff --git a/user_manual/groupware/sync_android.rst b/user_manual/groupware/sync_android.rst index 5c87a1eae54..592f872f8fb 100644 --- a/user_manual/groupware/sync_android.rst +++ b/user_manual/groupware/sync_android.rst @@ -5,7 +5,7 @@ Synchronizing with Android Files and notifications ----------------------- -1. Install the Nextcloud Android client `from Google Play Store `__ or +1. Install the Nextcloud Android client `from Google Play Store `__ or `from F-Droid `__. 2. Start the app. There are two ways of setting it up: @@ -25,8 +25,8 @@ Contacts and Calendar With the Nextcloud mobile app ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. Install `DAVx⁵ (formerly known as DAVDroid) `_ on your Android device, - `from Google Play Store `__ or +1. Install `DAVx⁵ (formerly known as DAVDroid) `_ on your Android device, + `from Google Play Store `__ or `from F-Droid `__. 2. In the Nextcloud mobile, go to **Settings**/**More**, tap on "**Sync calendars & contacts**". @@ -49,8 +49,8 @@ Without the Nextcloud mobile app If you do not want to install the Nextcloud mobile app, the following steps are required: -1. Install `DAVx⁵ (formerly known as DAVDroid) `_ on your Android device, - `from Google Play Store `__ or +1. Install `DAVx⁵ (formerly known as DAVDroid) `_ on your Android device, + `from Google Play Store `__ or `from F-Droid `__. 2. Optionally install OpenTasks (`Google Play Store `__ or `F-Droid `__). diff --git a/user_manual/groupware/sync_ios.rst b/user_manual/groupware/sync_ios.rst index 24a80933fb8..c89348ee4fa 100644 --- a/user_manual/groupware/sync_ios.rst +++ b/user_manual/groupware/sync_ios.rst @@ -25,7 +25,7 @@ Your calendar will now be visible in the Calendar application. either specify both the protocol (``https://``) and the port (usually ``443``) in the ``Server`` field, i.e., ``https://example.com:443/remote.php/dav/principals/users/username/``, or none, like in the step-by-step guide above. Either way, the application automatically tries to use SSL, - which you can confirm in “Advanced Settings” of the account after saving. + which you can confirm in “Advanced Settings” of the account after saving. .. note:: Beginning with iOS 12 an SSL encryption is necessary. Therefore do **not** disable **SSL** (For this reason a certificate is required at your domain, https://letsencrypt.org/ will do). diff --git a/user_manual/groupware/sync_osx.rst b/user_manual/groupware/sync_osx.rst index f090c33abcc..9f378b7605f 100644 --- a/user_manual/groupware/sync_osx.rst +++ b/user_manual/groupware/sync_osx.rst @@ -22,7 +22,7 @@ At the time of writing this guide, macOS is at version 26.3.1. .. figure:: ./images/macos_3.png -4. Click on **add Other Account...** +4. Click on **add Other Account...** .. figure:: ./images/macos_4.png diff --git a/user_manual/groupware/sync_windows10.rst b/user_manual/groupware/sync_windows10.rst index f3f0f6ea16f..7bbb9f41023 100644 --- a/user_manual/groupware/sync_windows10.rst +++ b/user_manual/groupware/sync_windows10.rst @@ -46,12 +46,10 @@ Troubleshooting: 2FA Troubleshooting: TLSv1.2 ------------------------ -- For Windows 10 your Nextcloud https server `must support TLSv1.2`_. This is apparent if no connection attempts are seen on the server, and the Windows client Event Viewer will display Schannel TLS errors under "Windows Logs -> System". +- For Windows 10 your Nextcloud https server `must support TLSv1.2 `_. This is apparent if no connection attempts are seen on the server, and the Windows client Event Viewer will display Schannel TLS errors under "Windows Logs -> System". Credits ------- Special thanks to this Reddit user for their post: https://www.reddit.com/r/Nextcloud/comments/5rcypb/using_the_windows_10_calendar_application_with/ - -.. _must support TLSv1.2: https://docs.microsoft.com/en-us/windows/win32/secauthn/protocols-in-tls-ssl--schannel-ssp- diff --git a/user_manual/talk/advanced_features.rst b/user_manual/talk/advanced_features.rst index 6481947cded..891d0fa7c52 100644 --- a/user_manual/talk/advanced_features.rst +++ b/user_manual/talk/advanced_features.rst @@ -306,4 +306,4 @@ When enabled, the transcription will appear in the bottom and will be updated in With `live_transcription` provider app enabled, you can also use live translation. Instead of receiving the transcription in the original message, it will be translated to the language of your choice. .. image:: images/call-translation-actions.png - :width: 400px \ No newline at end of file + :width: 400px diff --git a/user_manual/talk/talk_basics.rst b/user_manual/talk/talk_basics.rst index a0d66369448..90f659bb44b 100644 --- a/user_manual/talk/talk_basics.rst +++ b/user_manual/talk/talk_basics.rst @@ -287,7 +287,7 @@ Closing poll is possible from the poll dialog. .. image:: images/close-poll.png :width: 400px -As a moderator, you can create the poll directly or you can save it as a draft to edit it later. +As a moderator, you can create the poll directly or you can save it as a draft to edit it later. .. image:: images/save-poll-draft.png :width: 400px @@ -464,7 +464,7 @@ You can zoom in and out of the shared screen with mouse wheel, double click or t Changing view in a call ----------------------- -You can switch the view in a call in the bottom bar between promoted view and grid view. +You can switch the view in a call in the bottom bar between promoted view and grid view. .. image:: images/call-view-toggle-button.png :width: 300px @@ -501,7 +501,7 @@ Appearance Compact view of conversations list ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Compact view allows to hide last message preview in the conversation list, providing a more focused interface. +Compact view allows to hide last message preview in the conversation list, providing a more focused interface. .. image:: images/talk-compact-view.png :width: 200px @@ -562,4 +562,4 @@ Subscribed threads are easily accessible from the navigation bar in ``Threads`` Editing thread title is possible from the thread itself or from the sidebars. .. image:: images/thread-edit-title.png - :width: 500px \ No newline at end of file + :width: 500px diff --git a/user_manual/user_2fa.rst b/user_manual/user_2fa.rst index 92bc822ef28..1a670315d30 100644 --- a/user_manual/user_2fa.rst +++ b/user_manual/user_2fa.rst @@ -4,7 +4,7 @@ Using two-factor authentication Two-factor authentication (2FA) is a way to protect your Nextcloud account against unauthorized access. It works by requiring two different 'proofs' of -your identity. For example, *something you know* (like a password) and +your identity. For example, *something you know* (like a password) and *something you have* like a physical key. Typically, the first factor is a password like you already have and the second can be a text message you receive or a code you generate on your phone or another device @@ -42,7 +42,7 @@ Auth settings. Choose *Generate backup codes*: :alt: 2FA backup code generator You will then be presented with a list of one-time-use backup codes: - + .. figure:: images/2fa_backupcode_2.png :alt: 2FA backup codes @@ -92,7 +92,7 @@ Using client applications with two-factor authentication Once you have enabled 2FA, your clients will no longer be able to connect with just your password unless they also have support for two-factor authentication. -To solve this, you should generate device specific passwords for them. See +To solve this, you should generate device specific passwords for them. See :doc:`session_management` for more information on how to do this. diff --git a/user_manual/userpreferences.rst b/user_manual/userpreferences.rst index 77e348abf1f..77e3fa8f3ab 100644 --- a/user_manual/userpreferences.rst +++ b/user_manual/userpreferences.rst @@ -49,7 +49,7 @@ include the following: Sharing your data in the global address book ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Some administrators decide to share their global address book with other Nextcloud instances (so called *Trusted Servers*) or even with the wider world. +Some administrators decide to share their global address book with other Nextcloud instances (so called *Trusted Servers*) or even with the wider world. This is helpful when two instances want to work closely together, or when people want to use Nextcloud as a virtual telephone book for others to browse. It also allows searching for contacts, creating shares and much more. @@ -66,7 +66,7 @@ If you set your data to **Local**, all logged in users within your Nextcloud ins If you set your data to **Federated**, the trusted server(s) which are added by your administrator will be able to see this data, in addition to all logged in users. -If you set your data to **Published**, anyone can see your data. For some use cases this is wanted. +If you set your data to **Published**, anyone can see your data. For some use cases this is wanted. Someone with a public facing role such as marketing or sales might want to share their contact with a wide variety of connections which might not be using Nextcloud.