diff --git a/.codespellignore b/.codespellignore new file mode 100644 index 000000000..ab827362e --- /dev/null +++ b/.codespellignore @@ -0,0 +1,4 @@ +SME +te +jus +nin diff --git a/.codespellrc b/.codespellrc new file mode 100644 index 000000000..903bfe4a1 --- /dev/null +++ b/.codespellrc @@ -0,0 +1,4 @@ +[codespell] +skip = ./build/*,**/_build/*,*.pot,conf.py,./static/*,./admin_manual/configuration_server/config_sample_php_parameters.rst,./_shared_assets/*,./COPYING +ignore-words = .codespellignore +check-filenames = true diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index fa1bf09ad..ac032fe5e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,12 +1,10 @@ -/*/groupware/ @ChristophWurst -/*/groupware/calendar.rst @miaulalala -/*/groupware/contacts.rst @hamza221 -/*/groupware/mail.rst @GretaD +/*/groupware/calendar.rst @SebastianKrupinski @st3iny @tcitworld +/*/groupware/contacts.rst @GVodyanov @hamza221 @SebastianKrupinski +/*/groupware/mail.rst @ChristophWurst @GretaD @kesselb /*/security.rst @nickvergessen /admin_manual/configuration_database @nickvergessen /admin_manual/file_workflows @nickvergessen /developer_manual/client_apis/OCS/ocs-status-api.rst @Antreesy @nickvergessen -/developer_manual/digging_deeper/groupware/ @ChristophWurst -/developer_manual/digging_deeper/groupware/calendar.rst @miaulalala +/developer_manual/digging_deeper/groupware/calendar.rst @SebastianKrupinski @st3iny @tcitworld /developer_manual/digging_deeper/talk.rst @nickvergessen /user_manual/talk/ @Antreesy @DorraJaouad @nickvergessen diff --git a/.github/workflows/block-merge-freeze.yml b/.github/workflows/block-merge-freeze.yml index 2e4b3e25d..bbbe1ab0d 100644 --- a/.github/workflows/block-merge-freeze.yml +++ b/.github/workflows/block-merge-freeze.yml @@ -2,6 +2,9 @@ # # https://github.com/nextcloud/.github # https://docs.github.com/en/actions/learn-github-actions/sharing-workflows-with-your-organization +# +# SPDX-FileCopyrightText: 2022-2024 Nextcloud GmbH and Nextcloud contributors +# SPDX-License-Identifier: MIT name: Block merges during freezes @@ -27,10 +30,10 @@ jobs: steps: - name: Register server reference to fallback to master branch run: | - server_ref="$(if [ "${{ github.base_ref }}" = "main" ]; then echo -n "master"; else echo -n "${{ github.base_ref }}"; fi)" + server_ref="$(if [ '${{ github.base_ref }}' = 'main' ]; then echo -n 'master'; else echo -n '${{ github.base_ref }}'; fi)" echo "server_ref=$server_ref" >> $GITHUB_ENV - name: Download version.php from ${{ env.server_ref }} - run: curl https://raw.githubusercontent.com/nextcloud/server/${{ env.server_ref }}/version.php --output version.php + run: curl 'https://raw.githubusercontent.com/nextcloud/server/${{ env.server_ref }}/version.php' --output version.php - name: Run check run: cat version.php | grep 'OC_VersionString' | grep -i -v 'RC' diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml new file mode 100644 index 000000000..afe308a87 --- /dev/null +++ b/.github/workflows/codespell.yml @@ -0,0 +1,22 @@ +name: 'Codespell' + +on: + pull_request: + push: + branches: + - master + +jobs: + codespell: + name: Check spelling + runs-on: self-hosted + steps: + - name: Check out code + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + persist-credentials: false + + - name: Check spelling + uses: codespell-project/actions-codespell@406322ec52dd7b488e48c1c4b82e2a8b3a1bf630 # v2.1 + with: + skip: '**.svg, **.js' diff --git a/.github/workflows/command-rebase.yml b/.github/workflows/command-rebase.yml deleted file mode 100644 index ffd39d43a..000000000 --- a/.github/workflows/command-rebase.yml +++ /dev/null @@ -1,51 +0,0 @@ -# This workflow is provided via the organization template repository -# -# https://github.com/nextcloud/.github -# https://docs.github.com/en/actions/learn-github-actions/sharing-workflows-with-your-organization - -name: Rebase command - -on: - issue_comment: - types: created - -permissions: - contents: read - -jobs: - rebase: - runs-on: ubuntu-latest - permissions: - contents: none - - # On pull requests and if the comment starts with `/rebase` - if: github.event.issue.pull_request != '' && startsWith(github.event.comment.body, '/rebase') - - steps: - - name: Add reaction on start - uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0 - with: - token: ${{ secrets.COMMAND_BOT_PAT }} - repository: ${{ github.event.repository.full_name }} - comment-id: ${{ github.event.comment.id }} - reaction-type: "+1" - - - name: Checkout the latest code - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6 - with: - fetch-depth: 0 - token: ${{ secrets.COMMAND_BOT_PAT }} - - - name: Automatic Rebase - uses: cirrus-actions/rebase@b87d48154a87a85666003575337e27b8cd65f691 # 1.8 - env: - GITHUB_TOKEN: ${{ secrets.COMMAND_BOT_PAT }} - - - name: Add reaction on failure - uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0 - if: failure() - with: - token: ${{ secrets.COMMAND_BOT_PAT }} - repository: ${{ github.event.repository.full_name }} - comment-id: ${{ github.event.comment.id }} - reaction-type: "-1" diff --git a/.github/workflows/fixup.yml b/.github/workflows/fixup.yml index 98d49927a..69da2bbb0 100644 --- a/.github/workflows/fixup.yml +++ b/.github/workflows/fixup.yml @@ -2,6 +2,9 @@ # # https://github.com/nextcloud/.github # https://docs.github.com/en/actions/learn-github-actions/sharing-workflows-with-your-organization +# +# SPDX-FileCopyrightText: 2021-2024 Nextcloud GmbH and Nextcloud contributors +# SPDX-License-Identifier: MIT name: Block fixup and squash commits @@ -28,6 +31,6 @@ jobs: steps: - name: Run check - uses: skjnldsv/block-fixup-merge-action@42d26e1b536ce61e5cf467d65fb76caf4aa85acf # v1 + uses: skjnldsv/block-fixup-merge-action@c138ea99e45e186567b64cf065ce90f7158c236a # v2 with: repo-token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/generate_catalog_templates.yml b/.github/workflows/generate_catalog_templates.yml index 9d9d48209..5312210b8 100644 --- a/.github/workflows/generate_catalog_templates.yml +++ b/.github/workflows/generate_catalog_templates.yml @@ -12,30 +12,45 @@ jobs: user_manual: runs-on: ubuntu-latest steps: - - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + persist-credentials: false - - uses: ammaraskar/sphinx-action@master + - uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0 + with: + python-version: '3.13' + + - uses: ammaraskar/sphinx-action@54e52bfb642e9b60ea5b6bcb05fe3f74b40d290a # v8.2.3 with: docs-folder: "user_manual/" - pre-build-command: pip install -r requirements.txt - build-command: make gettext + pre-build-command: "pip install -r requirements.txt" + build-command: "make gettext" - - uses: peter-evans/create-pull-request@v6 + - name: Change file owner to correct user + run: | + ls -la user_manual/locale/source + sudo chown -R 1001:1001 user_manual/locale/source + ls -la user_manual/locale/source + + - uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8 id: cpr with: token: ${{ secrets.COMMAND_BOT_PAT }} - commit-message: "chore(l10n): Updates catalog templates (POT files fetched automatically by transifex)" - title: Updates catalog templates - branch: update-l10n + commit-message: 'chore(l10n): Updates catalog templates (POT files fetched automatically by transifex)' + committer: GitHub + author: nextcloud-command signoff: true + branch: 'automated/noid/update-l10n' + title: 'Updates catalog templates' - - uses: hmarr/auto-approve-action@v4.0.0 + - uses: hmarr/auto-approve-action@f0939ea97e9205ef24d872e76833fa908a770363 # v4.0.0 if: steps.cpr.outputs.pull-request-operation == 'created' with: github-token: "${{ secrets.GITHUB_TOKEN }}" pull-request-number: ${{ steps.cpr.outputs.pull-request-number }} - - uses: pascalgn/automerge-action@v0.16.3 + - uses: pascalgn/automerge-action@7961b8b5eec56cc088c140b56d864285eabd3f67 # v0.16.4 if: steps.cpr.outputs.pull-request-operation == 'created' env: GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" diff --git a/.github/workflows/openapi.yml b/.github/workflows/openapi.yml index 83c7440a0..2995eeb1b 100644 --- a/.github/workflows/openapi.yml +++ b/.github/workflows/openapi.yml @@ -15,12 +15,12 @@ jobs: steps: - name: Checkout - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6 + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: submodules: true - name: Set up php - uses: shivammathur/setup-php@c665c7a15b5295c2488ac8a87af9cb806cd72198 # v2 + uses: shivammathur/setup-php@9e72090525849c5e82e596468b86eb55e9cc5401 # v2 with: php-version: '8.1' # https://docs.nextcloud.com/server/stable/admin_manual/installation/source_installation.html#prerequisites-for-manual-installation diff --git a/.github/workflows/pr-feedback.yml b/.github/workflows/pr-feedback.yml index be0d028f9..cda794806 100644 --- a/.github/workflows/pr-feedback.yml +++ b/.github/workflows/pr-feedback.yml @@ -17,10 +17,11 @@ on: jobs: pr-feedback: + if: ${{ github.repository_owner == 'nextcloud' }} runs-on: ubuntu-latest steps: - name: The get-github-handles-from-website action - uses: marcelklehr/get-github-handles-from-website-action@a739600f6b91da4957f51db0792697afbb2f143c # v1.0.0 + uses: marcelklehr/get-github-handles-from-website-action@06b2239db0a48fe1484ba0bfd966a3ab81a08308 # v1.0.1 id: scrape with: website: 'https://nextcloud.com/team/' @@ -35,7 +36,7 @@ jobs: with: feedback-message: | Hello there, - Thank you so much for taking the time and effort to create a pull request to our Nextcloud project. + Thank you so much for taking the time and effort to create a pull request to our Nextcloud project. We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process. @@ -45,6 +46,6 @@ jobs: (If you believe you should not receive this message, you can add yourself to the [blocklist](https://github.com/nextcloud/.github/blob/master/non-community-usernames.txt).) days-before-feedback: 14 - start-date: "2024-04-30" - exempt-authors: "${{ steps.blocklist.outputs.blocklist }},${{ steps.scrape.outputs.users }},nextcloud-command,nextcloud-android-bot" + start-date: '2024-04-30' + exempt-authors: '${{ steps.blocklist.outputs.blocklist }},${{ steps.scrape.outputs.users }}' exempt-bots: true diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index 38da0a211..16eb196c0 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -11,7 +11,7 @@ jobs: user_manual: runs-on: ubuntu-latest steps: - - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 - uses: actions/setup-python@v5 with: python-version: '3.10' @@ -23,7 +23,7 @@ jobs: shell: bash run: tar czf /tmp/documentation.tar.gz -C user_manual/_build/html . - name: Upload static documentation - uses: actions/upload-artifact@v4.3.3 + uses: actions/upload-artifact@v4.6.1 with: name: User manual.zip path: "/tmp/documentation.tar.gz" @@ -31,7 +31,7 @@ jobs: user_manual-en: runs-on: ubuntu-latest steps: - - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 - uses: actions/setup-python@v5 with: python-version: '3.10' @@ -43,7 +43,7 @@ jobs: developer_manual: runs-on: ubuntu-latest steps: - - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 - uses: actions/setup-python@v5 with: python-version: '3.10' @@ -55,7 +55,7 @@ jobs: shell: bash run: tar czf /tmp/documentation.tar.gz -C developer_manual/_build/html/com . - name: Upload static documentation - uses: actions/upload-artifact@v4.3.3 + uses: actions/upload-artifact@v4.6.1 with: name: Developer manual.zip path: "/tmp/documentation.tar.gz" @@ -63,7 +63,7 @@ jobs: admin_manual: runs-on: ubuntu-latest steps: - - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 - uses: actions/setup-python@v5 with: python-version: '3.10' @@ -75,7 +75,7 @@ jobs: shell: bash run: tar czf /tmp/documentation.tar.gz -C admin_manual/_build/html/com . - name: Upload static documentation - uses: actions/upload-artifact@v4.3.3 + uses: actions/upload-artifact@v4.6.1 with: name: Administration manual.zip path: "/tmp/documentation.tar.gz" diff --git a/.github/workflows/transifex.yml b/.github/workflows/transifex.yml index 779a378b1..4652f7ed1 100644 --- a/.github/workflows/transifex.yml +++ b/.github/workflows/transifex.yml @@ -17,7 +17,7 @@ jobs: name: Auto-merge needs: approve steps: - - uses: pascalgn/automerge-action@v0.16.3 + - uses: pascalgn/automerge-action@v0.16.4 if: github.actor == 'transifex-integration[bot]' env: GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" diff --git a/Makefile b/Makefile index 65ee0167d..d532a2fc4 100644 --- a/Makefile +++ b/Makefile @@ -42,4 +42,4 @@ openapi-spec: get-server-sources clean: - rm -r admin_manual/_build developer_manual/_build user_manual/_build user_manual_de_/_build + rm -vrf admin_manual/_build developer_manual/_build user_manual/_build user_manual_de_/_build diff --git a/README.rst b/README.rst index 266cd41b2..33d85ed94 100644 --- a/README.rst +++ b/README.rst @@ -170,7 +170,7 @@ Using the VSCode DevContainer This repository contains a full-featured `VSCode DevContainer `_. You can use it in your local development environment or via `GitHub Codespaces `_. Just open the container an use one of the commands from above to build the project. For example ``make`` to build the full -documentaion, ``make html`` to build the HTML documentaion or ``make pdf`` to build the PDF documentation. You can also use +documentation, ``make html`` to build the HTML documentation or ``make pdf`` to build the PDF documentation. You can also use ``make SPHINXBUILD=sphinx-autobuild html`` in combination with `port forwarding `_ to watch file changes and automatically reload the html preview. diff --git a/_shared_assets/static/custom.css b/_shared_assets/static/custom.css index 7c316f3fe..5bce5d73e 100644 --- a/_shared_assets/static/custom.css +++ b/_shared_assets/static/custom.css @@ -92,4 +92,20 @@ div#list-of-available-icons > blockquote > div > div > p { font-size: 90%; font-style: normal; text-align: center; +} + +.wy-nav-content { + max-width: clamp(800px, calc(100vw - 600px), 1200px) !important; +} + +.wy-nav-content section { + max-width: 900px; +} + +table.docutils { + min-width: 50%; +} + +#code-style table.docutils { + width: 100%; } \ No newline at end of file diff --git a/admin_manual/Makefile b/admin_manual/Makefile index 805a74fa1..60552782b 100644 --- a/admin_manual/Makefile +++ b/admin_manual/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line. SPHINXOPTS += -SPHINXBUILD = sphinx-build +SPHINXBUILD = buf_size=1000000 sphinx-build PAPER = BUILDDIR = _build @@ -115,7 +115,7 @@ latex: latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf + buf_size=10000000 $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." pdf: diff --git a/admin_manual/_templates/versions.html b/admin_manual/_templates/versions.html new file mode 100644 index 000000000..e8a3a5a13 --- /dev/null +++ b/admin_manual/_templates/versions.html @@ -0,0 +1,18 @@ +{% if READTHEDOCS %} +{# Add rst-badge after rst-versions for small badge style. #} +
+ + Read the Docs + v: {{ current_version }} + + +
+
+
{{ _('Versions') }}
+ {% for slug, url in versions %} +
{{ slug }}
+ {% endfor %} +
+
+
+{% endif %} \ No newline at end of file diff --git a/admin_manual/ai/ai_as_a_service.rst b/admin_manual/ai/ai_as_a_service.rst index 14c75acfb..8633eda78 100644 --- a/admin_manual/ai/ai_as_a_service.rst +++ b/admin_manual/ai/ai_as_a_service.rst @@ -4,15 +4,36 @@ AI as a Service .. _ai-ai_as_a_service: -At Nextcloud we focus on creating on-premise AI apps that run fully self-hosted on your own servers in order to preserve your privacy and data sovereignty. However, you can also offload these resource-heavy tasks to an "AI as a Service" provider offering API access in exchange for payment. Examples of such providers are `OpenAI `_, with its ChatGPT APIs providing language model access among other APIs as well as `replicate `_. +At Nextcloud we focus on creating on-premise AI apps that run fully self-hosted on your own servers in order to preserve your privacy and data sovereignty. +However, you can also offload these resource-heavy tasks to an "AI as a Service" provider offering API access in exchange for payment. +Examples of such providers are `OpenAI `_, with its ChatGPT APIs providing language model access +among other APIs as well as `Replicate `_. Installation ------------ In order to use these providers you will need to install the respective app from the app store: -* ``integration_openai`` (With this application, you can also connect to a self-hosted LocalAI instance or to any service that implements an API similar to OpenAI, for example Plusserver or MistralAI.) +* ``integration_openai`` * ``integration_replicate`` You can then add your API token and rate limits in the administration settings and set the providers live in the "Artificial intelligence" section of the admins settings. + +Optionally but recommended, setup background workers for faster pickup of tasks. See :ref:`the relevant section in AI Overview` for more information. + +OpenAI integration +------------------ + +With this application, you can also connect to a self-hosted LocalAI or Ollama instance or to any service that implements an API similar enough to the OpenAI API, +for example `IONOS AI Model Hub `_, +`Plusserver `_, `Groqcloud `_, `MistralAI `_ or `Together AI `_. + +Do note however, that we test the Assistant tasks that this app implements only with OpenAI models and only against the OpenAI API, we thus cannot guarantee other models and APIs will work. +Some APIs claiming to be compatible with OpenAI might not be fully compatible so we cannot guarantee that they will work with this app. + + +Improve performance +------------------- + +Prompts from integration_openai and integration_replicate can have a delay of 5 minutes. This can be optimized and more information can be found in :ref:`the relevant section in AI Overview `. diff --git a/admin_manual/ai/app_api_and_external_apps.rst b/admin_manual/ai/app_api_and_external_apps.rst deleted file mode 100644 index 34f2bee2b..000000000 --- a/admin_manual/ai/app_api_and_external_apps.rst +++ /dev/null @@ -1,36 +0,0 @@ -======================== -AppAPI and External Apps -======================== - -.. _ai-app_api: - -Previously, Nextcloud only supported applications written in the PHP programming language. In order to support a wider range of use cases, -the External App ecosystem was introduced, which allows installing apps that are docker containers. - -Most of our AI apps nowadays are ExApps (External Apps) and thus require some preparation of your Nextcloud before you can install them. - -Installation ------------- - -1. You will need to install the `AppAPI `_ Nextcloud app from the app store. -2. You will need to set up a Deploy Daemon in the AppAPI admin settings. A Deploy Daemon is a way for Nextcloud to install and communicate with and control External Apps. - - 1. You will need to `setup a docker container called docker-socket-proxy that proxies access to docker for your Nextcloud instance `_ - 2. Now you can connect your Nextcloud to the docker-socket-proxy by entering its details in the Deploy Daemon creation form in the AppAPI settings. - 3. Make sure to enable GPU support if you want the installed ExApps to be able to use the GPU - -3. You can now install ExApps from the Nextcloud Appstore by clicking "Install" on the respective app in the AppAPI apps page. - -FAQ ---- - -* I have two graphic cards XXX with 6/8/Y GB of ram each, how can I run something what does not fit in one graphic card? - * Distributing models across multiple GPUs is currently not supported. You will need a GPU that fits all of the model you are trying to use. -* I have YYY graphic card that does not supports CUDA - can I use it and how? - * No, our AI apps require GPUs with CUDA support to function -* What is the minimum VRAM size requirement for a GPU if I want to install multiple apps? - * When running multiple ExApps on the same GPU, it is currently required that the GPU can hold the largest model of the apps you install -* Is it possible to add more graphics cards for my instance to enable parallel requests or to speed up one request? - * Parallel processing of AI workloads of the same app with multiple GPUs is currently not supported -* Can I use in parallel CPU and GPU for AI processing? - * No, you can only process AI workloads for one app either on CPU or GPU. Between apps you can decide which app you want to run on CPU or GPU. diff --git a/admin_manual/ai/app_assistant.rst b/admin_manual/ai/app_assistant.rst index 1dea486b5..a52efefcc 100644 --- a/admin_manual/ai/app_assistant.rst +++ b/admin_manual/ai/app_assistant.rst @@ -6,7 +6,7 @@ Nextcloud Assistant Nextcloud assistant is the primary graphical user interface for interacting with artificial intelligence features in Nextcloud. -It offers the graphical user interface for text processing tasks like summarizing text, generating headlines, and asking arbitrary questions, for Speech-To-Text transcription of media files, for Text-To-Image picture generation and it integrates with the context_chat app to offer in-context answers about your own data stored in Nextcloud. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. +It offers the graphical user interface for the unified AI Task processing API offering features like summarizing text, generating headlines, asking arbitrary questions, transcription of media files, image generation and it integrates with the context_chat app to offer in-context answers about your own data stored in Nextcloud. The assistant app also offers a chat interface to interact with the chosen language model. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. Find the user documentation here: ``_ @@ -36,16 +36,20 @@ Related apps Artificial intelligence at Nextcloud is built in a modular way, allowing you to choose from a variety of solutions for your needs. In order to make use of the various features of the Assistant you will need additional apps that act as backends to provide the actual implementation of the AI functionality. In the Nextcloud administration settings under "Artificial intelligence" you can select which AI backend app to use for which tasks. Note that some of the backend apps are only community maintained, while others are available for Customer support upon request. +The AI admin settings will show all types of Assistant Tasks that are implemented by all your installed apps. Task types can be disabled in the AI admin settings so they are not available for the Assistant or other apps even if they are implemented. All implemented Task types are enabled by default. + **Note**: At Nextcloud we focus on creating on-premise AI apps that run fully self-hosted on your own servers in order to preserve your privacy and data sovereignty. However, you can also offload these resource-heavy tasks to an :ref:`"AI as a Service" provider`. +**Note**: When using our on-premise AI apps, make sure you have a GPU with enough VRAM that fits all the features you need. For each app documented here you will find its hardware requirements. + +.. _machine_translation: + Machine translation ~~~~~~~~~~~~~~~~~~~ In order to make use of machine translation features in the assistant, you will need an app that provides a translation backend: - -* :ref:`translate` - Runs open source AI translation models locally on your own server hardware (Customer support available upon request) +* :ref:`translate2 (ExApp)` - Runs open source AI translation models locally on your own server hardware (Customer support available upon request) * *integration_deepl* - Integrates with the deepl API to provide translation functionality from Deepl.com servers (Only community supported) -* *integration_libretranslate* - Integrates with the open source LibreTranslate API to provide translation functionality hosted commercially or on your own hardware (Only community supported) Speech-To-Text ~~~~~~~~~~~~~~ @@ -63,12 +67,26 @@ In order to make use of text processing features in the assistant, you will need * :ref:`llm2` - Runs open source AI language models locally on your own server hardware (Customer support available upon request) * *integration_openai* - Integrates with the OpenAI API to provide AI functionality from OpenAI servers (Customer support available upon request; see :ref:`AI as a Service`) +These apps currently implement the following Assistant Tasks: + +* *Generate text* (Tested with OpenAI GPT-3.5 and Llama 3.1 8B) +* *Summarize* (Tested with OpenAI GPT-3.5 and Llama 3.1 8B) +* *Generate headline* (Tested with OpenAI GPT-3.5 and Llama 3.1 8B) +* *Extract topics* (Tested with OpenAI GPT-3.5 and Llama 3.1 8B) + +Additionally, *integration_openai* also implements the following Assistant Tasks: + +* *Context write* (Tested with OpenAI GPT-3.5) +* *Reformulate text* (Tested with OpenAI GPT-3.5) + +These tasks may work with other models, but we can give no guarantees. + Text-To-Image ~~~~~~~~~~~~~ In order to make use of Text-To-Image features, you will need an app that provides an image generation backend: -* text2image_stablediffusion2 (Customer support available upon request) +* :ref:`tex2image_stablediffusion2` (Customer support available upon request) * *integration_openai* - Integrates with the OpenAI API to provide AI functionality from OpenAI servers (Customer support available upon request; see :ref:`AI as a Service`) * *integration_replicate* - Integrates with the replicate API to provide AI functionality from replicate servers (see :ref:`AI as a Service`) @@ -79,6 +97,18 @@ In order to make use of our special Context Chat feature, offering in-context in * :ref:`context_chat + context_chat_backend` - (Customer support available upon request) +You will also need a text processing provider as specified above (ie. llm2 or integration_openai). + +Context Agent +~~~~~~~~~~~~~ + +In order to make use of our AI agent feature, offering the execution of actions on behalf of the user based on the AI chat, you will need the following apps: + + +* :ref:`context_agent` - (Customer support available upon request) + + +You will also need a text processing provider as specified above (ie. *llm2* or *integration_openai*). Configuration ------------- @@ -94,7 +124,7 @@ Assistant configuration .. code-block:: - occ config:app:set assistant assistant_enabled --value=1 --type=integer + occ config:app:set assistant assistant_enabled --value=1 --type=string To enable/disable the assistant button from the top-right corner for all the users. @@ -102,7 +132,7 @@ To enable/disable the assistant button from the top-right corner for all the use .. code-block:: - occ config:app:set assistant free_prompt_picker_enabled --value=1 --type=integer + occ config:app:set assistant free_prompt_picker_enabled --value=1 --type=string To enable/disable the AI text generation smart picker for all the users. @@ -110,7 +140,7 @@ To enable/disable the AI text generation smart picker for all the users. .. code-block:: - occ config:app:set assistant text_to_image_picker_enabled --value=1 --type=integer + occ config:app:set assistant text_to_image_picker_enabled --value=1 --type=string To enable/disable the text-to-image smart picker for all the users. @@ -118,10 +148,45 @@ To enable/disable the text-to-image smart picker for all the users. .. code-block:: - occ config:app:set assistant speech_to_text_picker_enabled --value=1 --type=integer + occ config:app:set assistant speech_to_text_picker_enabled --value=1 --type=string To enable/disable the speech-to-text smart picker for all the users. +Task processing +~~~~~~~~~~~~~~~ + +1. List Tasks + +.. code-block:: + + occ taskprocessing:task:list + +lists all task processing tasks. + +2. Get Task + +.. code-block:: + + occ taskprocessing:task:get $TASK_ID + +shows all information for a specific task. + +3. Enable or disable a Task type + +.. code-block:: + + occ taskprocessing:task-type:set-enabled $TASK_TYPE_ID 1 + +Set 1 to enable and 0 to disable an implemented task type. + +4. Get Task statistics + +.. code-block:: + + occ taskprocessing:task:stats + +shows statistics for all task processing Tasks. + Image storage ~~~~~~~~~~~~~ @@ -142,6 +207,8 @@ Chat with AI The user instructions that are prepended before the chat messages for the AI model to understand the context of the block of text. This is a good place not only to instruct the AI model to be polite and kind but also to for example answer all the queries in a particular language or better yet, follow the user's language. The sky is the limit. +**Note**: The default instructions are optimized to work well across a variety of language models, but may not be optimal for the specific model you choose. Specifically, the model may be tempted to mention the user's name a bit too often and may mention the user's language in an unusual manner. + 2. Chat User Instructions for Title Generation .. code-block:: @@ -158,3 +225,8 @@ This field is appended to the block of chat messages, i.e. attached after the me The number of latest messages to consider for generating the next message. This does not include the user instructions, which is always considered in addition to this. This value should be adjusted in case you are hitting the token limit in your conversations too often. The AI text generation provider should ideally handle the max token limit case. + +Improve AI task pickup speed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See :ref:`the relevant section in AI Overview` for more information. diff --git a/admin_manual/ai/app_context_agent.rst b/admin_manual/ai/app_context_agent.rst new file mode 100644 index 000000000..16d722dac --- /dev/null +++ b/admin_manual/ai/app_context_agent.rst @@ -0,0 +1,140 @@ +================================== +App: Context Agent (context_agent) +================================== + +.. _ai-app-context_agent: + +The *context_agent* app is the app that provides AI agent functionality in Nextcloud and acts as a backend for the :ref:`Nextcloud Assistant app`. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. + +When the Context Agent app is installed the AI Chat in Nextcloud Assistant will be able to interact with your Nextcloud apps via virtual integrations that are called "tools". They allow the Assistant to perform actions in your Nextcloud upon sending instructions in a chat message. + +Currently implemented tools: + +* List the user's calendars + + * Example prompt: *"List my calendars"* + +* List the user's talk conversations + + * Example prompt: *"List my talk conversations"* + +* List messages in a talk conversation + + * Example prompt: *"List the latest messages in my conversation with Andrew"* + +* Find a person in the user's contacts + + * Example prompt: *"What is Andrew's Email address?"* + +* Find the current user's details + + * Example prompt: *"Where do I live?"* + +* Ask a question to context chat + + * Example prompt: *"What is the company's sick leave process?"* + +* Get coordinates for an Address from Open Street Maps Nomatim + + * Example prompt: *"List my calendars"* + +* Get the current weather at a location + + * Example prompt: *"How is the weather in Berlin?"* + +* Schedule an event in the user's calendar + + * Example prompt: *"Make schedule an event with Andrew tomorrow at noon."* + +* Send a message to a talk conversation + + * Example prompt: *"Can you send a joke to Andrew in talk?"* + +* Create a deck card + + * Example prompt: *"Create a deck card for 'Buy Groceries' in my Personal board."* + +* Access information in deck boards + + * Example prompt: *"Which deck cards are currently in the To do list in my Personal board?"* + +* Create a task + + * Example prompt: *"Create a task for 'Renovate flat' in my Personal calendar. The task should be due Monday next week."* + +* Search for youtube videos + + * Example prompt: *"Show me the youtube video of the Nextcloud hub 10 launch."* + +* Send an email via Nextcloud Mail + + * Example prompt *"Send a test email from carry@company.com to Andrew@company.com from my account with id 12"* + * (The account ID will soon be irrelevant) + +These tools can also be combined by the agent to fulfil tasks like the following: + + * *"How is the weather where Andrew lives?"* + + * Uses contacts to look up Andrew's address and then checks the weather + + * *"How is the weather where I live?"* + + * Look up the current user's address and then checks the weather + + * *"Send an email from carry@company.com to Andrew"* + + * Uses contacts to look up Andrew's email and then sends an email + +Requirements +------------ + +* This app is built as an External App and thus depends on AppAPI v3.1.0 or higher +* Nextcloud AIO is supported +* No GPU is necessary for Context Agent but one might be useful if you use it with a self-hosted provider like llm2 + +* CPU Sizing + + * At least 1GB of system RAM + +Installation +------------ + +0. Make sure the :ref:`Nextcloud Assistant app` is installed +1. :ref:`Install AppAPI and setup a Deploy Demon` +2. Install the "Context Agent" ExApp via the "Apps" page in the Nextcloud web admin user interface +3. Install a text generation backend like :ref:`llm2 ` or :ref:`integration_openai ` via the "Apps" page in Nextcloud + + +Model requirements +~~~~~~~~~~~~~~~~~~ + +This app requires underlying Large language models to support tool calling. The default model in *llm2* does *not* support tool calling. Instead we recommend: + +* Mistral 3 small 24B +* Qwen 2.5 8B or higher (May not work well with languages other than English) +* Watt Tool 8B or higher + +See :ref:`llm2 documentation ` on how to configure alternate models. + +Scaling +------- + +It is currently not possible to scale this app, we are working on this. + +App store +--------- + +You can also find the app in our app store, where you can write a review: ``_ + +Repository +---------- + +You can find the app's code repository on GitHub where you can report bugs and contribute fixes and features: ``_ + +Nextcloud customers should file bugs directly with our Support system. + +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 sometimes answer in another language than 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) \ No newline at end of file diff --git a/admin_manual/ai/app_context_chat.rst b/admin_manual/ai/app_context_chat.rst index 53eeb8c2c..13303db74 100644 --- a/admin_manual/ai/app_context_chat.rst +++ b/admin_manual/ai/app_context_chat.rst @@ -11,46 +11,96 @@ Context Chat is an :ref:`assistant` feature that is implemente Together they provide the ContextChat text processing tasks accessible via the :ref:`Nextcloud Assistant app`. -The *context_chat* and *context_chat_backend* apps run only open source models and do so entirely on-premises. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. +The *context_chat* and *context_chat_backend* apps will use the Free text-to-text task processing providers like OpenAI integration, LLM2, etc. and such a provider is required on a fresh install, or it can be configured to run open source models entirely on-premises. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. + +This app supports input and output in the same languages that the currently configured Free text-to-text task processing provider supports. Requirements ------------ -* Minimal Nextcloud version: 28 -* The *context_chat_backend* app is built as an External App and thus depends on AppAPI v2.3.0 and later +* Minimal Nextcloud version: 30 * Nextcloud AIO is supported * We currently support NVIDIA GPUs and x86_64 CPUs -* GPU Sizing +* CPU that supports AVX and AVX2 instruction +* CUDA >= v12.2 on your host system +* GPU Setup Sizing - * A NVIDIA GPU with at least 8GB VRAM - * At least 12GB of system RAM + * A NVIDIA GPU with at least 2GB VRAM + * The requirements for the Free text-to-text providers should be checked separately + * llm2's requirements can be found :ref:`here ` + * integration_openai does not have any additional GPU requirements + * At least 8GB of system RAM + * 2 GB + additional 500MB for each concurrent request made to the backend if configuration parameters are changed -* CPU Sizing +* CPU Setup Sizing * At least 12GB of system RAM + * 2 GB + additional 500MB for each request made to the backend if the Free text-to-text provider is not on the same machine + * 8 GB is recommended in the above case for the default settings + * This app makes use of the configured free text-to-text task processing provider instead of running its own language model by default, you will thus need 4+ cores for the embedding model only (backed configuration needs changes to make use of the extra cores, refer to `Configuration Options (Backend)`_) + +* A dedicated machine is recommended Space usage ~~~~~~~~~~~ -This app employs a bundled Vector DB called `Chroma`. All the users' textual data is duplicated, chunked and stored on disk in this vector DB along with semantic embedding vectors for the content. - -Assuming no shared files between users you can calculate with roughly the amount of textual data in user files (e.g. for PDFs, only the text counts, no images are kept). Any shared files will be duplicated per user, however, so, assuming all files are shared with all users you need to calculate with "the amount of textual data in user files * number of users". The reality will lie between these two estimates, of course. +This app employs a bundled DB with Vector support called `PostgreSQL `_. All the users' textual data is duplicated, chunked and stored on disk in this vector DB along with semantic embedding vectors for the content. Installation ------------ -0. Make sure the :ref:`Nextcloud Assistant app` is installed -1. :ref:`Install AppAPI and setup a Deploy Demon` -2. Install the *context_chat_backend* ExApp via the "External Apps" admin page in Nextcloud -3. Install the *context_chat* app via the "Apps" page in Nextcloud, or by executing +1. Make sure the :ref:`Nextcloud Assistant app` is installed +2. Setup a :ref:`Deploy Demon ` in AppAPI Admin settings +3. Install the *context_chat_backend* ExApp via the "Apps" page in Nextcloud, or by executing (checkout the readme at https://github.com/nextcloud/context_chat_backend for manual install steps) + +.. code-block:: + + occ app_api:app:register context_chat_backend + +4. Install the *context_chat* app via the "Apps" page in Nextcloud, or by executing .. code-block:: occ app:enable context_chat +5. Install a text generation backend like :ref:`llm2 ` or `integration_openai `_ via the "Apps" page in Nextcloud + +6. Optionally but recommended, setup background workers for faster pickup of tasks. See :ref:`the relevant section in AI Overview` for more information. **Note**: Both apps need to be installed and both major version and minor version of the two apps must match for the functionality to work (ie. "v1.3.4" and "v1.3.1"; but not "v1.3.4" and "v2.1.6"; and not "v1.3.4" and "v1.4.5"). Keep this in mind when updating. + +Initial loading of data +----------------------- + +Auto-indexing +~~~~~~~~~~~~~ + +| Context chat will automatically load user data into the Vector DB using asynchronous background jobs. +| The initial loading of data can take a long time depending on the number of files and their size. + +The indexing jobs are set up to run during the Nextcloud instance's maintenance window (typically during the night) only. If you have not set a maintenance window, indexing will run 24/7. + +You can set up a background job worker explicitly for Context Chat to avoid slowing down normal background job operation on larger instances. + +.. code-block:: + + php cron.php "OCA\\ContextChat\\BackgroundJobs\\IndexerJob" "OCA\\ContextChat\\BackgroundJobs\\ActionJob" "OCA\\ContextChat\\BackgroundJobs\\SubmitContentJob" "OCA\\ContextChat\\BackgroundJobs\\StorageCrawlJob" "OCA\\ContextChat\\BackgroundJobs\\InitialContentImportJob" + +You can set this command to run every 15 minutes on weekends using cron for example. + +Synchronous indexing +~~~~~~~~~~~~~~~~~~~~ + +| To index all the files synchronously, use the following command: +| Note: This does not interact with the auto-indexing feature and that list would remain unchanged. However, the indexed files would be skipped when the auto indexer runs. + +.. code-block:: + + occ context_chat:scan + +**Note**: The synchronous command could take several days to complete. On larger systems we thus recommend to use auto-indexing. + Scaling ------- @@ -68,13 +118,93 @@ You can find the app's code repository on GitHub where you can report bugs and c Nextcloud customers should file bugs directly with our Customer Support. +Commands (OCC) +-------------- + +The options for each command can be found like this, using scan as example: ``context_chat:scan --help`` + +* ``context_chat:diagnostics`` + Check currently running ContextChat background processes. + +* ``context_chat:prompt`` + Ask a question about your data, with options for selective context. + +* ``context_chat:scan`` + Scan and index the user's documents based on the user ID provided, synchronously. + +* ``context_chat:stats`` + | Shows the time taken to complete the initial indexing of the documents if it has finished, + | and the current no. of items in the indexer and actions queue. + | "Actions" refers to tasks like file deletions, ownership changes through share changes, etc. + | These file and ownership changes are synced with the backed through this actions queue. + + +Configuration Options (OCC) +--------------------------- + +* ``auto_indexing`` boolean (default: true) + To allow/disallow the IndexerJob from running in the background + +.. code-block:: + + occ config:app:set context_chat auto_indexing --value=true --type=boolean + +* ``indexing_batch_size`` integer (default: 5000) + The number of files to index per run of the indexer background job (this is limited by `indexing_max_time`) + +.. code-block:: + + occ config:app:set context_chat indexing_batch_size --value=100 --type=integer + +* ``indexing_job_interval`` integer (default: 1800) + The interval at which the indexer jobs run in seconds + +.. code-block:: + + occ config:app:set context_chat indexing_job_interval --value=1800 --type=integer + +* ``indexing_max_time`` integer (default: 1800) + The number of seconds to index files for per run, regardless of batch size + +.. code-block:: + + occ config:app:set context_chat indexing_max_time --value=1800 --type=integer + +* ``request_timeout`` integer (default: 3000) + Request timeout in seconds for all requests made to the Context chat backend (the external app in AppAPI). + If a docker socket proxy is used, the ``TIMEOUT_SERVER`` environment variable should be set to a value higher than ``request_timeout``. + +.. code-block:: + + occ config:app:set context_chat request_timeout --value=3 --type=integer + + +Configuration Options (Backend) +------------------------------- + +Refer to `the Configuration head `_ in the backend's readme. + + +Logs +---- + +Logs for the ``context_chat`` PHP app can be found in the Nextcloud log file, which is usually located in the Nextcloud data directory. The log file is named ``nextcloud.log``. + +| For the backend, warning and error logs can be found in the docker container logs, and the complete logs can be found in ``logs/`` directory in the persistent storage of the docker container. +| That will be ``/nc_app_context_chat_backend/logs/`` in the docker container. +| See `the Logs head `_ in the backend's readme for more information. + +Possibility of Data Leak +------------------------ + +| It is possible that some users who had access to certain files/folders (and have later have been denied this access) still have access to the content of those files/folders through the Context Chat app. We're working on a solution for this. +| The users who never had access to a particular file/folder will NOT be able to see those contents in any way. + Known Limitations ----------------- -* The underlying language model used by Context Chat cannot be changed -* We currently only support the English language -* Language models are likely to generate false information and should thus only be used in situations that are not critical. It's recommended to only use AI at the beginning of a creation process and not at the end, so that outputs of AI serve as a draft for example and not as final product. Always check the output of language models before using it. -* Make sure to test this app for whether it meets your use-case's quality requirements -* 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) -* Due to technical limitations that we are in the process of mitigating, each task currently incurs a time cost of between 0 and 5 minutes in addition to the actual processing time -* Nextcloud usernames can be only 56 characters long. This is a limitation of the vector database we use (Chroma DB) and will be fixed soon. +* Language models are likely to generate false information and should thus only be used in situations that are not critical. It's recommended to only use AI at the beginning of a creation process and not at the end, so that outputs of AI serve as a draft for example and not as final product. Always check the output of language models before using it and make sure whether it meets your use-case's quality requirements. +* Context Chat is not integrated into the Chat UI of assistant app, at the moment, but has it's own interface in the assistant modal +* 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). +* Large files are not supported in "Selective context" in the Assistant UI if they have not been indexed before. Use ``occ context_chat:scan -d `` to index the desired directory synchronously and then use the Selective context option. "Large files" could mean differently for different users. It depends on the amount of text inside the documents in question and the hardware on which the indexer is running. Generally 20 MB should be large for a CPU-backed setup and 100 MB for a GPU-backed system. +* Password protected PDFs or any other files are not supported. There will be error logs mentioning cryptography and AES in the docker container when such files are encountered but it is nothing to worry about, they will be simply ignored and the system will continue to function normally. diff --git a/admin_manual/ai/app_llm2.rst b/admin_manual/ai/app_llm2.rst index 2c78c11e4..f01379be7 100644 --- a/admin_manual/ai/app_llm2.rst +++ b/admin_manual/ai/app_llm2.rst @@ -4,31 +4,50 @@ App: Local large language model (llm2) .. _ai-app-llm2: -The *llm2* app is one of the apps that provide text processing functionality using Large language models in Nextcloud and act as a text processing backend for the :ref:`Nextcloud Assistant app`, the *mail* app and :ref:`other apps making use of the core Translation API`. The *llm2* app specifically runs only open source models and does so entirely on-premises. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. +The *llm2* app is one of the apps that provide text processing functionality using Large language models in Nextcloud and act as a text processing backend for the :ref:`Nextcloud Assistant app`, the *mail* app and :ref:`other apps making use of the core Text Processing API`. The *llm2* app specifically runs only open source models and does so entirely on-premises. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. -This app uses `ctransformers `_ under the hood and is thus compatible with any model in *gguf* format. Output quality will differ depending on which model you use, we recommend the following models: +This app uses `llama.cpp `_ under the hood and is thus compatible with any model in *gguf* format. -* `Llama2 7b Chat `_ (Slightly older; good quality; good acclaim) -* `NeuralBeagle14 7B `_ (Newer; good quality; less well known) +However, we only test with Llama 3.1. Output quality will differ depending on which model you use and downstream tasks like summarization or Context Chat may not work on other models. +We thus recommend the following models: + +* `Llama3.1 8b Instruct `_ (reasonable quality; fast; good acclaim; comes shipped with the app) +* `Llama3.1 70B Instruct `_ (good quality; good acclaim) + +Multilinguality +--------------- + +This app supports input and output in languages other than English if the underlying model supports the language. + +Llama 3.1 `supports the following languages: `_ + +* English +* Portuguese +* Spanish +* Italian +* German +* French +* Hindi +* Thai + +Note, that other languages may work as well, but only the above languages are guaranteed to work. Requirements ------------ -* This app is built as an External App and thus depends on AppAPI v2.3.0 +* This app is built as an External App and thus depends on AppAPI v3.1.0 or higher * Nextcloud AIO is supported -* Using GPU processing is supported, but not required; be prepared for slow performance unless you are using GPU -* We currently only support NVIDIA GPUs +* We currently support NVIDIA GPUs and x86_64 CPUs +* CPU that supports AVX and AVX2 instruction +* CUDA >= v12.2 on your host system * GPU Sizing - * You will need a GPU with enough VRAM to hold the model you choose - - * for 7B parameter models, 5bit-quantized variants and lower should fit on a 8GB VRAM, but of course have lower quality - * for 7B parameter models, 6bit-quantized variants and up will need 12GB VRAM - * If you want better reasoning capabilities, you will need to look for models with more parameters, like 14B and higher, which of course also need more VRAM + * A NVIDIA GPU with at least 8GB VRAM + * At least 12GB of system RAM * CPU Sizing - * If you don't have a GPU, this app will utilize your CPU cores + * At least 12GB of system RAM * The more cores you have and the more powerful the CPU the better, we recommend 10-20 cores * The app will hog all cores by default, so it is usually better to run it on a separate machine @@ -37,7 +56,7 @@ Installation 0. Make sure the :ref:`Nextcloud Assistant app` is installed 1. :ref:`Install AppAPI and setup a Deploy Demon` -2. Install the "Local large language model" ExApp via the "External Apps" page in the Nextcloud web admin user interface +2. Install the "Local large language model" ExApp via the "Apps" page in the Nextcloud web admin user interface Supplying alternate models ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -49,6 +68,43 @@ This app allows supplying alternate LLM models as *gguf* files in the ``/nc_app_ 3. Restart the llm2 ExApp 4. Select the new model in the Nextcloud AI admin settings + +Configuring alternate models +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since every model requires slightly different inference parameters, you can pass along a configuration file for the alternate model files you supply. + +The configuration file for a model file must have the same name as the model file but must end in ``.json`` instead of ``.gguf``. + +The strings ``{system_prompt}`` and ``{user_prompt}`` are variables that will be filled in by the app, so they must be part of your prompt template. + +Here is an example config file for Llama 2: + +.. code-block:: json + + { + "prompt": "<|im_start|> system\n{system_prompt}\n<|im_end|>\n<|im_start|> user\n{user_prompt}\n<|im_end|>\n<|im_start|> assistant\n", + "loader_config": { + "n_ctx": 4096, + "max_tokens": 2048, + "stop": ["<|im_end|>"] + } + } + +Here is an example configuration for Llama 3: + +.. code-block:: json + + { + "prompt": "<|begin_of_text|><|start_header_id|>system<|end_header_id|>\n{system_prompt}<|eot_id|><|start_header_id|>user<|end_header_id|>\n{user_prompt}<|eot_id|>\n<|start_header_id|>assistant<|end_header_id|>\n", + "loader_config": { + "n_ctx": 8000, + "max_tokens": 4000, + "stop": ["<|eot_id|>"], + "temperature": 0.3 + } + } + Scaling ------- @@ -69,9 +125,32 @@ Nextcloud customers should file bugs directly with our Support system. Known Limitations ----------------- -* We currently only support the English language +* We currently only support languages that the underlying model supports; correctness of language use in languages other than English may be poor depending on the language's coverage in the model's training data (We recommended model Llama 3 or other models explicitly trained on multiple languages) +* Language models can be bad at reasoning tasks * Language models are likely to generate false information and should thus only be used in situations that are not critical. It's recommended to only use AI at the beginning of a creation process and not at the end, so that outputs of AI serve as a draft for example and not as final product. Always check the output of language models before using it. * Make sure to test the language model you are using it for whether it meets the use-case's quality requirements -* Language models notoriously have a high energy consumption, if you want to reduce load on your server you can choose smaller models or quantized models in excahnge for lower accuracy +* Language models notoriously have a high energy consumption, if you want to reduce load on your server you can choose smaller models or quantized models in exchange for lower accuracy * 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) -* Due to technical limitations that we are in the process of mitigating, each task currently incurs a time cost of between 0 and 5 minutes in addition to the actual processing time + +Addendum: Running with a fully open model +----------------------------------------- + +If you would like to use a fully open model that scores a green score on our Ethical AI rating, we recommend the following model: + +* OLMo 2 (either in 7B or 13B): ``_ + +What makes OLMo a fully open model? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* The code for training, fine-tuning and inference of the model is publicly available and fully open source +* The training data with which the model is pretrained is publicly available +* The model itself is publicly available and fully open source +* The instruction tuning data is publicly available +* The Reinforcement learning model is publicly available and fully open source + +Limitations +~~~~~~~~~~~ + +* OLMo currently only works well with English language input +* In our tests it sometimes produced hallucinated or garbled output; make sure to thoroughly test the model for your use case +* It cannot use tools, so cannot be used in conjunction with :ref:`Context Agent ` diff --git a/admin_manual/ai/app_stt_whisper2.rst b/admin_manual/ai/app_stt_whisper2.rst index 4ef327dd0..3dc259b38 100644 --- a/admin_manual/ai/app_stt_whisper2.rst +++ b/admin_manual/ai/app_stt_whisper2.rst @@ -6,10 +6,14 @@ App: Local Whisper Speech-To-Text (stt_whisper2) The *stt_whisper2* app is one of the apps that provide Speech-To-Text functionality in Nextcloud and act as a media transcription backend for the :ref:`Nextcloud Assistant app`, the *talk* app and :ref:`other apps making use of the core Translation API`. The *stt_whisper2* app specifically runs only open source models and does so entirely on-premises. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. +This app supports input and output in languages other than English if the underlying model supports the language. + This app uses `faster-whisper `_ under the hood. Output quality will differ depending on which model you use, we recommend the following models: - * OpenAI Whisper large-v2 or v3 - * OpenAI Whisper medium.en + * OpenAI Whisper large-v2 or v3 (multilingual) + * OpenAI Whisper medium.en (English only) + +Whisper large v3 supports about ~100 languages and shows outstanding performance in ~10 of them. For more details see the `OpenAI Whisper paper `_ Requirements ------------ @@ -17,37 +21,28 @@ Requirements * Minimal Nextcloud version: 28 * This app is built as an External App and thus depends on AppAPI v2.3.0 * Nextcloud AIO is supported -* Using GPU processing is supported, but not required; be prepared for slow performance unless you are using GPU -* We currently only support NVIDIA GPUs -* GPU Sizing - - * You will need a GPU with enough VRAM to hold the model you choose - - * the small model should fit on 2GB VRAM - * the large-v2 (the best and largest) will need 6GB VRAM - - * The distil-whisper variants have half the parameters of the original models while supposedly staying within 1% of the original error rate (your mileage may vary) +* Using GPU is currently not supported * CPU Sizing - * If you don't have a GPU, this app will utilize your CPU cores * The more cores you have and the more powerful the CPU the better, we recommend 10-20 cores * The app will hog all cores by default, so it is usually better to run it on a separate machine + * 4GB for the app Installation ------------ 0. Make sure the :ref:`Nextcloud Assistant app` is installed 1. :ref:`Install AppAPI and setup a Deploy Demon` -2. Install the *stt_whisper2* "Local Speech-To-Text" ExApp via the "External Apps" page in the Nextcloud web admin user interface +2. Install the *stt_whisper2* "Local Speech-To-Text" ExApp via the "Apps" page in the Nextcloud web admin user interface Supplying alternate models ~~~~~~~~~~~~~~~~~~~~~~~~~~ -This app allows supplying alternate LLM models as *gguf* files in the ``/nc_app_llm2_data`` directory of the docker container. You can use any `*faster-whisper* model by Systran on hugging face `_ by simply +This app allows supplying alternate models in the ``/nc_app_stt_whisper2_data`` directory of the docker container. You can use any `*faster-whisper* model by Systran on hugging face `_ in the following way: 1. git cloning the respective repository -2. Copying the folder with the git repository to ``/nc_app_llm2_data`` inside the docker container. +2. Copying the folder with the git repository to ``/nc_app_stt_whisper2_data`` inside the docker container. 3. Restarting the Whisper ExApp 4. Selecting the respective model in the Nextcloud AI admin settings @@ -76,6 +71,6 @@ Known Limitations * The whisper models perform unevenly across languages, and may show lower accuracy on low-resource and/or low-discoverability languages or languages where there was less training data available. The models also exhibit disparate performance on different accents and dialects of particular languages, which may include higher word error rate across speakers of different genders, races, ages, or other demographic criteria. * Language models are likely to generate false information and should thus only be used in situations that are not critical. It's recommended to only use AI at the beginning of a creation process and not at the end, so that outputs of AI serve as a draft for example and not as final product. Always check the output of language models before using it. * Make sure to test the language model you are using it for whether it meets the use-case's quality requirements -* Language models notoriously have a high energy consumption, if you want to reduce load on your server you can choose smaller models or quantized models in excahnge for lower accuracy +* Language models notoriously have a high energy consumption, if you want to reduce load on your server you can choose smaller models or quantized models in exchange for lower accuracy * 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) * Due to technical limitations that we are in the process of mitigating, each task currently incurs a time cost of between 0 and 5 minutes in addition to the actual processing time diff --git a/admin_manual/ai/app_summary_bot.rst b/admin_manual/ai/app_summary_bot.rst new file mode 100644 index 000000000..c9ff54560 --- /dev/null +++ b/admin_manual/ai/app_summary_bot.rst @@ -0,0 +1,137 @@ +========================================== +App: Summary Bot (Talk chat summarize bot) +========================================== + +.. _ai-app-summary-bot: + +The *Summary Bot* app utilizes Large Language Model (LLM) providers in Nextcloud and can be added to a conversation in `Nextcloud Talk` to generate summaries from the chat messages of that room either on-demand or following a schedule. +It can run on only open source or proprietary models either on-premises or in the cloud leveraging apps like `Local large language model app `_ or `OpenAI and LocalAI integration app `_. + +Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. + +The app currently supports the following languages: + +* English (en) + +The quality of summaries depends directly on the quality of the underlying model. It is recommended to test the model for the desired use-case before applying it. + +Requirements +------------ + +* Minimal Nextcloud version: 30 +* Docker +* AppAPI >= 3.0.0 +* Talk +* Task Processing Provider like Local large language model app (llm2) or OpenAI and LocalAI integration app (integration_openai) + +Space usage +~~~~~~~~~~~ + +* ~100MB + +Installation +------------ + +0. Make sure the following apps are installed: + + - `Nextcloud AppAPI app `_ + + - `Nextcloud Talk app (Spreed) `_ + + - One of the following AI model providers: + + - `Nextcloud Local large language model app `_ + + - `Nextcloud OpenAI and LocalAI integration app `_ + + +Setup (via App Store) +~~~~~~~~~~~~~~~~~~~~~ + +1. Install the *Summary Bot* app via the "Apps" page in Nextcloud + +2. Enable the *Summary Bot* Bot for the selected Chatroom via the three dots menu of the Chatroom (The Bots settings are located inside the *Bots* section) + +Setup (Manual) +~~~~~~~~~~~~~~ + +After cloning this app *manually* (cloned via git to your apps directory) you will need to execute the following steps: + +1. Change to the folder you have cloned the source to: +.. code-block:: + + cd /path/to/your/nextcloud/webroot/apps/summary_bot/ + + +2. Build the docker image: +.. code-block:: + + docker build --no-cache -f Dockerfile -t local_summary_bot . + +3. Run the docker image: + +*Info:* + +- APP_VERSION environment variable should be equal to the version of the *Summary Bot* you are using + +- NEXTCLOUD_URL environment variable must be set to your Nextcloud instance's URL, ensuring it's reachable by the docker image. + +.. code-block:: + + sudo docker run -ti -v /etc/localtime:/etc/localtime:ro -v /etc/timezone:/etc/timezone:ro -e APP_ID=summary_bot -e APP_DISPLAY_NAME="Summary Bot" -e APP_HOST=0.0.0.0 -e APP_PORT=9031 -e APP_SECRET=12345 -e APP_VERSION=1.0.0 -e NEXTCLOUD_URL='' -p 9031:9031 local_summary_bot + + +4. Un-register the Summary Bot if its already installed + +.. code-block:: + + sudo -u php /path/to/your/nextcloud/webroot/occ app_api:app:unregister summary_bot + + +5. Register the Summary Bot so that your Nextcloud instance is aware of it + +*Info:* Adjust the host value in the following example to the IP address of the docker container (for added security) + +.. code-block:: + + sudo -u php ./occ app_api:app:register summary_bot manual_install --json-info '{ "id": "summary_bot", "name": "Summary Bot", "daemon_config_name": "manual_install", "version": "1.0.0", "secret": "12345", "host": "0.0.0.0", "port": 9031, "scopes": ["AI_PROVIDERS", "TALK", "TALK_BOT"], "protocol": "http"}' --force-scopes --wait-finish + + +6. Enable the *Summary Bot* for the selected Chatroom via the three dots menu of the Chatroom (The Bots settings are located inside the *Bots* section) + +Usage +----- + +After enabling the *Summary Bot* in a Chatroom, you can test its functionality by simply sending the message below: + + "@summary" or "@summary help" + +App store +--------- + +You can also find the app in our app store, where you can write a review: ``_ + +Repository +---------- + +You can find the app's code repository on GitHub where you can report bugs and contribute fixes and features: ``_ + +Nextcloud customers should file bugs directly with our Customer Support. + +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`. + +Known Limitations +----------------- + +* The Summary Bot cannot access previous conversations, it only recognizes messages from the moment it was enabled in the chatroom. +* Summary of maximum 40000 characters is supported. This assumes the underlying model can handle this amount of text (which should be close to 16000 context length). +* Languages other than English are not supported. The underlying model may still be able to understand other languages. +* AI models may occasionally produce inaccurate information. Therefore, they should be employed with caution in non-critical scenarios. It's essential to verify the accuracy of the bot's output before application. +* Be aware that AI models can consume a significant amount of energy. It's advisable to consider this factor in the planning and operation of AI systems if hosted on-premises or sustainability is a concern. +* AI models can exhibit extended processing times when run on CPUs. For enhanced efficiency, utilizing GPU support is recommended to expedite request handling. +* Customer support is available upon request, however we can't solve false or problematic output (hallucinations), most performance issues, or other problems caused by the underlying models. Support is thus limited only to bugs directly caused by the implementation of the app (connectors, API, front-end, AppAPI) diff --git a/admin_manual/ai/app_text2image_stablediffusion2.rst b/admin_manual/ai/app_text2image_stablediffusion2.rst new file mode 100644 index 000000000..d854d7970 --- /dev/null +++ b/admin_manual/ai/app_text2image_stablediffusion2.rst @@ -0,0 +1,60 @@ +========================================================= +App: Local Image Generation (text2image_stablediffusion2) +========================================================= + +.. _ai-app-text2image_stablediffusion2: + +The *text2image_stablediffusion2* app is one of the apps that provide image generation functionality in Nextcloud and act as an image generation backend for the :ref:`Nextcloud Assistant app` and other apps making use of the image generation functionality. The *text2image_stablediffusion2* app specifically runs only open source models and does so entirely on-premises. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. + +Requirements +------------ + +* This app is built as an External App and thus depends on AppAPI v3.1.0 or higher +* Nextcloud AIO is supported +* We currently support NVIDIA GPUs and x86_64 CPUs +* CUDA >= v12.2 on your host system +* GPU Sizing + + * A NVIDIA GPU with at least 8GB VRAM + +* CPU Sizing + + * At least 8GB of system RAM + * The more cores you have and the more powerful the CPU the better, we recommend 10-20 cores + * The app will hog all cores by default, so it is usually better to run it on a separate machine + +Installation +------------ + +* Make sure the :ref:`Nextcloud Assistant app` is installed +* :ref:`Install AppAPI and setup a Deploy Demon` +* Install the "Local large language model" ExApp via the "Apps" page in the Nextcloud web admin user interface + + +Scaling +------- + +It is currently not possible to scale this app, we are working on this. Based on our calculations an instance has a rough capacity of 120 image requests per hour (each user request can be for multiple images). However, this number is based on theory and we do appreciate real-world feedback on this. + +App store +--------- + +You can also find the app in our app store, where you can write a review: ``_ + +Repository +---------- + +You can find the app's code repository on GitHub where you can report bugs and contribute fixes and features: ``_ + +Nextcloud customers should file bugs directly with our Support system. + +Known Limitations +----------------- + +* The generated images are of a fixed resolution (512x512 pix), and the model does not achieve perfect photorealism +* The model cannot render legible text +* Faces and people in general may not be generated properly +* The results for certain image generation requests can be biased and may enforce stereotypes +* We currently only support languages that the underlying model supports; correctness of language use in languages other than English may be poor depending on the language's coverage in the model's training data +* Make sure to test the app for whether it meets the use-case's quality requirements +* 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) diff --git a/admin_manual/ai/app_translate.rst b/admin_manual/ai/app_translate.rst deleted file mode 100644 index e4ea8b265..000000000 --- a/admin_manual/ai/app_translate.rst +++ /dev/null @@ -1,103 +0,0 @@ -========================================== -App: Local Machine translation (translate) -========================================== - -.. _ai-app-translate: - -The *translate* app is one of the apps that provide machine translation functionality in Nextcloud and act as a translation backend for the :ref:`Nextcloud Assistant app`, the *text* app and :ref:`other apps making use of the core Translation API`. The *translate* app specifically runs only open source models and does so entirely on-premises. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. - -The app currently supports the following languages: - -* English (en) -* German (de) -* French (fr) -* Spanish (es) -* Chinese (zh) - -As the models are entirely open source, the quality of translations may not be comparable to commercially available machine translation services. - -Requirements ------------- - -* Minimal Nextcloud version: 26 -* x86 CPU -* GNU lib C (musl is not supported) -* This app does not support using GPU for processing and may thus not be performing ideally for long texts - -(*Note*: Nextcloud AIO is currently not supported due to it using musl) - -Space usage -~~~~~~~~~~~ - - * ~1GB per language pair - * ~10GB in total - -Installation ------------- - -0. Make sure the :ref:`Nextcloud Assistant app` is installed -1. Install the *translate* app via the "Apps" page in Nextcloud, or by executing - - occ app:enable translate - -Setup -~~~~~ - -After installing this app you will need to run: - -.. code-block:: - - occ translate:download-models - -You may also download only specific languages by using the following command: - -.. code-block:: - - occ translate:download-models - -For example - -.. code-block:: - - occ translate:download-models de en - -will download both en->de and de->en. - -.. code-block:: - - occ translate:download-models de en es - -will download en->de, de->en, en->es, es->en, es->de, de->es - -App store ---------- - -You can also find the app in our app store, where you can write a review: ``_ - -Repository ----------- - -You can find the app's code repository on GitHub where you can report bugs and contribute fixes and features: ``_ - -Nextcloud customers should file bugs directly with our Customer Support. - -Ethical AI Rating ------------------ - -Rating: 🟢 -~~~~~~~~~~ - -Positive: -* the software for training and inference of this model is open source -* the trained model is freely available, and thus can be run on-premises -* the training data is freely available, making it possible to check or correct for bias or optimise the performance and CO2 usage. - -Learn more about the Nextcloud Ethical AI Rating `in our blog`. - -Known Limitations ------------------ - -* Language models are likely to generate false information and should thus only be used in situations that are not critical. It's recommended to only use AI at the beginning of a creation process and not at the end, so that outputs of AI serve as a draft for example and not as final product. Always check the output of language models before using it. -* Make sure to test the translation model you are using it for whether it meets the use-case's quality requirements -* Language models notoriously have a high energy consumption -* 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 models. Support is thus limited only to bugs directly caused by the implementation of the app (connectors, API, front-end, AppAPI) diff --git a/admin_manual/ai/app_translate2.rst b/admin_manual/ai/app_translate2.rst new file mode 100644 index 000000000..05cc8bfb3 --- /dev/null +++ b/admin_manual/ai/app_translate2.rst @@ -0,0 +1,81 @@ +============================================= +App: Local Machine translation 2 (translate2) +============================================= + +.. _ai-app-translate2: + +The *translate2* app is one of the apps that provide machine translation functionality in Nextcloud and act as a translation backend for the :ref:`Nextcloud Assistant app`. The *translate2* app specifically runs only open source models and does so entirely on-premises. Nextcloud can provide customer support upon request, please talk to your account manager for the possibilities. + +The app currently supports 400+ languages. See the complete list here: https://huggingface.co/datasets/allenai/MADLAD-400 + +Requirements +------------ + +* Minimal Nextcloud version: 30 +* This app is built as an External App and thus depends on AppAPI v3.1.0 or higher +* Nextcloud AIO is supported +* We currently support NVIDIA GPUs and x86_64 CPUs +* CUDA >= v12.2.2 on your host system +* GPU Sizing + + * A NVIDIA GPU with at least 4 GB VRAM + * At least 6 GB of system RAM + +* CPU Sizing + + * x86 CPU with 4-8 cores for the app to use (The more cores the faster it will be) + * At least 6 GB of RAM for the app should be enough (includes software+libraries and the model) + +Space usage +~~~~~~~~~~~ + + * ~ 2.95 GB for the docker container + * ~ 2.77 GB for the default model + +Installation +------------ + +0. Make sure the :ref:`Nextcloud Assistant app` is installed +1. :ref:`Install AppAPI and setup a Deploy Demon` +2. Install the "Local Machine Translation" (translate2) ExApp via the "Apps" page in the Nextcloud web admin user interface + +Model Switch +------------ + +1. Remove ``hf_model_path`` key from ``loader`` object in the ``config.json`` file in the docker container named ``nc_app_translate2``. +2. Change ``model_name`` to the new model name to ``Nextcloud-AI/madlad400-7b-mt-bt-ct2-int8_float32``. +3. Restart the docker container ``docker restart nc_app_translate2`` + +App store +--------- + +You can also find the app in our app store, where you can write a review: ``_ + +Repository +---------- + +You can find the app's code repository on GitHub where you can report bugs and contribute fixes and features: ``_ + +Nextcloud customers should file bugs directly with our Customer Support. + +Ethical AI Rating +----------------- + +Rating: 🟢 +~~~~~~~~~~ + +Positive: +* the software for training and inference of this model is open source +* the trained model is freely available, and thus can be run on-premises +* the training data is freely available, making it possible to check or correct for bias or optimise the performance and CO2 usage. + +Learn more about the Nextcloud Ethical AI Rating `in our blog `_. + +Known Limitations +----------------- + +* AI translations are not a replacement for human professional translations and in many cases post-editing is required. AI translations can be used for understanding the main content of a text but not for translations that require special knowledge (such as technical content or legal content), or translations that require specific writing style to convey style, deeper meaning, or emotions (such as marketing content or translating books). +* While the quality of the output will be fine for the most common languages (English, French, Spanish) the quality will suffer for languages that have less coverage in the original training set. +* Make sure to test the translation model you are using it for whether it meets the use-case's quality requirements. The default model is the smallest of the batch and might produce duplicate translation outputs. Switch to a larger model if you need better quality and less artifacts, see `Model Switch`_. +* Language models notoriously have a high energy consumption. +* 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 models. Support is thus limited only to bugs directly caused by the implementation of the app (connectors, API, front-end, AppAPI). diff --git a/admin_manual/ai/images/ai_overview.png b/admin_manual/ai/images/ai_overview.png new file mode 100644 index 000000000..509cc40d8 Binary files /dev/null and b/admin_manual/ai/images/ai_overview.png differ diff --git a/admin_manual/ai/images/ai_overview.svg b/admin_manual/ai/images/ai_overview.svg new file mode 100644 index 000000000..e98f4bf9f --- /dev/null +++ b/admin_manual/ai/images/ai_overview.svg @@ -0,0 +1,4 @@ + + + +
OpenAI integration
llm2
translate2
stt_whisper2
Text processing
(e.g. Summary)
Translation
Transcription
Image generation
OpenAI integration
OpenAI integration
OpenAI integration
text2image_
stablediffusion
Context Chat
AI backend Apps
AI frontend Apps
AI task types
Deepl integration
Context Agent
Nextcloud Assistant
Nextcloud Mail
Nextcloud Office
Nextcloud Talk
Replicate
integration
 \ No newline at end of file diff --git a/admin_manual/ai/index.rst b/admin_manual/ai/index.rst index d86935c8c..26f0583ea 100644 --- a/admin_manual/ai/index.rst +++ b/admin_manual/ai/index.rst @@ -7,10 +7,12 @@ Artificial Intelligence overview app_assistant - app_translate + app_translate2 app_llm2 app_stt_whisper2 + app_text2image_stablediffusion2 app_recognize app_context_chat - app_api_and_external_apps + app_context_agent + app_summary_bot ai_as_a_service diff --git a/admin_manual/ai/overview.rst b/admin_manual/ai/overview.rst index 266fcf3b3..0607e595c 100644 --- a/admin_manual/ai/overview.rst +++ b/admin_manual/ai/overview.rst @@ -11,6 +11,9 @@ Overview of AI features Nextcloud uses modularity to separate raw AI functionality from the Graphical User interfaces and apps that make use of said functionality. Each instance can thus make use of various backends that provide the functionality for the same frontends and the same functionality can be implemented by multiple apps using on-premises processing or third-party AI service providers. +.. figure:: images/ai_overview.png + :scale: 80% + .. csv-table:: :header: "Feature","App","Rating","Open source","Freely available model","Freely available training data","Privacy: Keeps data on premises" @@ -22,23 +25,45 @@ Nextcloud uses modularity to separate raw AI functionality from the Graphical Us "Suspicious login detection","`Suspicious Login `_","Green","Yes","Yes","Yes","Yes" "Related resources","`Related Resources `_","Green","Yes","Yes","Yes","Yes" "Recommended files","recommended_files","Green","Yes","Yes","Yes","Yes" - "Machine translation","`Translate `_","Green","Yes","Yes - Opus models by University Helsinki","Yes","Yes" - "","`LibreTranslate integration `_","Green","Yes","Yes - OpenNMT models","Yes","Yes" + "Text processing using LLMs","`llm2 (ExApp) `_","Green","Yes","Yes - Llama 3.1 model by Meta","Yes","Yes" + "","`OpenAI and LocalAI integration (via OpenAI API) `_","Red","No","No","No","No" + "","`OpenAI and LocalAI integration (via LocalAI) `_","Yellow","Yes","Yes - e.g. Llama models by Meta", "No","Yes" + "","`OpenAI and LocalAI integration (via Ollama) `_","Yellow","Yes","Yes - e.g. Llama models by Meta", "No","Yes" + "","`OpenAI and LocalAI integration (via IONOS AI Model Hub) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via Plusserver) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via Groqcloud) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via MistralAI) `_","Orange","No","Yes","No","No" + "Machine translation","`Local Machine Translation 2 (ExApp) `_","Green","Yes","Yes - MADLAD models by Google","Yes","Yes" "","`DeepL integration `_","Red","No","No","No","No" "","`OpenAI and LocalAI integration (via OpenAI API) `_","Red","No","No","No","No" "","`OpenAI and LocalAI integration (via LocalAI) `_","Green","Yes","Yes","Yes","Yes" - "","`Local Whisper Speech-To-Text 2 (ExApp) `_","Yellow","Yes","Yes - Whisper models by OpenAI","No","Yes" + "","`OpenAI and LocalAI integration (via Ollama) `_","Yellow","Yes","Yes - e.g. Llama models by Meta", "No","Yes" + "","`OpenAI and LocalAI integration (via IONOS AI Model Hub) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via Plusserver) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via Groqcloud) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via MistralAI) `_","Orange","No","Yes","No","No" + "Speech to Text","`Local Whisper Speech-To-Text 2 (ExApp) `_","Yellow","Yes","Yes - Whisper models by OpenAI","No","Yes" "","`OpenAI and LocalAI integration `_","Yellow","Yes","Yes - Whisper models by OpenAI","No","No" + "","`OpenAI and LocalAI integration (via LocalAI) `_","Green","Yes","Yes","Yes","Yes" + "","`OpenAI and LocalAI integration (via Ollama) `_","Yellow","Yes","Yes - e.g. Whisper", "No","Yes" + "","`OpenAI and LocalAI integration (via IONOS AI Model Hub) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via Plusserver) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via Groqcloud) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via MistralAI) `_","Orange","No","Yes","No","No" "","`Replicate integration `_","Yellow","Yes","Yes - Whisper models by OpenAI","No","No" "Image generation","`Local Stable Diffusion `_","Yellow","Yes","Yes - StableDiffusion XL model by StabilityAI","No","Yes" - "","`OpenAI and LocalAI integration (via OpenAI API) `_","Red","No","No","No","No" - "","`OpenAI and LocalAI integration (via LocalAI) `_","Yellow","Yes","Yes - StableDiffusion models by StabilityAI","No","Yes" "","`Replicate integration `_","Yellow","Yes","Yes - StableDiffusion models by StabilityAI","No","No" "","`Local large language model 2 (ExApp) `_","Yellow","Yes","Yes","No","Yes" "","`OpenAI and LocalAI integration (via OpenAI API) `_","Red","No","No","No","No" "","`OpenAI and LocalAI integration (via LocalAI) `_","Green","Yes","Yes","Yes","Yes" + "","`OpenAI and LocalAI integration (via Ollama) `_","Yellow","Yes","Yes - e.g. Llama models by Meta", "No","Yes" + "","`OpenAI and LocalAI integration (via IONOS AI Model Hub) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via Plusserver) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via Groqcloud) `_","Orange","No","Yes","No","No" + "","`OpenAI and LocalAI integration (via MistralAI) `_","Orange","No","Yes","No","No" "Context Chat","`Nextcloud Assistant Context Chat `_","Yellow","Yes","Yes","No","Yes" "","`Nextcloud Assistant Context Chat (Backend) `_","Yellow","Yes","Yes","No","Yes" + "Context Agent","`Nextcloud Context Agent `_","Green","Yes","Yes","Yes","Yes" Ethical AI Rating @@ -66,6 +91,30 @@ Features used by other apps Some of our AI features are realized as generic APIs that any app can use and any app can provide an implementation for by registering a provider. So far, these are Machine translation, Speech-To-Text, Image generation, Text processing and Context Chat. +Text processing +^^^^^^^^^^^^^^^ + +.. _tp-consumer-apps: + +As you can see in the table above we have multiple apps offering text processing using Large language models. +In downstream apps like Context Chat and assistant, users can use the text processing functionality regardless of which app implements it behind the scenes. + +Frontend apps +~~~~~~~~~~~~~ + +* *Text* for offering an inline graphical UI for the various tasks +* `Assistant `_ for offering a graphical UI for the various tasks and a smart picker +* `Mail `_ for summarizing mail threads (see :ref:`the Nextcloud Mail docs` for how to enable this) +* `Summary Bot `_ for summarizing chat histories in `Talk `_ + + +Backend apps +~~~~~~~~~~~~ + +* :ref:`llm2` - Runs open source AI LLM models on your own server hardware (Customer support available upon request) +* `OpenAI and LocalAI integration (via OpenAI API) `_ - Integrates with the OpenAI API to provide AI functionality from OpenAI servers (Customer support available upon request; see :ref:`AI as a Service`) + + Machine translation ^^^^^^^^^^^^^^^^^^^ @@ -84,9 +133,8 @@ Frontend apps Backend apps ~~~~~~~~~~~~ -* :ref:`translate` - Runs open source AI translation models locally on your own server hardware (Customer support available upon request) +* :ref:`translate2 (ExApp)` - Runs open source AI translation models locally on your own server hardware (Customer support available upon request) * *integration_deepl* - Integrates with the deepl API to provide translation functionality from Deepl.com servers (Only community supported) -* *integration_libretranslate* - Integrates with the open source LibreTranslate API to provide translation functionality hosted commercially or on your own hardware (Only community supported) Speech-To-Text ^^^^^^^^^^^^^^ @@ -99,37 +147,15 @@ Frontend apps ~~~~~~~~~~~~~ * `Assistant `_ offering a graphical translation UI and a smart picker -* `Speech-to-Text Helper `_ for providing a Speech-To-Text smart picker (deprecated; was merged into assistant) * `Talk `_ for transcribing calls (see `Nextcloud Talk docs `_ for how to enable this) Backend apps ~~~~~~~~~~~~ * :ref:`stt_whisper2` - Runs open source AI Speech-To-Text models on your own server hardware (Customer support available upon request) -* *integration_openai* - Integrates with the OpenAI API to provide AI functionality from OpenAI servers (Customer support available upon request; see :ref:`AI as a Service`) +* `OpenAI and LocalAI integration (via OpenAI API) `_ - Integrates with the OpenAI API to provide AI functionality from OpenAI servers (Customer support available upon request; see :ref:`AI as a Service`) -Text processing -^^^^^^^^^^^^^^^ - -.. _tp-consumer-apps: - -As you can see in the table above we have multiple apps offering Text processing capabilities. In downstream apps like the Nextcloud Assistant app, users can use the text processing functionality regardless of which app implements it behind the scenes. - -Frontend apps -~~~~~~~~~~~~~ - -* `Assistant `_ for offering a graphical UI for the various tasks and a smart picker -* `GPTFreePrompt `_ for providing an llm smart picker (deprecated; was merged into assistant) -* `Mail `_ for summarizing mail threads (see :ref:`the Nextcloud Mail docs` for how to enable this) -* `SummarAI `_ for summarizing chat histories in `Talk `_ - -Backend apps -~~~~~~~~~~~~ - -* :ref:`llm2` - Runs open source AI language models locally on your own server hardware (Customer support available upon request) -* *integration_openai* - Integrates with the OpenAI API to provide AI functionality from OpenAI servers (Customer support available upon request; see :ref:`AI as a Service`) - Image generation ^^^^^^^^^^^^^^^^ @@ -141,18 +167,17 @@ Frontend apps ~~~~~~~~~~~~~ * `Assistant `_ for offering a graphical UI and a smart picker -* `Text-to-Image Helper `_ for providing a Text-to-Image smart picker (deprecated; was merged into assistant) Backend apps ~~~~~~~~~~~~ -* text2image_stablediffusion2 (Customer support available upon request) -* *integration_openai* - Integrates with the OpenAI API to provide AI functionality from OpenAI servers (Customer support available upon request; see :ref:`AI as a Service`) +* text2image_stablediffusion (Customer support available upon request) +* `OpenAI and LocalAI integration (via OpenAI API) `_ - Integrates with the OpenAI API to provide AI functionality from OpenAI servers (Customer support available upon request; see :ref:`AI as a Service`) * *integration_replicate* - Integrates with the replicate API to provide AI functionality from replicate servers (see :ref:`AI as a Service`) -Context Chat (Tech preview) -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Context Chat +^^^^^^^^^^^^ Our Context Chat feature was introduced in Nextcloud Hub 7 (v28). It allows asking questions to the assistant related to your documents in Nextcloud. You will need to install both the context_chat app as well as the context_chat_backend External App. Be prepared that things might break or be a little rough around the edges. We look forward to your feedback! Frontend apps @@ -165,6 +190,97 @@ Backend apps * :ref:`context_chat + context_chat_backend` - (Customer support available upon request) +Provider apps +~~~~~~~~~~~~~ + +Apps can integrate their content with Context Chat to make it available for querying using Context Chat. The following apps have implemented this integration so far: + +* *files* +* `Analytics `_ + +.. _ai-overview_improve-ai-task-pickup-speed: + +Improve AI task pickup speed +---------------------------- + +Most AI tasks will be run as part of the background job system in Nextcloud which only runs jobs every 5 minutes by default. +To pick up scheduled jobs faster you can set up background job workers inside your Nextcloud main server/container that process AI tasks as soon as they are scheduled. +If the PHP code or the Nextcloud settings values are changed while a worker is running, those changes won't be effective inside the runner. For that reason, the worker needs to be restarted regularly. It is done with a timeout of N seconds which means any changes to the settings or the code will be picked up after N seconds (worst case scenario). This timeout does not, in any way, affect the processing or the timeout of the AI tasks. + +Screen or tmux session +^^^^^^^^^^^^^^^^^^^^^^ + +Run the following occ command inside a screen or a tmux session, preferably 4 or more times for parallel processing of multiple requests by different or the same user (and as a requirement for some apps like context_chat). +It would be best to run one command per screen session or per tmux window/pane to keep the logs visible and the worker easily restartable. + +.. code-block:: + + set -e; while true; do sudo -u www-data occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done + +For Nextcloud-AIO you should use this command on the host server. + +.. code-block:: + + set -e; while true; do docker exec -u www-data -it nextcloud-aio-nextcloud php occ background-job:worker -v -t 60 "OC\TaskProcessing\SynchronousBackgroundJob"; done + +You may want to adjust the number of workers and the timeout (in seconds) to your needs. +The logs of the worker can be checked by attaching to the screen or tmux session. + +Systemd service +^^^^^^^^^^^^^^^ + +1. Create a systemd service file in ``/etc/systemd/system/nextcloud-ai-worker@.service`` with the following content: + +.. code-block:: + + [Unit] + Description=Nextcloud AI worker %i + After=network.target + + [Service] + ExecStart=/opt/nextcloud-ai-worker/taskprocessing.sh %i + Restart=always + StartLimitInterval=60 + StartLimitBurst=10 + + [Install] + WantedBy=multi-user.target + +2. Create a shell script in ``/opt/nextcloud-ai-worker/taskprocessing.sh`` with the following content and make sure to make it executable: + +.. code-block:: + + #!/bin/sh + echo "Starting Nextcloud AI Worker $1" + cd /path/to/nextcloud + sudo -u www-data php occ background-job:worker -t 60 'OC\TaskProcessing\SynchronousBackgroundJob' + +You may want to adjust the timeout to your needs (in seconds). + +3. Enable and start the service 4 or more times: + +.. code-block:: + + for i in {1..4}; do systemctl enable --now nextcloud-ai-worker@$i.service; done + +The status of the workers can be checked with (replace 1 with the worker number): + +.. code-block:: + + systemctl status nextcloud-ai-worker@1.service + +The list of workers can be checked with: + +.. code-block:: + + systemctl list-units --type=service | grep nextcloud-ai-worker + +The complete logs of the workers can be checked with (replace 1 with the worker number): + +.. code-block:: + + journalctl -xeu nextcloud-ai-worker@1.service -f + Frequently Asked Questions -------------------------- diff --git a/admin_manual/apps_management.rst b/admin_manual/apps_management.rst index 74b91c4cb..b37e0071b 100644 --- a/admin_manual/apps_management.rst +++ b/admin_manual/apps_management.rst @@ -21,9 +21,9 @@ During the Nextcloud server installation, some apps are enabled by default. To see which apps are enabled go to your Apps page. Those apps are supported and developed by Nextcloud GmbH directly and -have an **Featured**-tag. See :doc:`installation/apps_supported` for a list of supported apps. +have an **Featured**-tag. -.. note:: Your Nextcloud server needs to be able to communicate with +.. note:: Your Nextcloud server needs to be able to communicate with ``https://apps.nextcloud.com`` to list and download apps. Please make sure to whitelist this target in your firewall or proxy if necessary. .. note:: To get access to work-arounds, long-term-support, priority bug fixing @@ -55,11 +55,11 @@ in the Application View field. Clicking the **Enable** button will enable the ap If the app is not part of the Nextcloud installation, it will be downloaded from the app store, installed and enabled. -App updates will also be offered to you on this page. Simply click on the **Update** -button to update a specific app or use the **Update all** button on top of the page to +App updates will also be offered to you on this page. Simply click on the **Update** +button to update a specific app or use the **Update all** button on top of the page to update all apps. -.. note:: **Beta releases**: You can also install beta releases of apps directly from here by +.. note:: **Beta releases**: You can also install beta releases of apps directly from here by switching your Nextcloud to the beta channel in the admin overview. Update notifications @@ -81,6 +81,38 @@ By default guest users, when using the guests app, are not notified, to enable n occ config:app:set --type boolean --value="true" updatenotification app_updated.notify_guests +Enabling apps via occ command +----------------------------- + +In addition to managing apps via the web interface, administrators can also enable or disable apps using the `occ` command. + +To enable an app, use the following command: + +:: + + occ app:enable + +For example, to enable the "files" app, run: + +:: + + occ app:enable files + +To enable the app for specific groups, use the `--groups` option: + +:: + + occ app:enable files --groups=admin + + +This command enables the "files" app only for the "admin" group. + +To disable an app, use: + +:: + + occ app:disable + Using private API ----------------- @@ -96,7 +128,7 @@ folder. The key **url** defines the HTTP web path to that folder, starting at the Nextcloud web root. The key **writable** indicates if a user can install apps in that folder. -Example: To ensure that the default ``/apps/`` folder only contains apps shipped +Example: To ensure that the default ``/apps/`` folder only contains apps shipped with Nextcloud, follow this example to setup an ``/extra-apps/`` folder which will be used to store any additional apps you install: @@ -116,14 +148,14 @@ which will be used to store any additional apps you install: ], .. danger:: Make sure that the values you choose for ``path`` and ``url`` for any custom - apps directories do not conflict with directories which already exist in your Nextcloud + apps directories do not conflict with directories which already exist in your Nextcloud Server root (installation directory). .. tip:: Apps paths can be located outside the server root. However, for any **path** outside the server root, you need to create a symbolic link in the server root that points **url** to **path**. For instance, if **path** is - ``/var/local/lib/nextcloud/extra-apps``, and **url** is ``/extra-apps``, then - you would use the command ``ln`` to create the symbolic link like this: + ``/var/local/lib/nextcloud/extra-apps``, and **url** is ``/extra-apps``, then + you would use the command ``ln`` to create the symbolic link like this: ``ln -sf /var/local/lib/nextcloud/extra-apps ./extra-apps`` Using a self hosted apps store @@ -147,6 +179,6 @@ To enable a self hosted apps store: "appstoreurl" => "https://my.appstore.instance/v1", -By default the apps store is enabled and configured to use ``https://apps.nextcloud.com/api/v1`` as apps store url. Nextcloud will fetch ``apps.json`` and ``categories.json`` from there. To use the defaults again remove **appstoreenabled** and **appstoreurl** from the configuration. +By default the apps store is enabled and configured to use ``https://apps.nextcloud.com/api/v1`` as apps store url. Nextcloud will fetch ``apps.json`` and ``categories.json`` from there. To use the defaults again remove **appstoreenabled** and **appstoreurl** from the configuration. Example: If ``categories.json`` is available at ``https://apps.nextcloud.com/api/v1/categories.json`` the apps store url is ``https://apps.nextcloud.com/api/v1``. diff --git a/admin_manual/conf.py b/admin_manual/conf.py index 1a469042a..1250689f0 100644 --- a/admin_manual/conf.py +++ b/admin_manual/conf.py @@ -32,7 +32,7 @@ from conf import * extensions += ['sphinx.ext.todo', 'rst2pdf.pdfbuilder', 'sphinx.ext.intersphinx'] # Add any paths that contain templates here, relative to this directory. -templates_path = ['../_shared_assets/templates'] +templates_path = ['../_shared_assets/templates', '_templates'] # The suffix of source filenames. source_suffix = '.rst' @@ -52,6 +52,8 @@ master_doc = 'contents' # The full version, including alpha/beta/rc tags. #release = '12' +language = 'en' + # General information about the project. project = u'Nextcloud %s Administration Manual' % (version) #copyright = u'2012-2017, The Nextcloud developers' diff --git a/admin_manual/configuration_database/db_conversion.rst b/admin_manual/configuration_database/db_conversion.rst index 6df0b2c0f..ae9977170 100644 --- a/admin_manual/configuration_database/db_conversion.rst +++ b/admin_manual/configuration_database/db_conversion.rst @@ -37,7 +37,7 @@ The ``occ db:convert-type`` command handles all the tasks of the conversion. The php occ db:convert-type [options] type username hostname database ``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 PostgresSQL, or ``oci`` for Oracle. +``pgsql`` for PostgreSQL, or ``oci`` for Oracle. The options: diff --git a/admin_manual/configuration_database/linux_database_configuration.rst b/admin_manual/configuration_database/linux_database_configuration.rst index 3879f8d6e..0cef1e044 100644 --- a/admin_manual/configuration_database/linux_database_configuration.rst +++ b/admin_manual/configuration_database/linux_database_configuration.rst @@ -18,7 +18,7 @@ Requirements * Decide whether you wish to use MySQL / MariaDB, PostgreSQL, or Oracle as your database * Pick a recommendeded version of your database by checking the Nextcloud :doc:`System Requirements <../installation/system_requirements>` -* Install and set up the chosen database server software (and preferrred version) before deploying Nextcloud Server +* Install and set up the chosen database server software (and preferred version) before deploying Nextcloud Server .. note:: The steps for configuring a third party database are beyond the scope of this document. Please refer to the documentation for your specific @@ -208,7 +208,7 @@ like this: extension=pdo_pgsql.so extension=pgsql.so - [PostgresSQL] + [PostgreSQL] pgsql.allow_persistent = On pgsql.auto_reset_persistent = Off pgsql.max_persistent = -1 diff --git a/admin_manual/configuration_files/big_file_upload_configuration.rst b/admin_manual/configuration_files/big_file_upload_configuration.rst index f83a15ba4..0d7818cde 100644 --- a/admin_manual/configuration_files/big_file_upload_configuration.rst +++ b/admin_manual/configuration_files/big_file_upload_configuration.rst @@ -1,3 +1,5 @@ +.. _uploading_big_files: + =========================== Uploading big files > 512MB =========================== @@ -89,7 +91,7 @@ Apache with mod_proxy_fcgi nginx ^^^^^ * `client_max_body_size `_ -* `fastcgi_read_timeout `_ +* `fastcgi_read_timeout `_ [often the solution to 504 timeouts during ``MOVE`` transactions that occur even when using chunking] * `client_body_temp_path `_ Since nginx 1.7.11 a new config option `fastcgi_request_buffering @@ -150,17 +152,18 @@ low. This setting needs to be configured to at least the time (in seconds) that the longest upload will take. If unsure remove this completely from your configuration to reset it to the default shown in the ``config.sample.php``. +.. _files_configure_max_chunk_size: Adjust chunk size on Nextcloud side ----------------------------------- For upload performance improvements in environments with high upload bandwidth, the server's upload chunk size may be adjusted:: - sudo -u www-data php occ config:app:set files max_chunk_size --value 20971520 + sudo -u www-data php occ config:system:set --type int --value 20971520 files.chunked_upload.max_size Put in a value in bytes (in this example, 20MB). Set ``--value 0`` for no chunking at all. -Default is 10485760 (10 MiB). +Default is ``104857600`` (100 MiB). .. note:: Changing ``max_chunk_size`` will not have any performance impact on files uploaded through File Drop shares as unauthenticated file uploads are not chunked. @@ -174,6 +177,8 @@ to the actual file on the Nextcloud servers temporary directory. It is recommend the size of your temp directory accordingly and also ensure that request timeouts are high enough for PHP, webservers or any load balancers involved. +.. TODO ON RELEASE: Update version number above on release + .. tip:: In more recent versions of Nextcloud Server, when uploading to S3 in *Primary Storage* mode, we use S3 `MultipartUpload`. This allows chunked upload streaming of the chunks directly to S3 so that the final MOVE request no longer needs to assemble the final file on the Nextcloud server. This requires your ``memcache.distributed`` to be set to use Redis (or Memcached), otherwise we fall back on the prior behavior which consumes space on the Nextcloud Server for file assembly (as described above). Federated Cloud Sharing diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index cb3a13612..8c210e44b 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -79,6 +79,14 @@ the Nextcloud Web interface. If you lose your encryption keys your files are not recoverable. Always have backups of your encryption keys stored in a safe location, and consider enabling all recovery options. +Please be aware that a `master key` is generated during enabling the encryption. +This ensures that admin(s) can recover passwords and installed Nextcloud apps can +function properly. +If you do not want to use a master key setup, but wish to use user key encryption +instead, please run the following command before enabling the encryption:: + + occ encryption:disable-master-key + You have more options via the ``occ`` command (see :ref:`occ_encryption_label`) .. _enable_encryption_label: diff --git a/admin_manual/configuration_files/encryption_details.rst b/admin_manual/configuration_files/encryption_details.rst index 267cc4b34..763a60472 100644 --- a/admin_manual/configuration_files/encryption_details.rst +++ b/admin_manual/configuration_files/encryption_details.rst @@ -21,12 +21,12 @@ These conventions apply throughout this document: Key type: master key -------------------- -This is the default encryption mode in Nextcloud. With master key encryption enabled there is one central key that is used to secure the files handled by Nextcloud. The master key is protected by a password that can be generated by the server administrator. The advantage of the master key encryption is that the encryption is transparent to the users but has the disadvantage that the server administrator is able to decrypt user files without knowing any user password. +This is the default encryption mode in Nextcloud. With master key encryption enabled there is one central key that is used to secure the files handled by Nextcloud. The master key is protected by the instance `secret` that is generated at installation time. The advantage of the master key encryption is that the encryption is transparent to the users but has the disadvantage that the server administrator is able to decrypt user files without knowing any user password. Key type: public sharing key ---------------------------- -The public sharing key is used to secure files that have been publicly shared. The public sharing key is protected by a password that can be generated by the server administrator. The advantage of the public sharing key is that it is independent of the selected encryption mode so that Nextcloud is able to provide publicly shared files to outside parties. +The public sharing key is used to secure files that have been publicly shared. The advantage of the public sharing key is that it is independent of the selected encryption mode so that Nextcloud is able to provide publicly shared files to outside parties. Key type: recovery key ---------------------- @@ -345,9 +345,9 @@ Each block is (by default) AES-256-CTR decrypted with the ``$iv[$position]`` and Sources ------- -- `nextcloud-tools repository on GitHub `_ +- `encryption-recovery-tools repository on GitHub `_ - `Nextcloud Encryption Configuration documentation `_ -- `Nextcloud Help response concering the usage of version information `_ +- `Nextcloud Help response concerning the usage of version information `_ - `Sourcecode: Creation of the Message Authentication Code `_ - `Sourcecode: Derivation of the Encryption Key `_ - `Sourcecode: Encryption of the File `_ diff --git a/admin_manual/configuration_files/external_storage/amazons3.rst b/admin_manual/configuration_files/external_storage/amazons3.rst index b351672d9..0c09f294e 100644 --- a/admin_manual/configuration_files/external_storage/amazons3.rst +++ b/admin_manual/configuration_files/external_storage/amazons3.rst @@ -42,6 +42,8 @@ access your S3 mount. 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. + .. figure:: images/amazons3.png :alt: diff --git a/admin_manual/configuration_files/external_storage/images/amazons3.png b/admin_manual/configuration_files/external_storage/images/amazons3.png index 7c552ae78..8944fa936 100644 Binary files a/admin_manual/configuration_files/external_storage/images/amazons3.png and b/admin_manual/configuration_files/external_storage/images/amazons3.png differ diff --git a/admin_manual/configuration_files/external_storage/sftp.rst b/admin_manual/configuration_files/external_storage/sftp.rst index d15675648..e8b5cd8ed 100644 --- a/admin_manual/configuration_files/external_storage/sftp.rst +++ b/admin_manual/configuration_files/external_storage/sftp.rst @@ -5,9 +5,7 @@ SFTP Nextcloud's SFTP (SSH File Transfer Protocol) backend supports both password and public key authentication. -The **Host** field is required; a port can be specified as part of the **Host** -field in the following format: ``hostname.domain:port``. The default port is 22 -(SSH). +The **Host** field is required. The default port is 22 (SSH). For public key authentication, you can generate a public/private key pair from your **SFTP with secret key login** configuration. diff --git a/admin_manual/configuration_files/external_storage_configuration_gui.rst b/admin_manual/configuration_files/external_storage_configuration_gui.rst index 246acc22d..ad38f0a5e 100644 --- a/admin_manual/configuration_files/external_storage_configuration_gui.rst +++ b/admin_manual/configuration_files/external_storage_configuration_gui.rst @@ -93,7 +93,7 @@ individually with the following options: * Previews * Enable Sharing * Filesystem check frequency (Never, Once per direct access) -* Mac NFD Compatability +* Mac NFD Compatibility * Read Only The **Encryption** checkbox is visible only when the Encryption app is enabled. Note that server-side @@ -159,6 +159,6 @@ changed remotely (files changed without going through Nextcloud), especially when it's very deep in the folder hierarchy of the external storage. You might need to setup a cron job that runs ``sudo -u www-data php occ files:scan --all`` -(or replace ``--all`` with the user name, see also :doc:`../configuration_server/occ_command`) +(or replace ``--all`` with the user name, see also :doc:`../occ_command`) to trigger a rescan of the user's files periodically (for example every 15 minutes), which includes the mounted external storage. diff --git a/admin_manual/configuration_files/file_conversion.rst b/admin_manual/configuration_files/file_conversion.rst new file mode 100644 index 000000000..c426a282c --- /dev/null +++ b/admin_manual/configuration_files/file_conversion.rst @@ -0,0 +1,7 @@ +=============== +File conversion +=============== + +In the majority of cases, it is recommended that either the Pandoc or :doc:`Nextcloud Office <../office/installation>` apps +are enabled, as they provide the majority of file conversions available. Other apps may also +support their own file conversions for other file types if more specific conversions are required. diff --git a/admin_manual/configuration_files/file_sharing_configuration.rst b/admin_manual/configuration_files/file_sharing_configuration.rst index e04ef5987..e42ec0931 100644 --- a/admin_manual/configuration_files/file_sharing_configuration.rst +++ b/admin_manual/configuration_files/file_sharing_configuration.rst @@ -172,7 +172,7 @@ Trashbin contents are not transferred:: occ files:transfer-ownership user1 user2 -(See :doc:`../configuration_server/occ_command` for a complete ``occ`` +(See :doc:`../occ_command` for a complete ``occ`` reference.) Users may also transfer files or folders selectively by themselves. diff --git a/admin_manual/configuration_files/files_locking_transactional.rst b/admin_manual/configuration_files/files_locking_transactional.rst index 2e4fc4edc..43f42b062 100644 --- a/admin_manual/configuration_files/files_locking_transactional.rst +++ b/admin_manual/configuration_files/files_locking_transactional.rst @@ -49,7 +49,7 @@ recommended if Redis is running on the same system as Nextcloud) use this exampl 'memcache.locking' => '\OC\Memcache\Redis', 'redis' => array( - 'host' => '/var/run/redis/redis.sock', + 'host' => '/run/redis/redis-server.sock', 'port' => 0, 'timeout' => 0.0, ), diff --git a/admin_manual/configuration_files/index.rst b/admin_manual/configuration_files/index.rst index ed3be1ddc..f21f79392 100644 --- a/admin_manual/configuration_files/index.rst +++ b/admin_manual/configuration_files/index.rst @@ -20,3 +20,4 @@ File sharing and management previews_configuration file_versioning trashbin_configuration + file_conversion diff --git a/admin_manual/configuration_files/previews_configuration.rst b/admin_manual/configuration_files/previews_configuration.rst index 3e267f97e..b674e9e99 100644 --- a/admin_manual/configuration_files/previews_configuration.rst +++ b/admin_manual/configuration_files/previews_configuration.rst @@ -16,12 +16,13 @@ By default, Nextcloud can generate previews for the following filetypes: * Cover of MP3 files * Text documents -.. note:: Technically Nextcloud can also generate the previews - of other file types such as PDF, SVG or various office documents. - Due to security concerns those providers have been disabled by - default and are considered unsupported. - While those providers are still available, we discourage enabling - them, and they are not documented. +.. 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`` + :doc:`configuration parameter `. Parameters ---------- @@ -32,6 +33,9 @@ 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. +After changing one or more of the following parameters, you might want to run the ``preview:cleanup`` occ command to get rid of the previews with obsolete settings. +See :ref:`occ_cleanup_previews` to learn more. + Disabling previews: ^^^^^^^^^^^^^^^^^^^ @@ -106,3 +110,18 @@ Default JPEG quality setting for preview images is '80'. Change this with: :: occ config:app:set preview jpeg_quality --value="60" + +Maximum memory for image generation: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, Nextcloud generates image previews using the GD Graphics Library. +This configuration option limits the amount of memory that is allowed for preview generation. +If creating the preview image would allocate more memory than the limit, +preview generation will be disabled and the default mimetype icon is shown. + +Default limit is 256 MB. Set to ``-1`` for no limit. + +:: + + 256, diff --git a/admin_manual/configuration_files/primary_storage.rst b/admin_manual/configuration_files/primary_storage.rst index f96d1c4a0..7b311e678 100644 --- a/admin_manual/configuration_files/primary_storage.rst +++ b/admin_manual/configuration_files/primary_storage.rst @@ -195,6 +195,8 @@ Optional parameters less commonly needing adjustment: * :code:`timeout` defaults to :code:`15` * :code:`uploadPartSize` defaults to :code:`524288000` * :code:`putSizeLimit` defaults to :code:`104857600` +* :code:`useMultipartCopy` defaults to :code:`true` +* :code:`copySizeLimit` defaults to :code:`5242880000` * :code:`legacy_auth` has no default * :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.] diff --git a/admin_manual/configuration_files/trashbin_configuration.rst b/admin_manual/configuration_files/trashbin_configuration.rst index 7d199ebce..2b71abdc5 100644 --- a/admin_manual/configuration_files/trashbin_configuration.rst +++ b/admin_manual/configuration_files/trashbin_configuration.rst @@ -5,6 +5,12 @@ Deleted Items (trash bin) If the trash bin app is enabled (default), this setting defines the policy for when files and folders in the trash bin will be permanently deleted. +.. note:: + + If the user quota limit is exceeded due to deleted files in the trash bin, + retention settings will be ignored and files will be cleaned up until + the quota requirements are met. + The app allows for two settings, a minimum time for trash bin retention, and a maximum time for trash bin retention. Minimum time is the number of days a file will be kept, after which it @@ -15,7 +21,7 @@ file and folder deletion. For migration purposes, this setting is installed initially set to "auto", which is equivalent to the default setting in Nextcloud. -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:: 'trashbin_retention_obligation' => 'auto', @@ -41,11 +47,11 @@ Available values: Background job -------------- -To permanently delete files a background jobs runs every 30 minutes. +To permanently delete files 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_trashbin background_job_expire_trash`` Activate background job: ``occ config:app:delete files_trashbin background_job_expire_trash`` -Expire versions: ``occ trashbin:expire`` or ``occ trashbin:expire --quiet`` (without the progress bar) \ No newline at end of file +Expire versions: ``occ trashbin:expire`` or ``occ trashbin:expire --quiet`` (without the progress bar) diff --git a/admin_manual/configuration_mimetypes/index.rst b/admin_manual/configuration_mimetypes/index.rst index b0d835895..8b47f2e40 100644 --- a/admin_manual/configuration_mimetypes/index.rst +++ b/admin_manual/configuration_mimetypes/index.rst @@ -25,7 +25,7 @@ Ubuntu Linux:: # you may also need to update the mimetype for existing files, see nextcloud/server#30566 $ sudo -u www-data php occ maintenance:mimetype:update-db --repair-filecache -See :doc:`../configuration_server/occ_command` to learn more about ``occ``. +See :doc:`../occ_command` to learn more about ``occ``. Some common mimetypes that may be useful in creating aliases are: diff --git a/admin_manual/configuration_server/activity_configuration.rst b/admin_manual/configuration_server/activity_configuration.rst index ece070c29..90874cd0e 100644 --- a/admin_manual/configuration_server/activity_configuration.rst +++ b/admin_manual/configuration_server/activity_configuration.rst @@ -72,3 +72,19 @@ To implement the samples mentioned above, the following three entries are necess If you want to manually send out all activity emails which are queued, you can run ``occ activity:send-mails`` without any argument. + +Excluding users from the activity expiration +-------------------------------------------- + +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 +exclude these users from expiration:: + + 'activity_expire_exclude_users' => [ + 'admin', + 'group_admin', + 'second_admin' + ] + +For these users, their activity records will never deleted from the database. \ No newline at end of file diff --git a/admin_manual/configuration_server/admin_delegation_configuration.rst b/admin_manual/configuration_server/admin_delegation_configuration.rst index 564222eca..01784d73f 100644 --- a/admin_manual/configuration_server/admin_delegation_configuration.rst +++ b/admin_manual/configuration_server/admin_delegation_configuration.rst @@ -5,40 +5,43 @@ Administration privileges (Delegation) Introduction ~~~~~~~~~~~~ -Nextcloud has built-in functionality which permits administrators to delegate authority -to others without granting them full administration privileges (and without making -them a member of the ``admin`` group). +Nextcloud has built-in functionality which permits administrators to delegate authority +to others without granting them full administration privileges (and without making +them a member of the ``admin`` group). -This administration privilege delegation functionality is supported by many shipped and +This administration privilege delegation functionality is supported by many shipped and ecosystem apps that have their own settings areas under *Administration settings*. .. note:: If you're an app developer and would like administrators to be able to utilize this - functionality for your app, you need to enable support for delegation of your settings (see + functionality for your app, you need to enable support for delegation of your settings (see the Developer Manual for specifics). -.. tip:: Delegation of user management isn't handled here, but through the use of +.. tip:: Delegation of user management is possible, but you can also use :doc:`Group Administrators <../configuration_user/user_configuration>`. +.. warning:: Delegation of user management allow the delegated users to add themselves to groups + receiving delegation of other settings. This can be used to escalate privileges. + Usage ~~~~~ -By default only members of the ``admin`` group can access *Administration settings*. You can -create additional user groups (or use existing ones) and then grant these groups access to specific +By default only members of the ``admin`` group can access *Administration settings*. You can +create additional user groups (or use existing ones) and then grant these groups access to specific settings. -While logged in to an account that is a member of the ``admin`` group, go to -*Administration settings* -> *Administration privilege*. You will be presented with the list of +While logged in to an account that is a member of the ``admin`` group, go to +*Administration settings* -> *Administration privilege*. You will be presented with the list of settings pages and sections, including for any installed apps, that support delegation. .. figure:: images/admin-right.png -By clicking on the combo box, you will be able to choose which groups are able to access the -selected settings. You can revoke access at any time by removing the group from the selection -(or, if you wish only to revoke access for an individual account, by removing that account from +By clicking on the combo box, you will be able to choose which groups are able to access the +selected settings. You can revoke access at any time by removing the group from the selection +(or, if you wish only to revoke access for an individual account, by removing that account from the configured group). .. tip:: - Not every settings page or section supports delegation. This is either because delegating - access to that particular settings page would enable privilege escalation (i.e. bypassing - of the limited administration authority) or delegation has not yet been implemented for + Not every settings page or section supports delegation. This is either because delegating + access to that particular settings page would enable privilege escalation (i.e. bypassing + of the limited administration authority) or delegation has not yet been implemented for that specific settings page or app. diff --git a/admin_manual/configuration_server/background_jobs_configuration.rst b/admin_manual/configuration_server/background_jobs_configuration.rst index e967a74b2..526945586 100644 --- a/admin_manual/configuration_server/background_jobs_configuration.rst +++ b/admin_manual/configuration_server/background_jobs_configuration.rst @@ -117,8 +117,6 @@ Which returns:: .. note:: On some systems it might be required to call **php-cli** instead of **php**. -.. note:: For some configurations, it might be necessary to append ``--define apc.enable_cli=1`` to the cron command. Please refer to :doc:`./caching_configuration` (section APCu). - .. note:: Please refer to the crontab man page for the exact command syntax. .. _easyCron: https://www.easycron.com/ diff --git a/admin_manual/configuration_server/caching_configuration.rst b/admin_manual/configuration_server/caching_configuration.rst index 1b0bd19cd..1346352a7 100644 --- a/admin_manual/configuration_server/caching_configuration.rst +++ b/admin_manual/configuration_server/caching_configuration.rst @@ -24,7 +24,7 @@ needs. The supported caching backends are: * `APCu `_, APCu 4.0.6 and up required. A local cache for systems. -* `Redis `_, PHP module 2.2.6 and up required. +* `Redis `_, server 4.0.0 and up required. For local and distributed caching, as well as transactional file locking. * `Memcached `_ For distributed caching. @@ -116,10 +116,23 @@ After restarting your Web server, add this line to your ``config.php`` file:: Refresh your Nextcloud admin page, and the cache warning should disappear. -.. warning:: APCu is disabled by default on CLI which could cause issues with nextcloud's - cron jobs. Please make sure you set the ``apc.enable_cli`` to ``1`` on your ``php.ini`` - config file or append ``--define apc.enable_cli=1`` to the cron job call. +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 +``php.ini``. The default value is 32M which is usually too low for Nextcloud. A +good starting point is 128M. If you have a lot of users and/or a lot of apps +installed you may want to increase this value further. Keep in mind that this +memory needs to be available in your system's memory and kept in mind when +sizing the amount of workers on your server. +A frequently resetting cache can lead to unexpected slow downs when the cache is +being cleared and refilled. + +There is an admin check trying to detect too low memory sizing, but make sure to +monitor the APCu cache status to see if the cache is full and if you need to +increase the size. `APCu provides a script +`_ that can help with this, +otherwise the `serverinfo app `_ in +Nextcloud can also show the APCu cache status. Redis ----- @@ -206,7 +219,7 @@ The following options are available to configure when using a redis cluster (all 'dbindex' => 0, ], -.. note:: The port is required as part of the server URL. However, it is not necesarry to list all servers: for example, if all servers are load balanced via the same DNS name, only that server name is required. +.. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/admin_manual/configuration_server/config_sample_php_parameters.rst b/admin_manual/configuration_server/config_sample_php_parameters.rst index da5b61cb4..4b232c9d6 100644 --- a/admin_manual/configuration_server/config_sample_php_parameters.rst +++ b/admin_manual/configuration_server/config_sample_php_parameters.rst @@ -2,27 +2,205 @@ Configuration Parameters ======================== -Nextcloud uses the ``config/config.php`` file to control server operations. -``config/config.sample.php`` lists all the configurable parameters within -Nextcloud, along with example or default values. This document provides a more -detailed reference. Most options are configurable on your Admin page, so it -is usually not necessary to edit ``config/config.php``. +Introduction +------------ -.. note:: The installer creates a configuration containing the essential parameters. - Only manually add configuration parameters to ``config/config.php`` if you need to - use a special value for a parameter. **Do not copy everything from** - ``config/config.sample.php`` **. Only enter the parameters you wish to modify!** +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. -Multiple config.php file ------------------------- +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 +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 + settings are managed elsewhere and thus not included in it. These settings are typically + managed via individual apps. + +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 +sixty seconds in many pre-packaged Nextcloud installation methods). + +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 + ``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 + 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 +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 administartors 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 +arrays themselves). Each pair has the form ``key => value`` and is comma-separated. + +Types of Values +^^^^^^^^^^^^^^^ + +Strings: + +* ``"thisIsAnImportantValue"`` +* Note: These must be either single or double quoted - i.e. ``"string"`` or ``'string'``. +* Note: IP addresses are considered strings. +* Examples: + - ``'logo_url' => 'https://example.org',`` + - ``'versions_retention_obligation' => 'auto, D',`` + - ``'logtimezone' => 'Europe/Berlin',`` + +Boolean: + +* ``true`` or ``false`` +* Note: These should **not** be surrounded by quote marks within the configuration file itself. +* Examples: + - ``'session_keepalive' => true,`` + - ``'hide_login_form' => false,`` + +Numerical: + +* ``12`` +* This includes both integers and floating point numbers. +* Note: These should **not** be surrounded by quote marks within the configuration file itself. +* Examples: + - ``'loglevel' => 2,`` + - ``'session_lifetime' => 60 * 60 * 24,`` + +Arrays of any of the above types: + +* ``[ 'value1', 'value2' ]`` +* All value types (including other arrays) can be included in arrays. +* Note: Only some parameters support array style values. +* Examples: + - ``'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 + 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 +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 + 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. + +Defaults +-------- + +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 +and alongside additional context. + +.. 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 + ``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. +These custom files are not overwritten by Nextcloud. + +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 + ``config/config.php``. + +.. 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 + your ``config/config.php`` values! + +Examples +-------- + +These are some examples of the content of typical ``config/config.php`` files immediately after +a basic installation of Nextcloud. + +When you use SQLite as your Nextcloud database, your ``config.php`` looks like +this after installation. The SQLite database is stored in your Nextcloud +``data/`` directory:: + + 'occ6f7365735', + 'passwordsalt' => '2c5778476346786306303', + 'trusted_domains' => + array ( + 0 => 'localhost', + 1 => 'studio', + ), + 'datadirectory' => '/var/www/nextcloud/data', + 'dbtype' => 'sqlite3', + 'version' => '7.0.2.1', + '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, + Oracle, or PosgreSQL. + +This example is from a new Nextcloud installation using MariaDB:: + + 'oc8c0fd71e03', + 'passwordsalt' => '515a13302a6b3950a9d0fdb970191a', + 'trusted_domains' => + array ( + 0 => 'localhost', + 1 => 'studio', + 2 => '192.168.10.155' + ), + 'datadirectory' => '/var/www/nextcloud/data', + 'dbtype' => 'mysql', + 'version' => '7.0.2.1', + 'dbname' => 'nextcloud', + 'dbhost' => 'localhost', + 'dbtableprefix' => 'oc_', + 'dbuser' => 'oc_carla', + 'dbpassword' => '67336bcdf7630dd80b2b81a413d07', + 'installed' => true, + ); -Nextcloud supports loading configuration parameters from multiple files. -You can add arbitrary files ending with :file:`.config.php` in the :file:`config/` -directory, for example you could place your email server configuration -in :file:`email.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, and the values in these files take precedence over :file:`config.php`. .. The following section is auto-generated from .. https://github.com/nextcloud/server/blob/master/config/config.sample.php @@ -261,54 +439,7 @@ Defaults to ``false`` .. DEFAULT_SECTION_END .. Generated content above. Don't change this. -Default config.php Examples ---------------------------- -When you use SQLite as your Nextcloud database, your ``config.php`` looks like -this after installation. The SQLite database is stored in your Nextcloud -``data/`` directory. SQLite is a simple, lightweight embedded database that -is good for testing and for simple installations, but for production Nextcloud -systems you should use MySQL, MariaDB, or PosgreSQL. - -:: - - 'occ6f7365735', - 'passwordsalt' => '2c5778476346786306303', - 'trusted_domains' => - array ( - 0 => 'localhost', - 1 => 'studio', - ), - 'datadirectory' => '/var/www/nextcloud/data', - 'dbtype' => 'sqlite3', - 'version' => '7.0.2.1', - 'installed' => true, - ); - -This example is from a new Nextcloud installation using MariaDB:: - - - 'oc8c0fd71e03', - 'passwordsalt' => '515a13302a6b3950a9d0fdb970191a', - 'trusted_domains' => - array ( - 0 => 'localhost', - 1 => 'studio', - 2 => '192.168.10.155' - ), - 'datadirectory' => '/var/www/nextcloud/data', - 'dbtype' => 'mysql', - 'version' => '7.0.2.1', - 'dbname' => 'nextcloud', - 'dbhost' => 'localhost', - 'dbtableprefix' => 'oc_', - 'dbuser' => 'oc_carla', - 'dbpassword' => '67336bcdf7630dd80b2b81a413d07', - 'installed' => true, - ); +.. _config-php-sample: .. Generated content below. Don't change this. .. ALL_OTHER_SECTIONS_START @@ -375,6 +506,20 @@ login or shared items. User's locale preferences configured under "personal Defaults to ``en`` +reduce_to_languages +^^^^^^^^^^^^^^^^^^^ + + +:: + + 'reduce_to_languages' => [], + +With this setting is possible to reduce the languages available in the +language chooser. The languages have to be set as array values using ISO_639-1 +language codes such as ``en`` for English, ``de`` for German etc. + +For example: Set to ['de', 'fr'] to only allow German and French languages. + default_phone_region ^^^^^^^^^^^^^^^^^^^^ @@ -464,8 +609,9 @@ skeletondirectory 'skeletondirectory' => '/path/to/nextcloud/core/skeleton', The directory where the skeleton files are located. These files will be -copied to the data directory of new users. Leave empty to not copy any -skeleton files. +copied to the data directory of new users. Set empty string to not copy any +skeleton files. If unset and templatedirectory is empty string, shipped +templates will be used to create a template directory for the user. ``{lang}`` can be used as a placeholder for the language of the user. If the directory does not exist, it falls back to non dialect (from ``de_DE`` @@ -482,16 +628,15 @@ templatedirectory 'templatedirectory' => '/path/to/nextcloud/templates', The directory where the template files are located. These files will be -copied to the template directory of new users. Leave empty to not copy any +copied to the template directory of new users. Set empty string to not copy any template files. ``{lang}`` can be used as a placeholder for the language of the user. If the directory does not exist, it falls back to non dialect (from ``de_DE`` to ``de``). If that does not exist either, it falls back to ``default`` -If this is not set creating a template directory will only happen if no custom -``skeletondirectory`` is defined, otherwise the shipped templates will be used -to create a template directory for the user. +To disable creating a template directory, set both skeletondirectory and +templatedirectory to empty strings. User session ------------ @@ -535,6 +680,18 @@ davstorage.request_timeout The timeout in seconds for requests to servers made by the DAV component (e.g., needed for federated shares). +carddav_sync_request_timeout +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'carddav_sync_request_timeout' => 30, + +The timeout in seconds for synchronizing address books, e.g. federated system address books (as run by `occ federation:sync-addressbooks`). + +Defaults to ``30`` seconds + session_relaxed_expiry ^^^^^^^^^^^^^^^^^^^^^^ @@ -574,8 +731,10 @@ auto_logout 'auto_logout' => false, Enable or disable the automatic logout after session_lifetime, even if session -keepalive is enabled. This will make sure that an inactive browser will be logged out -even if requests to the server might extend the session lifetime. +keepalive is enabled. This will make sure that an inactive browser will log itself out +even if requests to the server might extend the session lifetime. Note: the logout is +handled on the client side. This is not a way to limit the duration of potentially +compromised sessions. Defaults to ``false`` @@ -625,6 +784,22 @@ Disabling this is discouraged for security reasons. Defaults to ``true`` +auth.bruteforce.protection.force.database +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'auth.bruteforce.protection.force.database' => false, + +Whether the brute force protection should write into the database even when a memory cache is available + +Using the database is most likely worse for performance, but makes investigating +issues a lot easier as it's possible to look directly at the table to see all +logged remote addresses and actions. + +Defaults to ``false`` + auth.bruteforce.protection.testing ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -643,6 +818,22 @@ and should only be done for debugging and on CI when running tests. Defaults to ``false`` +auth.bruteforce.max-attempts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'auth.bruteforce.max-attempts' => 10, + +Brute force protection: maximum number of attempts before blocking + +When more than max-attempts login requests are sent to Nextcloud, requests +will abort with "429 Too Many Requests". +For security reasons, change it only if you know what you are doing. + +Defaults to ``10`` + ratelimit.protection.enabled ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -774,6 +965,9 @@ mail_smtpdebug Enable SMTP class debugging. +NOTE: ``loglevel`` will likely need to be adjusted too. See docs: + https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/email_configuration.html#enabling-debug-mode + Defaults to ``false`` mail_smtpmode @@ -784,7 +978,7 @@ mail_smtpmode 'mail_smtpmode' => 'smtp', -Which mode to use for sending mail: ``sendmail``, ``smtp`` or ``qmail``. +Which mode to use for sending mail: ``sendmail``, ``smtp``, ``qmail`` or ``null``. If you are using local or remote SMTP, set this to ``smtp``. @@ -794,6 +988,9 @@ the server, with ``/usr/sbin/sendmail`` installed on your Unix system. For ``qmail`` the binary is /var/qmail/bin/sendmail, and it must be installed on your Unix system. +Use the string ``null`` to send no mails (disable mail delivery). This can be +useful if mails should be sent via APIs and rendering messages is not necessary. + Defaults to ``smtp`` mail_smtphost @@ -1020,6 +1217,9 @@ Use this configuration parameter to specify the base URL for any URLs which are generated within Nextcloud using any kind of command line tools (cron or occ). The value should contain the full base URL: ``https://www.example.com/nextcloud`` +Please make sure to set the value to the URL that your users mainly use to access this Nextcloud. + +Otherwise there might be problems with the URL generation via cron. Defaults to ``''`` (empty string) @@ -1149,6 +1349,10 @@ trashbin_retention_obligation If the trash bin app is enabled (default), this setting defines the policy for when files and folders in the trash bin will be permanently deleted. +If the user quota limit is exceeded due to deleted files in the trash bin, +retention settings will be ignored and files will be cleaned up until +the quota requirements are met. + The app allows for two settings, a minimum time for trash bin retention, and a maximum time for trash bin retention. @@ -1322,10 +1526,10 @@ connectivity_check_domains :: 'connectivity_check_domains' => [ - 'www.nextcloud.com', - 'www.startpage.com', - 'www.eff.org', - '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 @@ -1340,10 +1544,10 @@ If a protocol is provided, only this one will be tested. Defaults to the following domains: - - www.nextcloud.com - - www.startpage.com - - www.eff.org - - www.edri.org + - https://www.nextcloud.com + - https://www.startpage.com + - https://www.eff.org + - https://www.edri.org check_for_working_wellknown_setup ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1568,6 +1772,15 @@ log.condition '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 @@ -1581,6 +1794,9 @@ Supported conditions: this condition is met - ``apps``: if the log message is invoked by one of the specified apps, this condition is met + - ``matches``: if all the conditions inside a group match, + this condition is met. This allows to log only entries to an app + by a few users. Defaults to an empty array. @@ -1686,6 +1902,8 @@ customclient_desktop '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. @@ -1696,6 +1914,7 @@ Defaults to: - Android client: ``https://play.google.com/store/apps/details?id=com.nextcloud.client`` - iOS client: ``https://itunes.apple.com/us/app/nextcloud/id1125420102?mt=8`` - iOS client app id: ``1125420102`` +- F-Droid client: ``https://f-droid.org/packages/com.nextcloud.client/`` Apps ---- @@ -1711,9 +1930,10 @@ defaultapp 'defaultapp' => 'dashboard,files', -Set the default app to open on login. Use the app names as they appear in the -URL after clicking them in the Apps menu, such as documents, calendar, and -gallery. You can use a comma-separated list of app names, so if the first +Set the default app to open on login. The entry IDs can be retrieved from +the Navigations OCS API endpoint: https://docs.nextcloud.com/server/latest/develper_manual/_static/openapi.html#/operations/core-navigation-get-apps-navigation. + +You can use a comma-separated list of app names, so if the first app is not enabled for a user then Nextcloud will try the second one, and so on. If no enabled apps are found it defaults to the dashboard app. @@ -1920,7 +2140,8 @@ preview_ffmpeg_path custom path for ffmpeg binary -Defaults to ``null`` and falls back to searching ``avconv`` and ``ffmpeg`` in the configured ``PATH`` environment +Defaults to ``null`` and falls back to searching ``avconv`` and ``ffmpeg`` +in the configured ``PATH`` environment preview_imaginary_url ^^^^^^^^^^^^^^^^^^^^^ @@ -1932,7 +2153,12 @@ preview_imaginary_url Set the URL of the Imaginary service to send image previews to. -Also requires the ``OC\Preview\Imaginary`` provider to be enabled. +Also requires the ``OC\Preview\Imaginary`` provider to be enabled in the +``enabledPreviewProviders`` array, to create previews for these mimetypes: bmp, +x-bitmap, png, jpeg, gif, heic, heif, svg+xml, tiff, webp and illustrator. + +If you want Imaginary to also create preview images from PDF Documents, you +have to add the ``OC\Preview\ImaginaryPDF`` provider as well. See https://github.com/h2non/imaginary @@ -1999,6 +2225,35 @@ Defaults to the following providers: - ``OC\Preview\TXT`` - ``OC\Preview\XBitmap`` +metadata_max_filesize +^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'metadata_max_filesize' => 256, + +Maximum file size for metadata generation. + +If a file exceeds this size, metadata generation will be skipped. +Note: memory equivalent to this size will be used for metadata generation. + +Default: 256 megabytes. + +max_file_conversion_filesize +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'max_file_conversion_filesize' => 100, + +Maximum file size for file conversion. + +If a file exceeds this size, the file will not be converted. + +Default: 100 MiB + LDAP ---- @@ -2606,6 +2861,20 @@ when running "occ files:transfer-ownership". Defaults to false, so incoming shares are not transferred if not specifically requested by a command line argument. +Federated Cloud Sharing +----------------------- + + +sharing.federation.allowSelfSignedCertificates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'sharing.federation.allowSelfSignedCertificates' => false, + +Allow self-signed certificates for federated shares + Hashing ------- @@ -2837,39 +3106,80 @@ restricted. Defaults to the value of `datadirectory` if unset. If set, the value MUST be located _outside_ of the installation directory of Nextcloud and writable by the Web server user. -blacklisted_files -^^^^^^^^^^^^^^^^^ +forbidden_filenames +^^^^^^^^^^^^^^^^^^^ :: - 'blacklisted_files' => ['.htaccess'], + 'forbidden_filenames' => ['.htaccess'], -Blacklist a specific file or files and disallow the upload of files -with this name. ``.htaccess`` is blocked by default. +Block a specific file or files and disallow the upload of files with this name. + +This blocks any access to those files (read and write). +``.htaccess`` is blocked by default. WARNING: USE THIS ONLY IF YOU KNOW WHAT YOU ARE DOING. +Note that this list is case-insensitive. + Defaults to ``array('.htaccess')`` -forbidden_chars -^^^^^^^^^^^^^^^ +forbidden_filename_basenames +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - 'forbidden_chars' => [], + 'forbidden_filename_basenames' => [], -Blacklist characters from being used in filenames. This is useful if you +Disallow the upload of files with specific basenames. + +Matching existing files can no longer be updated and in matching folders no files can be created anymore. + +The basename is the name of the file without the extension, +e.g. for "archive.tar.gz" the basename would be "archive". + +Note that this list is case-insensitive. + +Defaults to ``array()`` + +forbidden_filename_characters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'forbidden_filename_characters' => [], + +Block characters from being used in filenames. This is useful if you have a filesystem or OS which does not support certain characters like windows. -The '/' and '\' characters are always forbidden. +Matching existing files can no longer be updated and in matching folders no files can be created anymore. -Example for windows systems: ``array('?', '<', '>', ':', '*', '|', '"', chr(0), "\n", "\r")`` +The '/' and '\' characters are always forbidden, as well as all characters in the ASCII range [0-31]. + +Example for windows systems: ``array('?', '<', '>', ':', '*', '|', '"')`` see https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits Defaults to ``array()`` +forbidden_filename_extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'forbidden_filename_extensions' => ['.part', '.filepart'], + +Deny extensions from being used for filenames. + +Matching existing files can no longer be updated and in matching folders no files can be created anymore. + +The '.part' extension is always forbidden, as this is used internally by Nextcloud. + +Defaults to ``array('.filepart', '.part')`` + theme ^^^^^ @@ -2897,6 +3207,18 @@ This must be a valid ITheme ID. E.g. dark, dark-highcontrast, default, light, light-highcontrast, opendyslexic +theming.standalone_window.enabled +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'theming.standalone_window.enabled' => true, + +This setting allows to disable the PWA functionality that allows browsers to open web applications in dedicated windows. + +Defaults to ``true`` + cipher ^^^^^^ @@ -2933,7 +3255,7 @@ minimum.supported.desktop.version :: - 'minimum.supported.desktop.version' => '2.3.0', + 'minimum.supported.desktop.version' => '2.7.0', The minimum Nextcloud desktop client version that will be allowed to sync with this server instance. All connections made from earlier clients will be denied @@ -2944,7 +3266,21 @@ When changing this, note that older unsupported versions of the Nextcloud deskto client may not function as expected, and could lead to permanent data loss for clients or other unexpected results. -Defaults to ``2.3.0`` +Defaults to ``2.7.0`` + +maximum.supported.desktop.version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'maximum.supported.desktop.version' => '99.99.99', + +The maximum Nextcloud desktop client version that will be allowed to sync with +this server instance. All connections made from later clients will be denied +by the server. + +Defaults to ``99.99.99`` localstorage.allowsymlinks ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -3144,6 +3480,21 @@ Nextcloud, bypassing access controls and making logs useless! Defaults to ``'HTTP_X_FORWARDED_FOR'`` +allowed_admin_ranges +^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'allowed_admin_ranges' => ['192.0.2.42/32', '233.252.0.0/24', '2001:db8::13:37/64'], + +List of trusted IP ranges for admin actions + +If this list is non-empty, all admin actions must be triggered from +IP addresses inside theses ranges. + +Defaults to an empty array. + max_filesize_animated_gifs_public_sharing ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -3161,26 +3512,6 @@ no limit. Defaults to ``10`` megabytes -filelocking.enabled -^^^^^^^^^^^^^^^^^^^ - - -:: - - 'filelocking.enabled' => true, - -Enables transactional file locking. - -This is enabled by default. - -Prevents concurrent processes from accessing the same files -at the same time. Can help prevent side effects that would -be caused by concurrent operations. Mainly relevant for -very large installations with many users working with -shared files. - -Defaults to ``true`` - filelocking.ttl ^^^^^^^^^^^^^^^ @@ -3574,10 +3905,76 @@ enable_non-accessible_features 'enable_non-accessible_features' => true, -Enable features that are do respect accessibility standards yet. +Enable features that don't respect accessibility standards yet. Defaults to ``true`` +binary_search_paths +^^^^^^^^^^^^^^^^^^^ + + +:: + + 'binary_search_paths' => [ + '/usr/local/sbin', + '/usr/local/bin', + '/usr/sbin', + '/usr/bin', + '/sbin', + '/bin', + '/opt/bin', + ], + +Directories where nextcloud looks for binaries. + +This is used to find external binaries like libreoffice, sendmail, ffmpeg and more. + +Defaults to ``['/usr/local/sbin','/usr/local/bin','/usr/sbin','/usr/bin','/sbin','/bin','/opt/bin']`` + +files.chunked_upload.max_size +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'files.chunked_upload.max_size' => 100 * 1024 * 1024, + +The maximum chunk size to use for chunked uploads. + +A bigger chunk size results in higher throughput, but above 100 MiB there are only diminishing returns, +while services like Cloudflare already limit to 100 MiB. + +Defaults to 100 MiB. + +files.chunked_upload.max_parallel_count +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +:: + + 'files.chunked_upload.max_parallel_count' => 5, + +The maximum number of chunks uploaded in parallel during chunked uploads. + +A bigger count results in higher throughput, but will also consume more server workers, +while the improvements diminish. + +Defaults to 5. + +files.trash.delete +^^^^^^^^^^^^^^^^^^ + + +:: + + 'files.trash.delete' => true, + +Allow users to manually delete files from their trashbin. + +Automated deletions are not affected and will continue to work in cases like low remaining quota for example. + +Defaults to true. + .. ALL_OTHER_SECTIONS_END .. Generated content above. Don't change this. diff --git a/admin_manual/configuration_server/dashboard_configuration.rst b/admin_manual/configuration_server/dashboard_configuration.rst index 528eaa520..e33c57458 100644 --- a/admin_manual/configuration_server/dashboard_configuration.rst +++ b/admin_manual/configuration_server/dashboard_configuration.rst @@ -28,3 +28,9 @@ The default layout of the dashboard for all users can be set with the following occ config:app:set dashboard layout --value="files,activity,calendar" Changing the default layout will not affect existing users that already have a custom layout stored. + + +It is possible to replace the default app, which is the dashboard app, with a custom app with the following command: + + occ config:app:set core defaultpage --value "/apps/files/extstoragemounts" + diff --git a/admin_manual/configuration_server/email_configuration.rst b/admin_manual/configuration_server/email_configuration.rst index 6ed906ed8..20df49bef 100644 --- a/admin_manual/configuration_server/email_configuration.rst +++ b/admin_manual/configuration_server/email_configuration.rst @@ -33,6 +33,17 @@ Sendmail when your mail server is on the same machine as Nextcloud. .. _email-smtp-config: +Mail Providers +-------------- + +.. versionadded:: 30 + +A mail provider is an app that provides outbound mail service to Nextcloud and allows the sending of system emails +directly through a user's configured personal email account instead of the system email account. +At present, this functionality is limited to calendar invitations. +This feature automatically matches a users email address to a configured mail provider account, when a system message is sent. +The only app that supports this functionality at present is Nextcloud Mail 4.1 or higher, a configured email account is required. + Configuring an SMTP server -------------------------- @@ -43,6 +54,7 @@ connect Nextcloud to a remote SMTP server: * STARTTLS cannot be enforced. It will be used automatically if the mail server supports it. The encryption type should be set to 'None/STARTTLS' in this case. 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. * Encryption type: None/STARTTLS or SSL diff --git a/admin_manual/configuration_server/index.rst b/admin_manual/configuration_server/index.rst index 2ae7558c7..a0ed087b2 100644 --- a/admin_manual/configuration_server/index.rst +++ b/admin_manual/configuration_server/index.rst @@ -7,6 +7,5 @@ Nextcloud configuration :glob: security_setup_warnings - occ_command config_sample_php_parameters * diff --git a/admin_manual/configuration_server/reverse_proxy_configuration.rst b/admin_manual/configuration_server/reverse_proxy_configuration.rst index b39a9e01e..4e5d29248 100644 --- a/admin_manual/configuration_server/reverse_proxy_configuration.rst +++ b/admin_manual/configuration_server/reverse_proxy_configuration.rst @@ -95,10 +95,10 @@ Traefik 2 Using Docker labels: :: - traefik.http.routers.nextcloud.middlewares: 'nextcloud_redirectregex' - traefik.http.middlewares.nextcloud_redirectregex.redirectregex.permanent: true - traefik.http.middlewares.nextcloud_redirectregex.redirectregex.regex: 'https://(.*)/.well-known/(?:card|cal)dav' - traefik.http.middlewares.nextcloud_redirectregex.redirectregex.replacement: 'https://$${1}/remote.php/dav' + - "traefik.http.routers.nextcloud.middlewares=nextcloud_redirectregex@docker" + - "traefik.http.middlewares.nextcloud_redirectregex.redirectregex.permanent=true" + - "traefik.http.middlewares.nextcloud_redirectregex.redirectregex.regex=https://(.*)/.well-known/(?:card|cal)dav" + - "traefik.http.middlewares.nextcloud_redirectregex.redirectregex.replacement=https://$${1}/remote.php/dav" Using a TOML file: :: @@ -118,6 +118,7 @@ HAProxy NGINX ^^^^^ +If using nginx as Nextcloud's webserver from behind another nginx reverse proxy, put this only in the reverse proxy's configuration. :: location /.well-known/carddav { @@ -127,13 +128,13 @@ NGINX location /.well-known/caldav { return 301 $scheme://$host/remote.php/dav; } + + location ^~ /.well-known { + return 301 $scheme://$host/index.php$uri; + } -or - -:: - - rewrite ^/\.well-known/carddav https://$server_name/remote.php/dav/ redirect; - rewrite ^/\.well-known/caldav https://$server_name/remote.php/dav/ redirect; +When using NGINX Proxy Manager, the entry ``proxy_hide_header Upgrade;`` must be added in the *"Advanced Settings"* +of the proxy host under *"Custom Nginx Configuration"*, otherwise mobile devices (iPad, iPhone etc.) will simply receive the Error Message "Connection Closed". Caddy ^^^^^ diff --git a/admin_manual/configuration_server/security_setup_warnings.rst b/admin_manual/configuration_server/security_setup_warnings.rst index a624648a9..66ae66a21 100644 --- a/admin_manual/configuration_server/security_setup_warnings.rst +++ b/admin_manual/configuration_server/security_setup_warnings.rst @@ -77,6 +77,9 @@ For enhanced security we recommend enabling HSTS as described in our security ti The HSTS header needs to be configured within your Web server by following the :ref:`enable-hsts-label` documentation +You can see if the header is appearing in requests by using your browser inspector +or using a tool such as cURL: ``curl --head https://cloud.domain.tld``. + /dev/urandom is not readable by PHP ----------------------------------- @@ -123,10 +126,10 @@ Some files have not passed the integrity check Please refer to the :ref:`code_signing_fix_warning_label` documentation how to debug this issue. -Your database does not run with "READ COMMITED" transaction isolation level ---------------------------------------------------------------------------- +Your database does not run with "READ COMMITTED" transaction isolation level +---------------------------------------------------------------------------- -"Your database does not run with "READ COMMITED" transaction isolation level. +"Your database does not run with "READ COMMITTED" transaction isolation level. This can cause problems when multiple actions are executed in parallel." Please refer to :ref:`db-transaction-label` how to configure your database for this requirement. diff --git a/admin_manual/configuration_server/text_configuration.rst b/admin_manual/configuration_server/text_configuration.rst index 9412ce044..39ba367cf 100644 --- a/admin_manual/configuration_server/text_configuration.rst +++ b/admin_manual/configuration_server/text_configuration.rst @@ -32,11 +32,11 @@ Rich text editing can be turned off globally to always open markdown files in th occ config:app:set text rich_editing_enabled --value=0 - File encodings - -------------- +File encodings +-------------- - Text can automatically detect encodings of files and will convert them to UTF-8 when saving. Due to the variety of encodings, not all of them can be detected, however you can configure a list of encodings and in which priority they should be detected using the php ``mbstring.detect_order`` setting in your php.ini: +Text can automatically detect encodings of files and will convert them to UTF-8 when saving. Due to the variety of encodings, not all of them can be detected, however you can configure a list of encodings and in which priority they should be detected using the php ``mbstring.detect_order`` setting in your php.ini: :: - mbstring.detect_order = ASCII,JIS,UTF-8,SJIS,EUC-JP + mbstring.detect_order = ASCII,JIS,UTF-8,SJIS,EUC-JP diff --git a/admin_manual/configuration_user/authentication.rst b/admin_manual/configuration_user/authentication.rst new file mode 100644 index 000000000..cc2ca16c6 --- /dev/null +++ b/admin_manual/configuration_user/authentication.rst @@ -0,0 +1,28 @@ +.. _authentication: + +============== +Authentication +============== + +App passwords +^^^^^^^^^^^^^ + +App passwords allow users to authenticate multiple client applications against their Nextcloud account without giving the application the login password. App passwords are mandatory for accounts with :ref:`two-factor authentication` enabled. + +Some clients support *remote wipe*, which makes the connected application delete its local data. + +.. _authentication-app-password-clean-up: + +Automated clean-up +****************** + +.. versionadded:: 30 + +Nextcloud will delete unused passwords. Passwords set for *remote wipe* are deleted after 60 days of no usage. App passwords of client applications are deleted after 365 days of no usage. + +The time spans can be overwritten with configuration:: + + php occ config:system:set token_auth_wipe_token_retention --type=int --value 2592000 # 60*60*24*30 - 30 days + 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 diff --git a/admin_manual/configuration_user/index.rst b/admin_manual/configuration_user/index.rst index 7a06f853c..98d54328c 100644 --- a/admin_manual/configuration_user/index.rst +++ b/admin_manual/configuration_user/index.rst @@ -9,9 +9,11 @@ User management reset_admin_password reset_user_password user_password_policy + authentication two_factor-auth user_auth_ldap user_auth_ldap_cleanup user_auth_ldap_api user_provisioning_api profile_configuration + user_auth_oidc diff --git a/admin_manual/configuration_user/instruction_set_for_apps.rst b/admin_manual/configuration_user/instruction_set_for_apps.rst index c928a855c..1e9efbcaf 100644 --- a/admin_manual/configuration_user/instruction_set_for_apps.rst +++ b/admin_manual/configuration_user/instruction_set_for_apps.rst @@ -90,7 +90,7 @@ XML output files Files File Management - AGPL + AGPL-3.0-or-later Robin Appelman 4.9 true diff --git a/admin_manual/configuration_user/instruction_set_for_users.rst b/admin_manual/configuration_user/instruction_set_for_users.rst index 5ffff98e0..183e7b372 100644 --- a/admin_manual/configuration_user/instruction_set_for_users.rst +++ b/admin_manual/configuration_user/instruction_set_for_users.rst @@ -22,16 +22,17 @@ basic HTTP authentication header. Status codes: -* 100 - successful -* 101 - invalid input data -* 102 - username already exists -* 103 - unknown error occurred whilst adding the user +* 101 - invalid argument +* 102 - user already exists +* 103 - cannot create sub-admins for admin group * 104 - group does not exist * 105 - insufficient privileges for group -* 106 - no group specified (required for subadmins) -* 107 - all errors that contain a hint - for example "Password is among the 1,000,000 most common ones. Please make it unique." (this code was added in 12.0.6 & 13.0.1) -* 108 - password and email empty. Must set password or an email -* 109 - invitation email cannot be send +* 106 - no group specified (required for sub-admins) +* 107 - hint exceptions +* 108 - an email address is required, to send a password link to the user. +* 109 - sub-admin group does not exist +* 110 - required email address was not provided +* 111 - could not create non-existing user ID Example ^^^^^^^ @@ -180,9 +181,10 @@ is done by sending a Basic HTTP Authorization header. Status codes: -* 100 - successful -* 101 - user not found -* 102 - invalid input data +* 101 - invalid argument +* 107 - password policy (hint exception) +* 112 - Setting the password is not supported by the users backend +* 113 - editing field not allowed / field doesn’t exist Examples ^^^^^^^^ diff --git a/admin_manual/configuration_user/profile_configuration.rst b/admin_manual/configuration_user/profile_configuration.rst index dda5c4352..48c222617 100644 --- a/admin_manual/configuration_user/profile_configuration.rst +++ b/admin_manual/configuration_user/profile_configuration.rst @@ -13,21 +13,26 @@ disable profile globally to remove all profile functionality. Profile properties are also written into the :ref:`system address book`. +.. note:: If not disabled, the profile is publicly visible. + The visibility of the individual profile attributes can be either controlled + by the assigned visibility scopes (e.g. "Private" will disable public access), + or by the user defined profile visibility. + +Configuration +------------- + To enable or disable profile by default for new users switch the toggle in Basic settings under the Administration settings section. .. figure:: ../images/profile_default_setting.png -.. note:: If you are upgrading from Nextcloud 22 to 23 and want profile to - be disabled by default for all users, you may run the ``occ`` command below - before upgrading or upgrade first then switch the toggle in Basic settings - before letting any users log in. +You may also run the ``occ`` command below instead to change the default to ``false``: :: occ config:app:set settings profile_enabled_by_default --value="0" -Please refer to :doc:`../configuration_server/occ_command` for all available +Please refer to :doc:`../occ_command` for all available ``occ`` commands. To disable profile globally add the following line to your ``config.php`` diff --git a/admin_manual/configuration_user/reset_admin_password.rst b/admin_manual/configuration_user/reset_admin_password.rst index 9bbad3e9b..f3ca77710 100644 --- a/admin_manual/configuration_user/reset_admin_password.rst +++ b/admin_manual/configuration_user/reset_admin_password.rst @@ -12,7 +12,7 @@ The normal ways to recover a lost password are: 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 -using the ``occ`` command. See :doc:`../configuration_server/occ_command` to +using the ``occ`` command. See :doc:`../occ_command` to learn more about using the ``occ`` command. :: diff --git a/admin_manual/configuration_user/user_auth_ldap.rst b/admin_manual/configuration_user/user_auth_ldap.rst index a8995afb7..98770f97b 100644 --- a/admin_manual/configuration_user/user_auth_ldap.rst +++ b/admin_manual/configuration_user/user_auth_ldap.rst @@ -709,7 +709,7 @@ Example usage:: It is also possible to set the admin group mapping using ``occ ldap:set-config $configId ldapAdminGroup $groupId``, but as the Nextcloud -group ID might not be known (yet) it is recommended (especially for automatized +group ID might not be known (yet) it is recommended (especially for automated setups) to use the `promote-group` command, that would also pull in the group and determine the group ID. @@ -777,6 +777,13 @@ The "s01" refers to the configuration ID as can be retrieved per Troubleshooting, tips and tricks -------------------------------- +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 +``loglevel`` to INFO (``1``) or DEBUG (``0``). + SSL certificate verification (LDAPS, TLS) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/admin_manual/configuration_user/user_auth_ldap_cleanup.rst b/admin_manual/configuration_user/user_auth_ldap_cleanup.rst index d003cbb05..23c09e292 100644 --- a/admin_manual/configuration_user/user_auth_ldap_cleanup.rst +++ b/admin_manual/configuration_user/user_auth_ldap_cleanup.rst @@ -42,7 +42,7 @@ 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 -:doc:`../configuration_server/occ_command`. +:doc:`../occ_command`. These examples are for Ubuntu Linux: diff --git a/admin_manual/configuration_user/user_auth_oidc.rst b/admin_manual/configuration_user/user_auth_oidc.rst new file mode 100644 index 000000000..c79b357b6 --- /dev/null +++ b/admin_manual/configuration_user/user_auth_oidc.rst @@ -0,0 +1,40 @@ +======================================= +User authentication with OpenID Connect +======================================= + +Nextcloud users can authenticate via an external identity provider. +Nextcloud can also be an identity provider itself. + +Authentication in Nextcloud +--------------------------- + +The `OpenID Connect user backend app `_ makes it possible for users to +authenticate using external Oidc identity providers. + +This app can optionally be in charge of user provisioning (by creating users when they first connect) or rely on +other user backends and only take care of authentication. + +`More details in the project's README `_ + +Using Nextcloud as an identity provider +--------------------------------------- + +The `OIDC Identity Provider community app `_ +can be installed to make Nextcloud an identity provider for other services. + +This app will allow any Nextcloud user (managed by any user backend) to authenticate during an Oidc login flow. +This is useful if you want your Nextcloud instance to be the authority regarding authentication and user profile data +among multiple services. + +Bearer token validation +----------------------- + +Nextcloud can accept Oidc ID tokens and access tokens as valid bearer token for API requests. +If using an external identity provider, only the ``user_oidc`` app is necessary. + +If Nextcloud is the identity provider, you will naturally need the ``oidc`` app to make Nextcloud an Oidc provider, +and also the ``user_oidc`` app because it will take care of validating API requests authentication. +In user_oidc, the ``oidc_provider_bearer_validation`` config flag needs to be set to true so ``user_oidc`` knows +it needs to ask the ``oidc`` app to validate the received bearer tokens. + +`More details on bearer token validation `_ diff --git a/admin_manual/configuration_user/user_configuration.rst b/admin_manual/configuration_user/user_configuration.rst index 6969b965a..f898a211f 100644 --- a/admin_manual/configuration_user/user_configuration.rst +++ b/admin_manual/configuration_user/user_configuration.rst @@ -18,18 +18,19 @@ On the User management page of your Nextcloud Web UI you can: The default view displays basic information about your users. -.. figure:: ../images/users-config.png +.. figure:: ../images/user-config.png The Group filters on the left sidebar lets you quickly filter users by their group memberships, and create new groups. -.. figure:: ../images/users-config-1.png +.. figure:: ../images/user-config-groups.png Click the gear icon on the lower left sidebar to set a default storage quota, and to display additional fields: **Show storage location, Show last log in, Show user backend, Send email to new users,** and **Show email address**. -.. figure:: ../images/users-config-2.png +.. figure:: ../images/user-config-settings.png + :scale: 75 % User accounts have the following properties: @@ -45,13 +46,20 @@ User accounts have the following properties: The admin sets the new user's first password. Both the user and the admin can change the user's password at anytime. +*Email address* + You can set an email address for a user. + This address can be used when you first set-up an account + so the user receive a mail asking them to create a password if none is provided. + This address can be used for password reset request. + *Groups* You may create groups, and assign group memberships to users. By default new users are not assigned to any groups. *Group Admin* Group admins are granted administrative privileges on specific groups, and - can add and remove users from their groups. + can add and remove users from their groups. This means they can modify the + username, password, email, quota, etc. of members of the group. *Quota* The maximum disk space assigned to each user. Any user that exceeds the quota @@ -73,7 +81,7 @@ To create a user account: * Optionally, assign **Groups** memberships * Click the **Create** button -.. figure:: ../images/users-create.png +.. figure:: ../images/user-config-new-user.png Login names may contain letters (a-z, A-Z), numbers (0-9), dashes (-), underscores (_), periods (.), spaces ( ) and at signs (@). After creating the user, you @@ -127,7 +135,7 @@ system settings, or add or modify users in the groups that they are not **Group Administrators** for. Use the dropdown menus in the **Group Admin** column to assign group admin privileges. -.. figure:: ../images/users-groups.png +.. figure:: ../images/user-config-group-admin.png **Super Administrators** have full rights on your Nextcloud server, and can access and modify all settings. To assign the **Super Administrators** role to @@ -190,7 +198,7 @@ files count against that user's quota. Disable and enable users ------------------------ -.. figure:: ../images/users-actions.png +.. figure:: ../images/user-config-actions.png Sometimes you may want to disable a user without permanently deleting their settings and files. The user can be activated any time again, without data-loss. @@ -214,7 +222,7 @@ select **Enable**. Deleting users -------------- -.. figure:: ../images/users-actions.png +.. figure:: ../images/user-config-actions.png Deleting a user is easy: hover your cursor over their name on the **Users** page until the "..."-menu icon appears at the far right. After clicking on it, you will diff --git a/admin_manual/contents.rst b/admin_manual/contents.rst index 000434abe..3d669fe95 100644 --- a/admin_manual/contents.rst +++ b/admin_manual/contents.rst @@ -10,7 +10,9 @@ Table of contents release_schedule installation/index configuration_server/index + occ_command apps_management + exapps_management/index configuration_user/index configuration_files/index file_workflows/index @@ -18,6 +20,9 @@ Table of contents office/index reference/index ai/index + webhook_listeners/index + windmill_workflows/index + desktop/index configuration_database/index configuration_mimetypes/index maintenance/index diff --git a/admin_manual/desktop/accountcommand.rst b/admin_manual/desktop/accountcommand.rst new file mode 100644 index 000000000..8583c7361 --- /dev/null +++ b/admin_manual/desktop/accountcommand.rst @@ -0,0 +1,20 @@ +========================== +Command-line Account Setup +========================== + +If you want to automate an Account Setup Wizard to allow the user skip entering server URL and local sync folder path in UI, you can use command-line parameters. +When you specify both, the desktop client's Account Setup Wizard will jump straight to opening a browser for account authentication/connection without the need of entering any of the connection details. +The local sync folder will also be selected to the one you specify instead of using default path (/home/Nextcloud) + +The following parameters are supported: + +``--overridelocaldir`` + specify a local dir to be used in the account setup wizard (e.g.: /home/nextcloud-sync-folder) + +``--overrideserverurl`` + specify a server URL to use for the force override to be used in the account setup wizard (e.g.: https://cloud.example.com) + +Examples: + +- ``C:\Program Files\Nextcloud\nextcloud.exe" --overridelocaldir "D:/work/nextcloud-sync-folder" --overrideserverurl https://cloud.example.com`` +- For Linux and mac the same example as above will work but ``nextcloud.exe path`` and ``--overridelocaldir`` value should get changed to platform specific format (e.g. ``no .exe extension`` and ``/home/`` format) diff --git a/admin_manual/desktop/commandline.rst b/admin_manual/desktop/commandline.rst new file mode 100644 index 000000000..070f04bf4 --- /dev/null +++ b/admin_manual/desktop/commandline.rst @@ -0,0 +1,141 @@ +=================== +Command Line Client +=================== + +The Nextcloud Client packages contain a command line client, ``nextcloudcmd``, that can +be used to synchronize Nextcloud files to client machines. + +``nextcloudcmd`` performs a single *sync run* and then exits the synchronization +process. In this manner, ``nextcloudcmd`` processes the differences between +client and server directories and propagates the files to bring both +repositories to the same state. Contrary to the GUI-based client, +``nextcloudcmd`` does not repeat synchronizations on its own. It also does not +monitor for file system changes. + + +Install ``nextcloudcmd`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +CentOS + +:: + + $ sudo yum -y install epel-release + $ sudo yum -y install nextcloud-client + +Ubuntu + +:: + + $ sudo add-apt-repository ppa:nextcloud-devs/client + $ sudo apt update + $ sudo apt install nextcloud-client + +Debian + +:: + + $ sudo apt install nextcloud-desktop-cmd + + +Refer to the link + +- https://nextcloud.com/install/#install-clients +- https://launchpad.net/~nextcloud-devs/+archive/ubuntu/client +- https://pkgs.alpinelinux.org/packages?name=nextcloud-client +- https://help.nextcloud.com/t/linux-packages-status/10216 + + +To invoke ``nextcloudcmd``, you must provide the local and the remote repository +URL using the following command:: + + nextcloudcmd [OPTIONS...] sourcedir nextcloudurl + +where ``sourcedir`` is the local directory and ``nextcloudurl`` is +the server URL. + +Other command line switches supported by ``nextcloudcmd`` include the following: + +``--path`` + Overrides default remote root folder to a specific subfolder on the server(e.g.: /Documents would sync the Documents subfolder on the server) + +``--user``, ``-u`` `` + Use ``user`` as the login name. + +``--password``, ``-p`` `` + Use `password` as the password. + +``-n`` + Use`netrc(5)` for login. + +``--non-interactive`` + Do not prompt for questions. + +``--silent``, ``--s`` + Inhibits verbose log output. + +``--trust`` + Trust any SSL certificate, including invalid ones. + +``--httpproxy`` `http://[user@pass:]:` + Uses `server` as HTTP proxy. + +``--exclude`` `` + Exclude list file + +``--unsyncedfolders`` `` + File containing the list of unsynced folders (selective sync) + +``--max-sync-retries`` `` + Retries maximum n times (defaults to 3) + +``-h`` + Sync hidden files,do not ignore them + + +Credential Handling +~~~~~~~~~~~~~~~~~~~ + +``nextcloudcmd`` requires the user to specify the username and password using the standard URL pattern, e.g., + +:: + + $ nextcloudcmd /home/user/my_sync_folder https://carla:secret@server/nextcloud + +To synchronize the Nextcloud directory ``Music`` to the local directory +``media/music``, through a proxy listening on port ``8080``, and on a gateway +machine using IP address ``192.168.178.1``, the command line would be:: + + $ nextcloudcmd --httpproxy http://192.168.178.1:8080 --path /Music \ + $HOME/media/music \ + https://server/nextcloud + +``nextcloudcmd`` will prompt for the user name and password, unless they have +been specified on the command line or ``-n`` has been passed. + +Exclude List +~~~~~~~~~~~~ + +``nextcloudcmd`` requires access to an exclude list file. It must either be +installed along with ``nextcloudcmd`` and thus be available in a system location, +be placed next to the binary as ``sync-exclude.lst`` or be explicitly specified +with the ``--exclude`` switch. + +The required file content is one exclude item per line where wildcards are allowed, e.g.: +:: + + ~*.tmp + ._* + ]Thumbs.db + ]photothumb.db + System Volume Information + +Example +~~~~~~~~~~~~ + +- Synchronize a local directory to the specified directory of the nextcloud server + +:: + + $ nextcloudcmd --path / /home/user/ \ + https://:@ diff --git a/admin_manual/desktop/configfile.rst b/admin_manual/desktop/configfile.rst new file mode 100644 index 000000000..89ffbfd5f --- /dev/null +++ b/admin_manual/desktop/configfile.rst @@ -0,0 +1,88 @@ +================== +Configuration File +================== + +The Nextcloud Client reads a configuration file. You can locate this configuration file as follows: + +On Linux distributions: + ``$HOME/.config/Nextcloud/nextcloud.cfg`` + +On Microsoft Windows systems: + ``%APPDATA%\Nextcloud\nextcloud.cfg`` + +On macOS systems: + ``$HOME/Library/Preferences/Nextcloud/nextcloud.cfg`` + + +The configuration file contains settings using the Microsoft Windows .ini file +format. You can overwrite changes using the Nextcloud configuration dialog. + +.. note:: Use caution when making changes to the Nextcloud Client configuration + file. Incorrect settings can produce unintended results. + +Some interesting values that can be set on the configuration file are: + ++----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``[Nextcloud]`` section | ++=================================+===============+========================================================================================================+ +| Variable | Default | Meaning | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``remotePollInterval`` | ``30000`` | Specifies the poll time for the remote repository in milliseconds. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``forceSyncInterval`` | ``7200000`` | The duration of no activity after which a synchronization run shall be triggered automatically. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``fullLocalDiscoveryInterval`` | ``3600000`` | The interval after which the next synchronization will perform a full local discovery. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``notificationRefreshInterval`` | ``300000`` | Specifies the default interval of checking for new server notifications in milliseconds. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ + + ++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``[General]`` section | ++==================================+==========================+========================================================================================================+ +| Variable | Default | Meaning | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``chunkSize`` | ``10000000`` (10 MB) | Specifies the chunk size of uploaded files in bytes. | +| | | The client will dynamically adjust this size within the maximum and minimum bounds (see below). | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``forceLoginV2`` | ``false`` | If the client should force the new login flow, even though some circumstances might need the old flow. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``minChunkSize`` | ``5000000`` (5 MB) | Specifies the minimum chunk size of uploaded files in bytes. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``maxChunkSize`` | ``5000000000`` (5000 MB) | Specifies the maximum chunk size of uploaded files in bytes. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``targetChunkUploadDuration`` | ``60000`` (1 minute) | Target duration in milliseconds for chunk uploads. | +| | | The client adjusts the chunk size until each chunk upload takes approximately this long. | +| | | Set to 0 to disable dynamic chunk sizing. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``promptDeleteAllFiles`` | ``false`` | If a UI prompt should ask for confirmation if it was detected that all files and folders were deleted. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``timeout`` | ``300`` | The timeout for network connections in seconds. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``moveToTrash`` | ``false`` | If non-locally deleted files should be moved to trash instead of deleting them completely. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``showExperimentalOptions`` | ``false`` | Whether to show experimental options that are still undergoing testing in the user interface. | +| | | Turning this on does not enable experimental behavior on its own. It does enable user interface | +| | | options that can be used to opt in to experimental features. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``showMainDialogAsNormalWindow`` | ``false`` | Whether the main dialog should be shown as a normal window even if tray icons are available. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ + + ++----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``[Proxy]`` section | ++=================================+===============+========================================================================================================+ +| Variable | Default | Meaning | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``host`` | ``127.0.0.1`` | The address of the proxy server. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``port`` | ``8080`` | The port were the proxy is listening. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ +| ``type`` | ``2`` | ``0`` for System Proxy. | ++ + +--------------------------------------------------------------------------------------------------------+ +| | | ``1`` for SOCKS5 Proxy. | ++ + +--------------------------------------------------------------------------------------------------------+ +| | | ``2`` for No Proxy. | ++ + +--------------------------------------------------------------------------------------------------------+ +| | | ``3`` for HTTP(S) Proxy. | ++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+ diff --git a/admin_manual/desktop/envvars.rst b/admin_manual/desktop/envvars.rst new file mode 100644 index 000000000..d2e135c6f --- /dev/null +++ b/admin_manual/desktop/envvars.rst @@ -0,0 +1,24 @@ +===================== +Environment Variables +===================== + +The behavior of the client can also be controlled using environment variables. The value of the environment variables overrides the values in the configuration file. + +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_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_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. + +Low Disk Space +^^^^^^^^^^^^^^ + +When disk space is low the Nextcloud Client will be unable to synchronize all files. This section describes its behavior in a low disk space situation as well as the options that influence it. + +1. Synchronization of a folder aborts entirely if the remaining disk space falls below 512 MB. This threshold can be adjusted with the ``OWNCLOUD_CRITICAL_FREE_SPACE_BYTES`` environment variable. + +2. Downloads that would reduce the free disk space below 1 GB will be skipped or aborted. The download will be retried regularly and other synchronization is unaffected. This threshold can be adjusted with the ``OWNCLOUD_FREE_SPACE_BYTES`` environment variable. diff --git a/admin_manual/desktop/images/create_debug_archive.png b/admin_manual/desktop/images/create_debug_archive.png new file mode 100644 index 000000000..7159f6bef Binary files /dev/null and b/admin_manual/desktop/images/create_debug_archive.png differ diff --git a/admin_manual/desktop/images/log_output_window.png b/admin_manual/desktop/images/log_output_window.png new file mode 100644 index 000000000..689f99591 Binary files /dev/null and b/admin_manual/desktop/images/log_output_window.png differ diff --git a/admin_manual/desktop/images/save_log_file.png b/admin_manual/desktop/images/save_log_file.png new file mode 100644 index 000000000..f10264b49 Binary files /dev/null and b/admin_manual/desktop/images/save_log_file.png differ diff --git a/admin_manual/desktop/index.rst b/admin_manual/desktop/index.rst new file mode 100644 index 000000000..b9a4e213f --- /dev/null +++ b/admin_manual/desktop/index.rst @@ -0,0 +1,31 @@ +=============== +Desktop Clients +=============== + +Available for Windows, macOS, and various Linux distributions, the Nextcloud +Desktop Sync client enables you to: + +- Specify one or more directories on your computer that you want to synchronize + to the Nextcloud server. +- Always have the latest files synchronized, wherever they are located. + +Your files are always automatically synchronized between your Nextcloud server, computer and mobile device. + +.. toctree:: + :maxdepth: 1 + + options + massdeployment + configfile + envvars + commandline + accountcommand + troubleshooting + +You can find additional information here: + +* `User manual`_ +* `Developer manual`_ + +.. _`User manual`: https://docs.nextcloud.com/server/latest/user_manual/en/desktop/index.html +.. _`Developer manual`: https://docs.nextcloud.com/server/latest/developer_manual/desktop/index.html diff --git a/admin_manual/desktop/massdeployment.rst b/admin_manual/desktop/massdeployment.rst new file mode 100644 index 000000000..54de78842 --- /dev/null +++ b/admin_manual/desktop/massdeployment.rst @@ -0,0 +1,34 @@ +==================================== +Mass Deployment And Account Creation +==================================== + +It is possible to perform mass deployment of the Nextcloud desktop client by passing certain command-line parameters from the deployment step to Nextcloud desktop client executable after the initial setup. +This will allow desktop client to generate a config (.cfg) file that will be used during subsequent launches. +A config file will have a corresponding account written into it similar to if you have added it manually via the desktop client's UI. +The desktop client will exit with code 0 if account has been added successfully, or 1 in case of failure. +Detailed failure message is printed to the desktop client logs. + +The following parameters are supported: + +``--userid`` + (required) userId (username as on the server) to pass when creating an account via command-line. + +``--apppassword`` + (required) appPassword to pass when creating an account via command-line (see the ``login-flow`` section in server documentation on how to generate the app password). + +``--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. + +``--remotedirpath`` + (optional) path to a remote subfolder when creating an account via command-line. e.g. If the server has folders "/Photos", "/Documents", "/Music" you can pass "/Music" and then this folder will get set up as remote root. + +``--serverurl`` + (required) a server URL to use when creating an account via command-line. (NOTE: There is another parameter supported by Nextcloud desktop client ``--overrideserverurl`` but it SHOULD NOT be used here as it is intended for setup via UI with wizard) + +Examples: + +- ``C:\Program Files\Nextcloud\nextcloud.exe" --userid admin --apppassword Jliy12356785jxnHa2ZCiZ9MX48ncECwDso95Pq3a5HABjY34ZvhZiXrPfpKWUg7aOHAX5 --localdirpath "D:\\Nextcloud-sync-folder" --remotedirpath /Music --serverurl "https://cloud.example.com" --isvfsenabled 1"`` - this will create a config file for user admin on the server https://cloud.example.com and set a remote root folder to "Music", the local sync folder will get created with VFS mode. +- For Linux and mac the same example as above will work but ``nextcloud.exe path`` and ``--localdirpath`` value should get changed to platform specific format (e.g. ``no .exe extension`` and ``/home/`` format) diff --git a/admin_manual/desktop/options.rst b/admin_manual/desktop/options.rst new file mode 100644 index 000000000..42c4037bc --- /dev/null +++ b/admin_manual/desktop/options.rst @@ -0,0 +1,38 @@ +======= +Options +======= + +You have the option of starting your Nextcloud desktop client with the +``nextcloud`` command. The following options are supported: + +``nextcloud -h`` or ``nextcloud --help`` + Displays all command options. + +The other options are: + +``--logwindow`` + Opens a window displaying log output. + +``--logfile`` `` + 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 + directory. + +``--logexpire`` `` + Removes logs older than the value specified (in hours). This command is + used with ``--logdir``. + +``--logflush`` + Clears (flushes) the log file after each write action. + +``--logdebug`` + Also output debug-level messages in the log (equivalent to setting the env var QT_LOGGING_RULES="qt.*=true;*.debug=true"). + +``--confdir`` `` + Uses the specified configuration directory. + +``--background`` + Launch the application in the background (i.e. without opening the main dialog). diff --git a/admin_manual/desktop/troubleshooting.rst b/admin_manual/desktop/troubleshooting.rst new file mode 100644 index 000000000..c9b35906f --- /dev/null +++ b/admin_manual/desktop/troubleshooting.rst @@ -0,0 +1,326 @@ +=============== +Troubleshooting +=============== + +The following two general issues can result in failed synchronization: + +- The server setup is incorrect. +- The client contains a bug. + +When reporting bugs, it is helpful if you first determine what part of the +system is causing the issue. + +Identifying Basic Functionality Problems +---------------------------------------- + +:Performing a general Nextcloud Server test: + The first step in troubleshooting synchronization issues is to verify that + you can log on to the Nextcloud web application. To verify connectivity to the + Nextcloud server try logging in via your Web browser. + + If you are not prompted for your username and password, or if a red warning + box appears on the page, your server setup requires modification. Please verify + that your server installation is working correctly. + +:Ensure the WebDAV API is working: + If all desktop clients fail to connect to the Nextcloud Server, but access + using the Web interface functions properly, the problem is often a + misconfiguration of the WebDAV API. + + The Nextcloud Client uses the built-in WebDAV access of the server content. + Verify that you can log on to Nextcloud's WebDAV server. To verify connectivity + with the Nextcloud WebDAV server: + + - Open a browser window and enter the address to the Nextcloud WebDAV server. + + For example, if your Nextcloud instance is installed at + ``http://yourserver.com/nextcloud``, your WebDAV server address is + ``http://yourserver.com/nextcloud/remote.php/dav``. + + If you are prompted for your username and password but, after providing the + correct credentials, authentication fails, please ensure that your + authentication backend is configured properly. + +:Use a WebDAV command line tool to test: + A more sophisticated test method for troubleshooting synchronization issues + is to use a WebDAV command line client and log into the Nextcloud WebDAV server. + One such command line client -- called ``cadaver`` -- is available for Linux + distributions. You can use this application to further verify that the WebDAV + server is running properly using PROPFIND calls. + + As an example, after installing the ``cadaver`` app, you can issue the + ``propget`` command to obtain various properties pertaining to the current + directory and also verify WebDAV server connection. + +"CSync unknown error" +--------------------- + +If you see this error message stop your client, delete the +``.sync_xxxxxxx.db`` file, and then restart your client. +There is a hidden ``.sync_xxxxxxx.db`` file inside the folder of every account +configured on your client. + +.. NOTE:: + Please note that this will also erase some of your settings about which + files to download. + +See https://github.com/owncloud/client/issues/5226 for more discussion of this +issue. + +"Connection closed" message when syncing files +---------------------------------------------- + +This message can be caused by using chunks that are too big or time-outs that +are set too liberally. You can configure the chunking behavior of the client in +the config file. For example, change these settings: + ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``chunkSize`` | ``10000000`` (10 MB) | Specifies the chunk size of uploaded files in bytes. | +| | | The client will dynamically adjust this size within the maximum and minimum bounds (see below). | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``minChunkSize`` | ``1000000`` (1 MB) | Specifies the minimum chunk size of uploaded files in bytes. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``maxChunkSize`` | ``50000000`` (1000 MB) | Specifies the maximum chunk size of uploaded files in bytes. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ +| ``targetChunkUploadDuration`` | ``6000`` (1 minute) | Target duration in milliseconds for chunk uploads. | +| | | The client adjusts the chunk size until each chunk upload takes approximately this long. | +| | | Set to 0 to disable dynamic chunk sizing. | ++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+ + +Setting ``maxChunkSize`` to 50000000, for example, will decrease the +individual chunk to about 50 mb. This causes additional overhead but +might be required in some situations, for example behind CloudFlare which +has been seen limiting upload chunks to 100mb. In other situations, +limiting ``targetChunkUploadDuration`` can help to avoid time-outs. + +Connection issues with the macOS client on "insecure" connections +----------------------------------------------------------------- +When using macOS devices to connect to a Nextcloud server that uses a what maybe +be classified as an insecure connection (i.e. connecting to a server with a +self-signed certificate, or a certificate with what Apple may consider an +insufficiently secure cipher), the macOS client may not connect to the server. +This is because macOS requires a valid certificate to establish a connection. + +To resolve this issue, you must ensure the server is signed with a certificate +that is accepted by Apple's App Transport Security requirements. More +information on the requirements can be found in Apple's documentation pages. + +https://developer.apple.com/documentation/security/preventing-insecure-network-connections + +Isolating other issues +---------------------- + +Other issues can affect synchronization of your Nextcloud files: + +- If you find that the results of the synchronizations are unreliable, please + ensure that the folder to which you are synchronizing is not shared with + other synchronization applications. + +- Synchronizing the same directory with Nextcloud and other synchronization + software such as Unison, rsync, Microsoft Windows Offline Folders, or other + cloud services such as Dropbox or Microsoft SkyDrive is not supported and + should not be attempted. In the worst case, it is possible that synchronizing + folders or files using Nextcloud and other synchronization software or + services can result in data loss. + +- If you find that only specific files are not synchronized, the + synchronization protocol might be having an effect. Some files are + automatically ignored because they are system files, other files might be + ignored because their filename contains characters that are not supported on + certain file systems. For more information about ignored files, see `ignored-files`. + +- If you are operating your own server, and use the local storage backend (the + default), make sure that Nextcloud has exclusive access to the directory. + + .. warning:: The data directory on the server is exclusive to Nextcloud and must not be modified manually. + +- If you are using a different file backend on the server, you can try to exclude a bug in the + backend by reverting to the built-in backend. + +- If you are experiencing slow upload/download speed or similar performance issues + be aware that those could be caused by on-access virus scanning solutions, either + on the server (like the files_antivirus app) or the client. + +Log Files +--------- + +Effectively debugging software requires as much relevant information as can be +obtained. To assist the Nextcloud support personnel, please try to provide as +many relevant logs as possible. Log output can help with tracking down +problems and, if you report a bug, log output can help to resolve an issue more +quickly. + + .. warning:: Log files contain sensitive information. You may wish to redact sensitive details or to only share limited excerpts. + +Obtaining the Client Log File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create Debug Archive +~~~~~~~~~~~~~~~~~~~~ + +Since the 3.1.0 release we made it easier for users to provide debug information: debug logging is enabled by default with expiration time set to 24 hours and under the "General" settings, you can click on "Create Debug Archive ..." to pick the location of where the desktop client will export the logs and the database to a zip file. + +.. figure:: images/create_debug_archive.png + :alt: Create debug archive + +Keyboard shortcut +~~~~~~~~~~~~~~~~~ + +Another way to obtain the client log file: + +1. Open the Nextcloud Desktop Client. + +2. Press F12 or Ctrl-L on your keyboard. + +The Log Output window opens. + +.. figure:: images/log_output_window.png + :alt: Log output + +3. Click the 'Save' button. + +The Save Log File window opens. + +.. figure:: images/save_log_file.png + :alt: Save logfile + +4. Migrate to a location on your system where you want to save your log file. + +5. Name the log file and click the 'Save' button. + + The log file is saved in the location specified. + +Command line +~~~~~~~~~~~~ + +Alternatively, you can launch the Nextcloud Log Output window using the +``--logwindow`` command. After issuing this command, the Log Output window +opens to show the current log. You can then follow the same procedures +mentioned above to save the log to a file. + + .. note:: You can also open a log window for an already running session, by + restarting the client using the following command: + + * Windows: ``C:\Program Files (x86)\Nextcloud\nextcloud.exe --logwindow`` + * macOS: ``/Applications/nextcloud.app/Contents/MacOS/nextcloud --logwindow`` + * Linux: ``nextcloud --logwindow`` + +Config file +~~~~~~~~~~~ + +The Nextcloud client enables you to save log files directly to a predefined file +or directory. This is a useful option for troubleshooting sporadic issues as +it enables you to log large amounts of data and bypass the limited buffer +settings associated with the log window. + +To enable logging to a directory, stop the client and add the following to the General section in the configuration file: + +:: + + [General] + logDebug=true + logExpire= + logDir= + +Independent of platform you must use slash (/) as a path separator: + + .. note:: + * Correct: C:/Temp + * Not correct: C:\Temp + +As an example, to keep log data for two days in a directory called temp: + +:: + + [General] + logDebug=true + logExpire=48 + logDir=C:/Temp + +Once you restart the client, you will find the log file in the ```` defined in ``logDir``. + + .. note:: You will find the configuration file in the following locations: + + * Microsoft Windows systems: ``%APPDATA%\Nextcloud\nextcloud.cfg`` + * macOS systems: ``$HOME/Library/Preferences/Nextcloud/nextcloud.cfg`` + * Linux distributions: ``$HOME/.config/Nextcloud/nextcloud.cfg`` + + +Alternatively, you can start the client in the command line with parameters: + +1. To save to a file, start the client using the ``--logfile `` command, + where ```` is the filename to which you want to save the file. + +2. To save to a directory, start the client using the ``--logdir `` command, where ```` + is an existing directory. + +When using the ``--logdir`` command, each sync run creates a new file. To limit +the amount of data that accumulates over time, you can specify the +``--logexpire `` command. When combined with the ``--logdir`` command, +the client automatically erases saved log data in the directory that is older +than the specified number of hours. + +As an example, to define a test where you keep log data for two days, you can +issue the following command: + +``` +nextcloud --logdir /tmp/nextcloud_logs --logexpire 48 +``` + +Nextcloud server Log File +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Nextcloud server also maintains an Nextcloud specific log file. This log file +must be enabled through the Nextcloud Administration page. On that page, you can +adjust the log level. We recommend that when setting the log file level that +you set it to a verbose level like ``Debug`` or ``Info``. + +You can view the server log file using the web interface or you can open it +directly from the file system in the Nextcloud server data directory. + +.. todo:: Need more information on this. How is the log file accessed? + Need to explore procedural steps in access and in saving this file ... similar + to how the log file is managed for the client. Perhaps it is detailed in the + Admin Guide and a link should be provided from here. I will look into that + when I begin heavily editing the Admin Guide. + +Webserver Log Files +~~~~~~~~~~~~~~~~~~~ + +It can be helpful to view your webserver's error log file to isolate any +Nextcloud-related problems. For Apache on Linux, the error logs are typically +located in the ``/var/log/apache2`` directory. Some helpful files include the +following: + +- ``error_log`` -- Maintains errors associated with PHP code. +- ``access_log`` -- Typically records all requests handled by the server; very + useful as a debugging tool because the log line contains information specific + to each request and its result. + +You can find more information about Apache logging at +``http://httpd.apache.org/docs/current/logs.html``. + +Core Dumps +---------- + +On macOS and Linux systems, and in the unlikely event the client software +crashes, the client is able to write a core dump file. Obtaining a core dump +file can assist Nextcloud Customer Support tremendously in the debugging +process. + +To enable the writing of core dump files, you must define the +``OWNCLOUD_CORE_DUMP`` environment variable on the system. + +For example: + +``` +OWNCLOUD_CORE_DUMP=1 nextcloud +``` + +This command starts the client with core dumping enabled and saves the files in +the current working directory. + +.. note:: Core dump files can be fairly large. Before enabling core dumps on + your system, ensure that you have enough disk space to accommodate these files. + Also, due to their size, we strongly recommend that you properly compress any + core dump files prior to sending them to Nextcloud Customer Support. diff --git a/admin_manual/exapps_management/AdvancedDeployOptions.rst b/admin_manual/exapps_management/AdvancedDeployOptions.rst new file mode 100644 index 000000000..1157804f9 --- /dev/null +++ b/admin_manual/exapps_management/AdvancedDeployOptions.rst @@ -0,0 +1,35 @@ +======================= +Advanced Deploy Options +======================= + +AppAPI allows optionally to configure environment variables and mounts for the ExApp container. + +It is available via "Deploy options" modal next to "Deploy and Enable" button in the sidebar of the ExApp page on the Apps management page: + +.. image:: ./img/advanced_deploy_options_1.png + +Or via CLI (:ref:`advanced_deploy_options_cli`). + + +Environment Variables +--------------------- + +Environment variables enable more precise configuration of the ExApp. +ExApp developers can define the list of supported environment variables with descriptions, +only these variables will be available for configuration. + +By default there are only mounts available for configuration. + +.. image:: ./img/advanced_deploy_options_2.png + +When ExApp installed the list of set environment variables will be displayed. + + +Mounts +------ + +Mounts can be used to provide additional data to the ExApp container from the host. +For example, it will be useful for some apps to provide a folder with SSL certs of your cloud, +so the app can handle HTTPS correctly without any additional re-installation of the ExApp. + +.. image:: ./img/advanced_deploy_options_3.png diff --git a/admin_manual/exapps_management/AppAPIAndExternalApps.rst b/admin_manual/exapps_management/AppAPIAndExternalApps.rst new file mode 100644 index 000000000..cb824900a --- /dev/null +++ b/admin_manual/exapps_management/AppAPIAndExternalApps.rst @@ -0,0 +1,75 @@ +======================== +AppAPI and External Apps +======================== + +.. _ai-app_api: + +Previously, Nextcloud only supported applications written in the PHP programming language. +In order to support a wider range of use cases, +an ecosystem for **ExApps** (short for "External Apps") was introduced, allowing for the installation of apps as Docker containers. + +Most of our :doc:`Artificial Intelligence <../ai/index>` (AI) apps are developed as ExApps and thus may require some preparation of your Nextcloud instance before you can install them. + +Installing AppAPI +----------------- + +All ExApps require the `AppAPI `_ Nextcloud app as a dependency. +As of Nextcloud version 30.0.1, AppAPI is automatically installed by default. +If AppAPI is not installed, you can still install it by simply navigating to the Apps management page in your Nextcloud instance and search for AppAPI from the Tools category. + +Setup deploy daemon +------------------- + +A Deploy Daemon is a way for Nextcloud to install, communicate with, and control ExApps. + +.. note:: + If you are using Nextcloud AIO with the "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. + +1. Setup a Docker container called `docker-socket-proxy `_ that proxies access to Docker for your Nextcloud instance. +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 +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. + +.. image:: ./img/app_api_3.png + +Deployment configuration examples can be found :doc:`here <./DeployConfigurations>`. + +Installing ExApps +----------------- + +You can now install ExApps from the Nextcloud App Store by clicking "Install" on the respective app in the Apps page. +If successful, the ExApp will be displayed under the "Your apps" list. + +.. image:: ./img/exapp_list_example.png + +FAQ +--- + +* I have two graphics cards XXX with 6/8/Y GB of ram each. How can I run something which does not fit into one graphics card? + * Distributing models across multiple GPUs is currently not supported. You will need a GPU that fits all of the model you are trying to use. +* I have YYY graphics card that does not supports CUDA - can I use it and how? + * No, our AI apps require GPUs with CUDA support to function at this time. +* What is the minimum VRAM size requirement for the GPU if I want to install multiple apps? + * When running multiple ExApps on the same GPU, the GPU must hold the largest model amongst the apps you install. +* Is it possible to add more graphics cards for my instance to enable parallel requests or to speed up one request? + * Parallel processing of AI workloads for the same app with multiple GPUs is currently not supported. +* Can I use the CPU and GPU in parallel for AI processing? + * No, you can only process AI workloads on either the CPU or GPU for one app. For different apps, you can decide whether to run them on CPU or GPU. diff --git a/admin_manual/exapps_management/DeployConfigurations.rst b/admin_manual/exapps_management/DeployConfigurations.rst new file mode 100644 index 000000000..15633566a --- /dev/null +++ b/admin_manual/exapps_management/DeployConfigurations.rst @@ -0,0 +1,384 @@ +.. _deploy-configs: + +Deployment configurations +========================= + +Currently, only one kind of application deployment is supported: + * **Docker Deploy Daemon** + +Docker Deploy Daemon +-------------------- + +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. + + We recommend that you use the `AppAPI Docker Socket Proxy `_ or `AIO Docker Socket Proxy <#nextcloud-in-docker-aio-all-in-one>`_ container. + +There are several Docker Daemon Deploy configurations (example schemes): + + * Nextcloud and Docker on the **same host** (via socket or DockerSocketProxy) + * Nextcloud on the host and Docker on a **remote** host (via DockerSocketProxy with HTTPS) + * Nextcloud and **ExApps** in the **same Docker** (via DockerSocketProxy) + * Nextcloud in AIO Docker and **ExApps** in the **same Docker** (via AIO DockerSocketProxy) + + +NC & Docker on the Same-Host +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The simplest configuration is when Nextcloud is installed on the host and Docker is on the same host and applications are deployed to it. + +.. mermaid:: + + stateDiagram-v2 + classDef docker fill: #1f97ee, color: transparent, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/img/docker.png) no-repeat center center / contain + classDef nextcloud fill: #006aa3, color: transparent, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/img/nextcloud.svg) no-repeat center center / contain + classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px + + Host + + state Host { + Nextcloud --> Daemon : /var/run/docker.sock + Daemon --> Containers + + state Containers { + ExApp1 + -- + ExApp2 + -- + ExApp3 + } + } + + 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** + +--- + +Suggested way to communicate with Docker via `Docker Socket Proxy container `_. + +.. mermaid:: + + stateDiagram-v2 + classDef docker fill: #1f97ee, color: transparent, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/img/docker.png) no-repeat center center / contain + classDef nextcloud fill: #006aa3, color: transparent, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/img/nextcloud.svg) no-repeat center center / contain + classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px + + Host + + state Host { + Nextcloud --> DockerSocketProxy: by port + Docker --> Containers + Docker --> DockerSocketProxy : /var/run/docker.sock + + state Containers { + DockerSocketProxy --> ExApp1 + DockerSocketProxy --> ExApp2 + DockerSocketProxy --> ExApp3 + } + } + + 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** + +.. 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. + + +Docker on a remote host +^^^^^^^^^^^^^^^^^^^^^^^ + +Distributed configuration occurs when Nextcloud is installed on one host and Docker is located on a remote host, resulting in the deployment of applications on the remote host. + +Benefit: no performance impact on Nextcloud host. + +In this case, the AppAPI uses a Docker Socket Proxy deployed on remote host to access docker socket and ExApps. + +.. mermaid:: + + stateDiagram-v2 + classDef docker fill: #1f97ee, color: transparent, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/img/docker.png) no-repeat center center / contain + classDef nextcloud fill: #006aa3, color: transparent, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/img/nextcloud.svg) no-repeat center center / contain + classDef python fill: #1e415f, color: white, stroke: #364c53, stroke-width: 1px + + Direction LR + + Host1 --> Host2 : by port + + state Host1 { + Nextcloud + } + + state Host2 { + [*] --> DockerSocketProxy : by port + Daemon --> Containers + + 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 + +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** + +NC & ExApps in the same Docker +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Applications are deployed in the same Docker where Nextcloud resides. + +Suggested way to communicate with Docker: via ``docker-socket-proxy``. + +.. mermaid:: + + stateDiagram-v2 + classDef docker fill: #1f97ee, color: transparent, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/img/docker.png) no-repeat center center / contain + classDef nextcloud fill: #006aa3, color: transparent, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/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 { + [*] --> 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 + +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** + +.. note:: + 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**. + + +.. _nextcloud-in-docker-aio-all-in-one: + +Nextcloud in Docker AIO (all-in-one) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the case of AppAPI in Docker AIO setup (installed in Nextcloud container). + +.. note:: + + AIO Docker Socket Proxy container must be enabled. + +.. mermaid:: + + stateDiagram-v2 + classDef docker fill: #1f97ee, color: transparent, font-size: 34px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/img/docker.png) no-repeat center center / contain + classDef docker2 fill: #1f97ee, color: transparent, font-size: 20px, stroke: #364c53, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/img/docker.png) no-repeat center center / contain + classDef nextcloud fill: #006aa3, color: transparent, font-size: 34px, stroke: #045987, stroke-width: 1px, background: url(https://raw.githubusercontent.com/nextcloud/app_api/main/docs/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 AIO Deploy Daemon +************************* + +Nextcloud AIO has a specifically created Docker Socket Proxy container to be used as the Deploy Daemon in AppAPI. +It has `fixed parameters `_: + +* Name: ``docker_aio`` +* Display name: ``AIO Docker Socket Proxy`` +* Accepts Deploy ID: ``docker-install`` +* Protocol: ``http`` +* Host: ``nextcloud-aio-docker-socket-proxy:2375`` +* Compute device: ``CPU`` +* Network: ``nextcloud-aio`` +* Nextcloud URL (passed to ExApps): ``https://$NC_DOMAIN`` + +Docker Socket Proxy security +**************************** + +AIO Docker Socket Proxy has strictly limited access to the Docker APIs described in `HAProxy configuration `_. + + +NC to ExApp Communication +------------------------- + +Each type of DeployDaemon necessarily implements the ``resolveExAppUrl`` function. + +It has the prototype: + +.. code-block:: php + + public function resolveExAppUrl( + string $appId, string $protocol, string $host, array $deployConfig, int $port, array &$auth + ) {} + +where: + +* **protocol** is daemon protocol value +* **host** is daemon host value, *can be DNS:port or IP:PORT or even path to docker socket*. +* **port** is an integer with ExApp port +* **deployConfig** can be custom for each Daemon type +* **auth** is an optional array, with *Basic Authentication* data if needed to access ExApp + +.. note:: + + 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. + + 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 { + $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. + +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 { + $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 (isset($deployConfig['haproxy_password']) && $deployConfig['haproxy_password'] !== '') { + $auth = [self::APP_API_HAPROXY_USER, $deployConfig['haproxy_password']]; + } + return sprintf('%s://%s:%s', $protocol, $exAppHost, $port); + } + +Here we have much more complex algorithm of detecting to where requests should be send. + +First of all, if the protocol is set to ``https``, AppAPI always sends requests to the daemon host, +and in this case, it is a HaProxy that will forward requests to ExApps that will be listening on ``localhost``. + +Briefly, it will look like this (*haproxy_host==daemon host value*): + +NC --> *https* --> ``haproxy_host:ex_app_port`` --> *http* --> ``localhost:ex_app_port`` + +When the protocol is not ``https`` but ``http``, then what will be the endpoint where to send requests is determined by ``$deployConfig['net']`` value. + +If ``net`` is defined and equal to ``host``, then AppAPI assumes that ExApp is installed somewhere in the current host network and will be available on ``localhost`` loop-back adapter. + +NC --> *http* --> ``localhost:ex_app_port`` + +In all other cases, the ExApp should be available by it's name: e.g. when using docker **custom bridge** network all containers available by DNS. + +NC --> *http* --> ``app_container_name:ex_app_port`` + +These three different types of communication cover most popular configurations. diff --git a/admin_manual/exapps_management/ManagingDeployDaemons.rst b/admin_manual/exapps_management/ManagingDeployDaemons.rst new file mode 100644 index 000000000..2cb627e1d --- /dev/null +++ b/admin_manual/exapps_management/ManagingDeployDaemons.rst @@ -0,0 +1,97 @@ + .. _managing-deploy-daemons: + +Managing Deploy Daemons +======================= + +OCC CLI +^^^^^^^ + +There are a few OCC CLI commands to manage Deploy Daemons: + +1. Register ``occ app_api:daemon:register`` +2. Unregister ``occ app_api:daemon:unregister`` +3. List registered daemons ``occ app_api:daemon:list`` + +Register +-------- + +Register Deploy Daemon (DaemonConfig). + +Command: ``app_api:daemon:register [--net NET] [--haproxy_password HAPROXY_PASSWORD] [--compute_device COMPUTE_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``) + * ``host`` - **path to docker-socket** or the Docker Socket Proxy: ``address:port`` + * ``protocol`` - protocol used to communicate with the Daemon/ExApps (``http`` or ``https``) + * ``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 HAPROXY_PASSWORD`` - ``[optional]`` password for AppAPI Docker Socket Proxy + * ``--compute_device GPU`` - ``[optional]`` GPU device to expose to the daemon (e.g. ``cpu|cuda|rocm``, default: ``cpu``) + * ``--set-default`` - ``[optional]`` set created daemon as default for ExApps installation + +DeployConfig +************ + +DeployConfig is a set of additional options in Daemon config, which are used in deployment algorithms to configure +ExApp container. + +.. code-block:: json + + { + "net": "host", + "nextcloud_url": "https://nextcloud.local", + "haproxy_password": "some_secure_password", + "computeDevice": { + "id": "cuda", + "name": "CUDA (NVIDIA)", + }, + } + +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)" }``) + +Unregister +---------- + +Unregister Deploy Daemon (DaemonConfig). + +Command: ``app_api:daemon:unregister `` + +List registered daemons +----------------------- + +List registered Deploy Daemons (DaemonConfigs). + +Command: ``app_api:daemon:list`` + +Nextcloud AIO +^^^^^^^^^^^^^ + +In the case of AppAPI installed in AIO, a default Deploy Daemon is registered automatically. +It is possible to register additional Deploy Daemons using the same methods as described above. + + +.. _additional_options_list: + +Additional options +^^^^^^^^^^^^^^^^^^ + +There is a possibility to add additional options to the Deploy Daemon configuration, +which are key-value pairs. + +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) diff --git a/admin_manual/exapps_management/ManagingExApps.rst b/admin_manual/exapps_management/ManagingExApps.rst new file mode 100644 index 000000000..c2e954c96 --- /dev/null +++ b/admin_manual/exapps_management/ManagingExApps.rst @@ -0,0 +1,107 @@ +Managing ExApps +=============== + +Managing ExApps can be done from App Management UI as with other Nextcloud Apps, +but you can also use the AppAPI commands in the OCC CLI tool. + +There are several commands to work with ExApps: + +1. Register +2. Unregister +3. Update +4. Enable +5. Disable +6. List ExApps + +Register +-------- + +Command: ``app_api:app:register [--force-scopes] [--info-xml INFO-XML] [--json-info JSON-INFO] [--wait-finish] [--silent] [--test-deploy-mode] [--env [ENV]] [--mount [MOUNT]] [--] []`` + +The register command is the first ExApp installation step. + +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``) + +Options +******* + + * ``--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) + * ``--wait-finish`` *[optional]* - wait until initialization finished + * ``--silent`` *[optional]* - do not print to console + * ``--test-deploy-mode`` *[optional]* - test deploy mode with additional status checks and slightly different logic + + .. _advanced_deploy_options_cli: + +Advanced Deploy Options +*********************** + + * ``--env`` *[optional]* - environment (ENV_NAME=ENV_VALUE), passed to ExApp container as environment variables (multiple values allowed) + * ``--mount`` *[optional]* - mount options (SRC_PATH=DST_PATH), passed to ExApp container as volume mounts (multiple values allowed) + + +Unregister +---------- + +Command: ``app_api:app:unregister [--rm-data] [--force] [--silent] [--] `` + +To remove an ExApp, you can use the unregister command. +By default, this command does *not* delete the ExApp's persistent storage (data volume) to avoid accidental removal of any user data. + +Arguments +********* + + * ``appid`` - unique name of the ExApp (e.g. ``app_python_skeleton``, must be the same as in deployed container) + +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 + +Update +------ + +Command: ``app_api:app:update [--info-xml INFO-XML] [--force-update] [-e|--enabled] [--] `` + +ExApp will be updated if there is a new version available. + +Arguments +********* + + * ``appid`` - unique name of the ExApp (e.g. ``app_python_skeleton``, must be the same as in deployed container) + +Options +******* + + * ``--info-xml INFO-XML`` *[optional]* - path to info.xml file (url or local absolute path) + * ``-e|--enabled`` *[optional]* - enable ExApp after update + +Enable +------ + +Command: ``app_api:app:enable `` + +Disable +------- + +Command: ``app_api:app:disable `` + +List ExApps +----------- + +Command: ``app_api:app:list`` + +ListExApps command will show all ExApps: + +.. code-block:: + + ExApps: + appid (Display Name): version [enabled/disabled] + to_gif_example (To Gif Example): 1.0.0 [enabled] + upscaler_example (Upscaler Example): 1.0.0 [enabled] diff --git a/admin_manual/exapps_management/TestDeploy.rst b/admin_manual/exapps_management/TestDeploy.rst new file mode 100644 index 000000000..b7cad98f4 --- /dev/null +++ b/admin_manual/exapps_management/TestDeploy.rst @@ -0,0 +1,99 @@ +.. _test_deploy: + +Test Deploy Daemon +------------------ + +You can test each Daemon configuration deployment from the AppAPI Admin settings. + +.. image:: ./img/test_deploy.png + + +Status Checks +^^^^^^^^^^^^^ + +The Deploy test installs a `test-deploy `_ ExApp +to verify each step of the deployment process, including a hardware support check - +for each compute device, there is a separate Docker image. + +.. note:: + The Test Deploy ExApp container is not removed after the test as it's needed for logs and status checks. + You can remove it after testing from the Apps page. + The Docker images are also not removed from the Daemon; you can clean up unused images with the ``docker image prune`` command. + +.. image:: ./img/test_deploy_modal_4.png + + +Register +******** + +The Register step is the first step; it checks if the ExApp is registered in Nextcloud. + +Image Pull +********** + +The Image Pull step downloads the ExApp Docker image. + +Possible errors: + +- Image not found (e.g. not public, no image found for your hardware architecture) +- Image pull failed (e.g., due to network issues) +- Image pull timeout +- Your Docker Socket Proxy is not configured correctly and blocks access to this Docker Engine API + +Container Started +***************** + +The Container Started step verifies that the ExApp container is created and started successfully. + +Possible errors: + +- Container failed to start with GPU support (may be missing or misconfigured) + - For NVIDIA, refer to the `NVIDIA Docker configuration docs `_. + - For AMD, refer to the `ROCm Docker configuration docs `_. +- The ExApp issue during startup (e.g. not enough memory) + + +Heartbeat +********* + +The Heartbeat step checks if the container's health check is finished and the container is healthy. +The ExApp might have additional pre-configuration logic during this step. + +Possible errors: + +- ExApp failed to start a web server, e.g., if the port is already in use (this should be visible in the container logs) +- ExApp heartbeat_count keeps increasing, this may indicate that the ExApp couldn't start properly +- Nextcloud can not reach the ExApp container, e.g., + * due to a network issue or a firewall (this should be visible in the server logs or the firewall logs) + * due to a "http" protocol deploy daemon. In this case, the ExApp's container listens on localhost (127.0.0.1 or ::1) which might not be reachable from the Nextcloud server and you might want to listen on a different IP address. See ``OVERRIDE_APP_HOST`` in :ref:`Additional options ` in the Deploy Daemon form. This issue can be identified using this command: ``lsof -i -P -n | grep LISTEN`` + +Init +**** + +The Init step checks if the ExApp is initialized and ready to use. +During the init step, the ExApp may perform downloads of extra stuff required for it. + +Possible errors: + +- Initialization failed (e.g., due to network issues or timeout) + + +Enabled +******* + +The Enabled step checks if the ExApp is enabled and ready to use. +During this step, the ExApp registers all the required and available APIs of the Nextcloud AppFramework. + +Possible errors: + +- ExApp did not respond to the enable request +- ExApp failed to enable due to a failure in registering AppAPI Nextcloud AppFramework APIs (this should be visible both in the container logs and in the Nextcloud logs if there are any errors) + + +Download Logs +^^^^^^^^^^^^^ + +You can download the logs of the last test deploy attempt container. + +.. note:: + Downloading Docker container logs is only possible for containers using the json-file or journald logging drivers. diff --git a/admin_manual/exapps_management/img/advanced_deploy_options_1.png b/admin_manual/exapps_management/img/advanced_deploy_options_1.png new file mode 100644 index 000000000..4dc950033 Binary files /dev/null and b/admin_manual/exapps_management/img/advanced_deploy_options_1.png differ diff --git a/admin_manual/exapps_management/img/advanced_deploy_options_2.png b/admin_manual/exapps_management/img/advanced_deploy_options_2.png new file mode 100644 index 000000000..1c1d9a44d Binary files /dev/null and b/admin_manual/exapps_management/img/advanced_deploy_options_2.png differ diff --git a/admin_manual/exapps_management/img/advanced_deploy_options_3.png b/admin_manual/exapps_management/img/advanced_deploy_options_3.png new file mode 100644 index 000000000..591248dad Binary files /dev/null and b/admin_manual/exapps_management/img/advanced_deploy_options_3.png differ diff --git a/admin_manual/exapps_management/img/app_api_1.png b/admin_manual/exapps_management/img/app_api_1.png new file mode 100755 index 000000000..db88faec9 Binary files /dev/null and b/admin_manual/exapps_management/img/app_api_1.png differ diff --git a/admin_manual/exapps_management/img/app_api_2.png b/admin_manual/exapps_management/img/app_api_2.png new file mode 100644 index 000000000..70ada7ec6 Binary files /dev/null and b/admin_manual/exapps_management/img/app_api_2.png differ diff --git a/admin_manual/exapps_management/img/app_api_3.png b/admin_manual/exapps_management/img/app_api_3.png new file mode 100644 index 000000000..aa01934d3 Binary files /dev/null and b/admin_manual/exapps_management/img/app_api_3.png differ diff --git a/admin_manual/exapps_management/img/app_api_4.png b/admin_manual/exapps_management/img/app_api_4.png new file mode 100644 index 000000000..839058809 Binary files /dev/null and b/admin_manual/exapps_management/img/app_api_4.png differ diff --git a/admin_manual/exapps_management/img/docker.png b/admin_manual/exapps_management/img/docker.png new file mode 100755 index 000000000..6d436d380 Binary files /dev/null and b/admin_manual/exapps_management/img/docker.png differ diff --git a/admin_manual/exapps_management/img/exapp_list_example.png b/admin_manual/exapps_management/img/exapp_list_example.png new file mode 100644 index 000000000..1576cecf1 Binary files /dev/null and b/admin_manual/exapps_management/img/exapp_list_example.png differ diff --git a/admin_manual/exapps_management/img/nextcloud.svg b/admin_manual/exapps_management/img/nextcloud.svg new file mode 100644 index 000000000..5375040d6 --- /dev/null +++ b/admin_manual/exapps_management/img/nextcloud.svg @@ -0,0 +1,11 @@ + + + + + + + + + diff --git a/admin_manual/exapps_management/img/test_deploy.png b/admin_manual/exapps_management/img/test_deploy.png new file mode 100644 index 000000000..2ca76c1cb Binary files /dev/null and b/admin_manual/exapps_management/img/test_deploy.png differ diff --git a/admin_manual/exapps_management/img/test_deploy_modal_2.png b/admin_manual/exapps_management/img/test_deploy_modal_2.png new file mode 100644 index 000000000..1c3b0c0dd Binary files /dev/null and b/admin_manual/exapps_management/img/test_deploy_modal_2.png differ diff --git a/admin_manual/exapps_management/img/test_deploy_modal_4.png b/admin_manual/exapps_management/img/test_deploy_modal_4.png new file mode 100644 index 000000000..42fd3b918 Binary files /dev/null and b/admin_manual/exapps_management/img/test_deploy_modal_4.png differ diff --git a/admin_manual/exapps_management/index.rst b/admin_manual/exapps_management/index.rst new file mode 100644 index 000000000..9d0de532b --- /dev/null +++ b/admin_manual/exapps_management/index.rst @@ -0,0 +1,13 @@ +================= +ExApps management +================= + +.. toctree:: + :maxdepth: 2 + + AppAPIAndExternalApps + DeployConfigurations + ManagingDeployDaemons + TestDeploy + ManagingExApps + AdvancedDeployOptions diff --git a/admin_manual/file_workflows/access_control.rst b/admin_manual/file_workflows/access_control.rst index 16149c149..dddc6614f 100644 --- a/admin_manual/file_workflows/access_control.rst +++ b/admin_manual/file_workflows/access_control.rst @@ -43,7 +43,7 @@ assigned. So you just need to assign the tag to the folder or file, and then block the tag with a rule group. The check is independent of the user's permissions for -the tag. Therefor restricted and invisible tags are recommended, otherwise a +the tag. Therefore restricted and invisible tags are recommended, otherwise a user could remove and reassign the tag. This example blocks access to any folder with the tag ``Confidential``. @@ -75,7 +75,7 @@ Blocking user groups When trying to deny access to a group of users, make sure that sharing does not allow them to create a way back in. When users are able to create a public link, the users can log themselves out and visit their own public link to access the -files. Since at this point they are no user and therefor no member of the +files. Since at this point they are no user and therefore no member of the blocked group, they will be able to read and change the file. The recommended work around is to create the same rule again, and deny access @@ -87,7 +87,7 @@ External storage While access to files in external storages is not possible via Nextcloud, users that have direct access to the external storage, can of course change files -there directly. Therefor it is recommended to disable the ``Allow users to mount +there directly. Therefore it is recommended to disable the ``Allow users to mount external storage`` option, when trying to to completely lock out users. .. _available-rules-label: diff --git a/admin_manual/file_workflows/automated_tagging.rst b/admin_manual/file_workflows/automated_tagging.rst index ecbb2698f..9ab2356c6 100644 --- a/admin_manual/file_workflows/automated_tagging.rst +++ b/admin_manual/file_workflows/automated_tagging.rst @@ -27,7 +27,7 @@ navigate to the configuration and locate the Workflow settings. In the example you can see a simple rule with only one condition. It will tag all files with the restricted tag ``Protected file`` that are uploaded into a folder that is tagged with ``Protect content``. No user can -remove the tag ``Protected file`` and therefor access control and retention +remove the tag ``Protected file`` and therefore access control and retention both work fine without users being able to work around them. In this case folder will be also tagged with tag ``Protected file``, to avoid diff --git a/admin_manual/groupware/calendar.rst b/admin_manual/groupware/calendar.rst index be7493abe..1ff83a7c4 100644 --- a/admin_manual/groupware/calendar.rst +++ b/admin_manual/groupware/calendar.rst @@ -2,6 +2,24 @@ Calendar / CalDAV ================= +Calendar server settings +------------------------ + +The calendar server can be configured on the Groupware admin settings page. +You can globally disable sending invitation emails for events, generating the built-in birthday +calendar, and sending email notifications about upcoming events. + +.. figure:: images/settings_calendar-server.png + :scale: 60% + +.. versionadded:: 30 The section will be hidden if no app makes use of the CalDAV backend. + +Starting from Nextcloud 30, the calendar server settings section will be hidden if no app uses the +CalDAV backend. +Install and enable an appropriate app to show the section again, e.g. +`Calendar `_ or +`Tasks `_. + Events ------ @@ -28,13 +46,13 @@ Contacts that have a birthday date filled are automatically added as events to a If you deactivate this option, all users will no longer have this calendar. When activating this option, users birthday calendars won't be available right away because they need to be generated -by a background task. See :doc:`../configuration_server/occ_command` section DAV commands. +by a background task. See :doc:`../occ_command` section DAV commands. Reminder notifications ---------------------- Nextcloud handles sending notifications for events. -Nextcloud currently handles two types of reminder notifications: Build-in Nextcloud notifications and +Nextcloud currently handles two types of reminder notifications: Built-in Nextcloud notifications and email notifications. For the emails to be send, you'll need a configured email server. See :doc:`../configuration_server/email_configuration`. @@ -49,7 +67,7 @@ more often than the standard ``cron`` system:: # crontab -u www-data -e */5 * * * * php -f /var/www/nextcloud/occ dav:send-event-reminders -See :doc:`../configuration_server/occ_command` section Dav commands. +See :doc:`../occ_command` section Dav commands. You'll also need to change the sending mode from ``background-job`` to ``occ``:: @@ -99,13 +117,14 @@ Refresh rate ~~~~~~~~~~~~ Calendar subscriptions are cached on server and refreshed periodically. -The default refresh rate is one week, unless the subscription itself tells otherwise. +If the calendar server provides a `refresh interval `_, it is respected. +Otherwise the default refresh rate is one day. -To set up a different default refresh rate, change the ``calendarSubscriptionRefreshRate`` option:: +To set up a different default refresh rate for calendars without server side refresh rates, change the ``calendarSubscriptionRefreshRate`` option:: - php occ config:app:set dav calendarSubscriptionRefreshRate --value "P1D" + php occ config:app:set dav calendarSubscriptionRefreshRate --value "PT6H" -Where the value is a `DateInterval `_, for instance with the above command all of the Nextcloud instance's calendars would be refreshed every day. +Where the value is a `DateInterval `_, for instance with the above command all of the Nextcloud instance's calendars would be refreshed every 6 hours. Allow subscriptions on local network ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/admin_manual/groupware/contacts.rst b/admin_manual/groupware/contacts.rst index af8dc150e..db9b9b597 100644 --- a/admin_manual/groupware/contacts.rst +++ b/admin_manual/groupware/contacts.rst @@ -16,11 +16,22 @@ Nextcloud maintains a read-only address book containing contact information of a Disabled users are removed from this address book. -You can disable access to the system address book by using the app config value ``system_addressbook_exposed``. +You can disable or enable access to the system address book by using the administration interface or with a command line command. -Run ``occ config:app:set dav system_addressbook_exposed --value="no"`` to disable access to the system address book for all users. Please note that this does not influence :ref:`Federated sharing`. +Please note that this does not influence :ref:`Federated sharing`. -.. warning:: If clients have already connected to the CalDAV endpoint, the clients might experience sync issues after system address book access was disabled. This can often be remedied by chosing a different default address book on the client and forcing a resync. +Command Line +^^^^^^^^^^^^ + +Run ``occ config:app:set dav system_addressbook_exposed --value="no"`` to disable access to the system address book for all users. + +Administration interface +^^^^^^^^^^^^^^^^^^^^^^^^ + +Navigate to *Administration Settings* -> *Groupware* -> *System Address Book* section and toggle the *Enable system address book* option. + + +.. warning:: If clients have already connected to the CalDAV endpoint, the clients might experience sync issues after system address book access was disabled. This can often be remedied by choosing a different default address book on the client and forcing a resync. Privacy and User Property Scopes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -49,3 +60,22 @@ Shared items .. versionadded:: 5.5.0 For this feature, the shipped `related resources app `_ needs to be enabled. + +Rate limits +----------- + +Nextcloud rate limits the creation of address books and how many can be created in a short period of time. The default is 10 address books per hour. This can be customized as follows:: + + # Set limit to 15 items per 30 minutes + php occ config:app:set dav rateLimitAddressBookCreation --type=integer --value=15 + php occ config:app:set dav rateLimitPeriodAddressBookCreation --type=integer --value=1800 + +Additionally, the maximum number of address books a user may create is limited to 10 items. This can be customized too:: + + # Allow users to create 50 addressbooks + php occ config:app:set dav maximumAdressbooks --type=integer --value=50 + +or:: + + # Allow users to create address books without restriction + php occ config:app:set dav maximumAdressbooks --type=integer --value=-1 diff --git a/admin_manual/groupware/images/settings_calendar-server.png b/admin_manual/groupware/images/settings_calendar-server.png new file mode 100644 index 000000000..c05312a2f Binary files /dev/null and b/admin_manual/groupware/images/settings_calendar-server.png differ diff --git a/admin_manual/groupware/mail.rst b/admin_manual/groupware/mail.rst index 077d9903c..22329ad03 100644 --- a/admin_manual/groupware/mail.rst +++ b/admin_manual/groupware/mail.rst @@ -91,7 +91,7 @@ Users can share mailboxes with each other. So far, there is no UI for users to c LLM Processing -------------- -The Mail app can optionally use large language models to process emails and offer assistance features like thread summaries, smart replies and event agendas. +The Mail app can optionally use large language models to process emails and offer assistance features like thread summaries, smart replies, event agendas and follow-up reminders. .. note:: The supported languages depend on the used large language model. @@ -117,3 +117,20 @@ The feature is opt-in, it is disabled by default and can be enabled in mail admi Administration settings > Groupware > Mail app > Enable thread summary +Follow-up reminders +------------------- + +.. versionadded:: 4.0 + +The Mail app will automatically remind users when their outgoing emails remain unanswered for +multiple days. +Each sent email will be analyzed by an AI to check whether a reply is expected. + +The feature can be enabled through the global :ref:`mail_llm_processing` setting. + +Translation +----------- + +.. versionadded:: 4.2 + +The mail app can optionally provide translations for messages if the :ref:`translation API ` is enabled. diff --git a/admin_manual/images/user-config-actions.png b/admin_manual/images/user-config-actions.png new file mode 100644 index 000000000..4bf2bd344 Binary files /dev/null and b/admin_manual/images/user-config-actions.png differ diff --git a/admin_manual/images/user-config-group-admin.png b/admin_manual/images/user-config-group-admin.png new file mode 100644 index 000000000..8c2ceacb8 Binary files /dev/null and b/admin_manual/images/user-config-group-admin.png differ diff --git a/admin_manual/images/user-config-groups.png b/admin_manual/images/user-config-groups.png new file mode 100644 index 000000000..2d41fb899 Binary files /dev/null and b/admin_manual/images/user-config-groups.png differ diff --git a/admin_manual/images/user-config-new-user.png b/admin_manual/images/user-config-new-user.png new file mode 100644 index 000000000..2751e9347 Binary files /dev/null and b/admin_manual/images/user-config-new-user.png differ diff --git a/admin_manual/images/user-config-settings.png b/admin_manual/images/user-config-settings.png new file mode 100644 index 000000000..6f1ff6ccf Binary files /dev/null and b/admin_manual/images/user-config-settings.png differ diff --git a/admin_manual/images/user-config.png b/admin_manual/images/user-config.png new file mode 100644 index 000000000..1e7395a6b Binary files /dev/null and b/admin_manual/images/user-config.png differ diff --git a/admin_manual/images/users-actions.png b/admin_manual/images/users-actions.png deleted file mode 100644 index d675d5290..000000000 Binary files a/admin_manual/images/users-actions.png and /dev/null differ diff --git a/admin_manual/images/users-config-1.png b/admin_manual/images/users-config-1.png deleted file mode 100644 index 33f13d550..000000000 Binary files a/admin_manual/images/users-config-1.png and /dev/null differ diff --git a/admin_manual/images/users-config-2.png b/admin_manual/images/users-config-2.png deleted file mode 100644 index 65c2b960e..000000000 Binary files a/admin_manual/images/users-config-2.png and /dev/null differ diff --git a/admin_manual/images/users-config.png b/admin_manual/images/users-config.png deleted file mode 100644 index 649aa7fff..000000000 Binary files a/admin_manual/images/users-config.png and /dev/null differ diff --git a/admin_manual/images/users-create.png b/admin_manual/images/users-create.png deleted file mode 100644 index 58ea55cbd..000000000 Binary files a/admin_manual/images/users-create.png and /dev/null differ diff --git a/admin_manual/images/users-groups.png b/admin_manual/images/users-groups.png deleted file mode 100644 index d6fbb569e..000000000 Binary files a/admin_manual/images/users-groups.png and /dev/null differ diff --git a/admin_manual/installation/apps_supported.rst b/admin_manual/installation/apps_supported.rst deleted file mode 100644 index 051555a99..000000000 --- a/admin_manual/installation/apps_supported.rst +++ /dev/null @@ -1,93 +0,0 @@ -============== -Supported apps -============== - -Below is the list of apps supported for Nextcloud |version|. Supported here means that we'll accept bugreports and resolve them in these apps with regard to functionality and compatibility with Nextcloud |version|. To get access to work-arounds, long term support, priority bug fixing and custom consulting, contact Nextcloud GmbH. - -All apps are licensed under ``AGPLv3``. - -Nextcloud Files ---------------- - -* `Activity `_ -* `Auditing / Logging `_ -* `Antivirus for files `_ -* `Brute-force settings `_ -* `Circles `_ -* `Collaborative Tags `_ -* `Comments `_ -* `Contacts Interaction `_ -* `Data Request `_ -* `Default encryption module `_ -* `Deleted files `_ -* `External Sites `_ -* `External storage support `_ -* `Federated file sharing `_ -* `Federation `_ -* `File sharing `_ -* `Files access control `_ -* `Files `_ -* `Files Automated Tagging `_ -* `Files download limit `_ -* `First run wizard `_ -* `Flow `_ -* `Full Text Search `_ -* `Full Text Search - Elasticsearch Platform `_ -* `Full Text Search - Files `_ -* `Full Text Search - Tesseract OCR `_ -* `Group folders `_ -* `Guests `_ -* `LDAP user and group backend `_ -* `Log Reader `_ -* `Monitoring `_ -* `Nextcloud announcements `_ -* `Notifications `_ -* `Password policy `_ -* `PDF Viewer `_ -* `Photos `_ -* `Provisioning API `_ -* `Recommendations `_ -* `Related Resources `_ -* `Share by mail `_ -* `SharePoint Backend `_ -* `Suspicious Login `_ -* `SSO & SAML authentication `_ -* Social sharing via: - * `Diaspora `_ - * `Email `_ - * `Facebook `_ - * `Twitter `_ -* `Terms of Service `_ -* `Text `_ -* `Theming `_ -* `Two-Factor backup codes `_ -* `Two-Factor TOTP Provider `_ -* `Two-Factor WebAuthn `_ -* `Update Notifications `_ -* `Versions `_ -* `WebDAV endpoint `_ - -Nextcloud Groupware -------------------- - -* `Calendar `_ -* `Contacts `_ -* `Deck `_ -* `Mail `_ - -Nextcloud Talk --------------- - -* `Talk `_ - -Collaborative editing ---------------------- - -* `Collabora Online `_ -* `ONLYOFFICE `_ - -Global Scale ------------- - -* `Global Site Selector `_ -* `Lookup Server Connector `_ diff --git a/admin_manual/installation/example_centos.rst b/admin_manual/installation/example_centos.rst index 664ed2084..16f987a17 100644 --- a/admin_manual/installation/example_centos.rst +++ b/admin_manual/installation/example_centos.rst @@ -91,7 +91,7 @@ You have to enable the module stream for 8.2: Installing PHP and the required modules ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Next, install the PHP modules needed for this install. Remember, because this is a limited basic install, we only install the neccessary modules, not all of them. If you are making a more complete install, please refer to PHP module list in the source installation documentation, :doc:`../installation/source_installation`:: +Next, install the PHP modules needed for this install. Remember, because this is a limited basic install, we only install the necessary modules, not all of them. If you are making a more complete install, please refer to PHP module list in the source installation documentation, :doc:`../installation/source_installation`:: dnf install -y php php-cli php-gd php-mbstring php-intl php-pecl-apcu\ php-mysqlnd php-opcache php-json php-zip diff --git a/admin_manual/installation/example_openbsd.rst b/admin_manual/installation/example_openbsd.rst index ef7bdd525..d4cd57147 100644 --- a/admin_manual/installation/example_openbsd.rst +++ b/admin_manual/installation/example_openbsd.rst @@ -114,7 +114,6 @@ It is recommended to add opcache to it:: [opcache] opcache.enable=1 - opcache.enable_cli=1 opcache.memory_consumption=512 opcache.interned_strings_buffer=8 opcache.max_accelerated_files=10000 @@ -208,7 +207,7 @@ Since in OpenBSD httpd(8) works with a chroot(8) by default, we need to be sure Nextcloud final steps --------------------- -Now that we have all in place, you should go to your browser with your URL (I am asuming you have an SSL already installed):: +Now that we have all in place, you should go to your browser with your URL (I am assuming you have an SSL already installed):: https://domain.tld diff --git a/admin_manual/installation/example_ubuntu.rst b/admin_manual/installation/example_ubuntu.rst index cd1890d7d..af0b08092 100644 --- a/admin_manual/installation/example_ubuntu.rst +++ b/admin_manual/installation/example_ubuntu.rst @@ -10,7 +10,7 @@ following commands in a terminal:: sudo apt update && sudo apt upgrade sudo apt install apache2 mariadb-server libapache2-mod-php php-gd php-mysql \ - php-curl php-mbstring php-intl php-gmp php-bcmath php-xml php-imagick php-zip + php-curl php-mbstring php-intl php-gmp php-xml php-imagick php-zip * This installs the packages for the Nextcloud core system. If you are planning on running additional apps, keep in mind that they might diff --git a/admin_manual/installation/harden_server.rst b/admin_manual/installation/harden_server.rst index 6ded9171d..7d1c1c906 100644 --- a/admin_manual/installation/harden_server.rst +++ b/admin_manual/installation/harden_server.rst @@ -177,6 +177,23 @@ information about the TLS settings. Also ensure that HTTP compression is disabled to mitigate the BREACH attack. +Restrict admin actions to a specific range of IP addresses +---------------------------------------------------------- + +Configure ``allowed_admin_ranges`` in ``config.php`` to restrict the admin actions to trusted IP ranges. + +This can be achieved with this kind of setting, usually using private IP ranges:: + + 'allowed_admin_ranges' => [ + '127.0.0.1/8', + '192.168.0.0/16', + 'fd00::/8', + ], + +All requests originating from IP addresses outside of these ranges will not be able to execute admin actions. + +Administrators connected from untrusted IP addresses will be able to use Nextcloud, but all admin specific actions will be hidden. + Use a dedicated domain for Nextcloud ------------------------------------ @@ -236,7 +253,7 @@ security headers are shipped. Connections to remote servers ----------------------------- -Some functionalites require the Nextcloud server to be able to connect remote systems via https/443. +Some functionalities require the Nextcloud server to be able to connect remote systems via https/443. This paragraph also includes the data which is being transmitted to the Nextcloud GmbH. Depending on your server setup, these are the possible connections: @@ -252,7 +269,7 @@ Depending on your server setup, these are the possible connections: - apps.nextcloud.com - to check for available apps and their updates - submitted data: subscription key -- github.com +- github.com, objects.githubusercontent.com - to download Nextcloud standard apps - push-notifications.nextcloud.com - sending push notifications to mobile clients @@ -273,6 +290,8 @@ Depending on your server setup, these are the possible connections: .. _optional (config): https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#has-internet-connection .. _detailed field list : https://github.com/nextcloud/survey_client +.. TODO ON RELEASE: Update version number above on release + Setup fail2ban -------------- @@ -280,6 +299,26 @@ Setup fail2ban 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 +system level, so the webserver, PHP and the database do not need to handle this +unnecessary traffic at all. + +Nextcloud prerequisites +^^^^^^^^^^^^^^^^^^^^^^^ + +Nextcloud logs failed login attempts in ``nextcloud.log`` with log level ``2``, +so you need to define a ``loglevel`` of ``2`` or less in ``config.php``. + +Make sure your ``nextcloud.log`` is writeable by your webserver user, possibly by +defining a correct ``logfilemode`` in ``config.php``. + +Perform a bad login attempt and check whether it does get logged to ``nextcloud.log``. + +Note that ``audit.log`` (if enabled) currently only logs successful logins and cannot be used. + +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 the configured services. @@ -335,4 +374,13 @@ running:: fail2ban-client status nextcloud +If you need to unban certain IP addresses (``1.2.3.4`` in this example), +you may do so by issuing:: + + fail2ban-client unban 1.2.3.4 + +There may be scenarios where you want to more permantently ban certain IP +addresses that repeatedly generate bad login attempts (or other attacks) by +using fail2ban's ``recidive`` feature. + .. _fail2ban download page: https://www.fail2ban.org/wiki/index.php/Downloads diff --git a/admin_manual/installation/index.rst b/admin_manual/installation/index.rst index b8865943c..fb0082c61 100644 --- a/admin_manual/installation/index.rst +++ b/admin_manual/installation/index.rst @@ -11,7 +11,6 @@ Installation and server configuration source_installation installation_wizard command_line_installation - apps_supported selinux_configuration nginx harden_server @@ -20,3 +19,5 @@ Installation and server configuration example_ubuntu example_centos example_openbsd + + uninstallation diff --git a/admin_manual/installation/nginx-root.conf.sample b/admin_manual/installation/nginx-root.conf.sample index fd8e8fe9d..c2aff0630 100644 --- a/admin_manual/installation/nginx-root.conf.sample +++ b/admin_manual/installation/nginx-root.conf.sample @@ -1,3 +1,5 @@ +# Version 2024-07-17 + upstream php-handler { server 127.0.0.1:9000; #server unix:/run/php/php8.2-fpm.sock; @@ -22,8 +24,12 @@ server { } server { - listen 443 ssl http2; + listen 443 ssl http2; listen [::]:443 ssl http2; + # With NGinx >= 1.25.1 you should use this instead: + # listen 443 ssl; + # listen [::]:443 ssl; + # http2 on; server_name cloud.example.com; # Path to the root of your installation @@ -165,7 +171,7 @@ server { } # Serve static files - location ~ \.(?:css|js|mjs|svg|gif|png|jpg|ico|wasm|tflite|map|ogg|flac)$ { + location ~ \.(?:css|js|mjs|svg|gif|ico|jpg|png|webp|wasm|tflite|map|ogg|flac)$ { try_files $uri /index.php$request_uri; # HTTP response headers borrowed from Nextcloud `.htaccess` add_header Cache-Control "public, max-age=15778463$asset_immutable"; @@ -178,7 +184,7 @@ server { access_log off; # Optional: Don't log access to assets } - location ~ \.woff2?$ { + location ~ \.(otf|woff2?)$ { try_files $uri /index.php$request_uri; expires 7d; # Cache-Control policy borrowed from `.htaccess` access_log off; # Optional: Don't log access to assets diff --git a/admin_manual/installation/nginx-subdir.conf.sample b/admin_manual/installation/nginx-subdir.conf.sample index bbfbae2d8..5ad2eca1f 100644 --- a/admin_manual/installation/nginx-subdir.conf.sample +++ b/admin_manual/installation/nginx-subdir.conf.sample @@ -26,6 +26,10 @@ server { server { listen 443 ssl http2; listen [::]:443 ssl http2; + # With NGinx >= 1.25.1 you should use this instead: + # listen 443 ssl; + # listen [::]:443 ssl; + # http2 on; server_name cloud.example.com; # Path to the root of the domain @@ -164,7 +168,7 @@ server { } # Serve static files - location ~ \.(?:css|js|mjs|svg|gif|png|jpg|ico|wasm|tflite|map|ogg|flac)$ { + location ~ \.(?:css|js|mjs|svg|gif|ico|jpg|png|webp|wasm|tflite|map|ogg|flac)$ { try_files $uri /nextcloud/index.php$request_uri; # HTTP response headers borrowed from Nextcloud `.htaccess` add_header Cache-Control "public, max-age=15778463$asset_immutable"; @@ -177,7 +181,7 @@ server { access_log off; # Optional: Don't log access to assets } - location ~ \.woff2?$ { + location ~ \.(otf|woff2?)$ { try_files $uri /nextcloud/index.php$request_uri; expires 7d; # Cache-Control policy borrowed from `.htaccess` access_log off; # Optional: Don't log access to assets diff --git a/admin_manual/installation/nginx.rst b/admin_manual/installation/nginx.rst index c1e80985a..4d8580be7 100644 --- a/admin_manual/installation/nginx.rst +++ b/admin_manual/installation/nginx.rst @@ -5,14 +5,15 @@ NGINX configuration =================== .. warning:: - Please note that webservers other than Apache 2.x are not officially supported. + Please note that web servers other than Apache 2.x are not officially supported. .. note:: This page covers example NGINX configurations to run a Nextcloud server. These configurations examples were originally provided by `@josh4trunks `_ and are exclusively community-maintained. (Thank you contributors!) -- You need to insert the following code into **your Nginx configuration file**. 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`). +- You need to insert the following code into **your Nginx configuration file**. + 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 @@ -139,6 +140,8 @@ to the following to re-allow file uploads: See `issue #8802 on nextcloud/server `_ for more information. +Other parameters besides the above are relevant to uploading large files (see :ref:`uploading_big_files`). + Login loop without any clue in access.log, error.log, nor nextcloud.log ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/admin_manual/installation/php_configuration.rst b/admin_manual/installation/php_configuration.rst index 4159d6eff..3171bc9c2 100644 --- a/admin_manual/installation/php_configuration.rst +++ b/admin_manual/installation/php_configuration.rst @@ -44,7 +44,7 @@ Database connectors (pick the one for your database): * PHP module intl (increases language translation performance and fixes sorting of non-ASCII characters) -* PHP module sodium (for Argon2 for password hashing. bcrypt is used as fallback, but if passwords were hashed with Argon2 already and the module is missing, your users can't log in. Included with PHP >= 7.2) +* PHP module sodium (for Argon2 for password hashing when PHP < 8.4 is used and PHP was built without libargon2. bcrypt is used as fallback, but if passwords were hashed with Argon2 already and the module is missing, your users can't log in.) Required for specific apps: @@ -53,8 +53,6 @@ Required for specific apps: :doc:`../configuration_files/external_storage/smb`) * PHP module ftp (for FTP storage / external user authentication) * PHP module imap (for external user authentication) -* PHP module bcmath (for passwordless login) -* PHP module gmp (for passwordless login) Recommended for specific apps (*optional*): @@ -98,7 +96,6 @@ ini values The following ini settings should be adapted if needed for Nextcloud: -* ``apc.enable_cli``: see :doc:`../configuration_server/caching_configuration` * ``disable_functions``: avoid disabling functions unless you know exactly what you are doing * ``max_execution_time``: see :doc:`../configuration_files/big_file_upload_configuration` * ``memory_limit``: should be at least 512MB. See also :doc:`../configuration_files/big_file_upload_configuration` @@ -129,4 +126,4 @@ You can search for a parameter with the following command: ``grep -r date.timezo /etc/php/8.3/cli/php.ini .. note:: Path names have to be set in respect of the installed PHP - (8.1, 8.2 or 8.3) as applicable. + (8.1, 8.2, 8.3 or 8.4) as applicable. diff --git a/admin_manual/installation/server_tuning.rst b/admin_manual/installation/server_tuning.rst index 45ca9d781..0584f69ea 100644 --- a/admin_manual/installation/server_tuning.rst +++ b/admin_manual/installation/server_tuning.rst @@ -39,7 +39,7 @@ Debug Mode Verify that ``debug`` is ``false`` in your ``config.php``. 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 faciliate easier debugging) and generates additional +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 outside of isolated troubleshooting situations. @@ -128,13 +128,31 @@ more processes to run in parallel to handle the requests. Enable PHP OPcache ------------------ -The `OPcache `_ improves the performance of PHP applications by caching precompiled bytecode. The default OPcache settings are usually sufficient for Nextcloud code to be fully cached. If any cache size limit is reached by more than 90%, the admin panel will show a related warning. Nextcloud strictly requires code comments to be preserved in opcode, which is the default. But in case PHP settings are changed on your system, you may need set the following: +The `OPcache `_ improves the performance of PHP applications by caching precompiled bytecode. -.. code:: ini +Revalidation +^^^^^^^^^^^^ - opcache.save_comments = 1 +OPcache revalidation in PHP handles changes made to PHP application code stored on disk. Code changes occur whenever: -By default, cached scripts are revalidated on access to ensure that changes on disk take effect after at most ``2`` seconds. Since Nextcloud handles cache revalidation internally when required, the revalidation frequency can be reduced or completely disabled to enhance performance. Note, however, that it affects manual changes to scripts, including ``config.php``. To check for changes at most every ``60`` seconds, use the following setting: +- Nextcloud or a Nextcloud app is upgraded +- a configuration change is made (e.g. ``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 revalidated to ensure that changes (on disk) take effect every ``2`` seconds. In many environments, these default +values are reasonable (and may never need to be changed). + +However, the revalidation frequency can be adjusted and may *potentially* enhance performance. We make no recommendations here about appropriate values for revalidation (other than the PHP defaults). + +.. danger:: + Lengthening the time between revalidation (or disabling it completely) means that manual changes to scripts, including ``config.php``, will take longer before they become active (or will never do so, if + revalidation is disabled completely). Lengthening also increases the likelihood of transient server and application upgrade problems. It also prevents the proper toggling of maintenance mode. + +.. warning:: + If you adjust these parameters, you are more likely to need to restart/reload your web server (mod_php) or fpm after making configuration changes or performing upgrades. If you forget to do so, you + will likely experience unusual behavior due to a mismatch between what is on disk and is in memory. These may appear to be bugs, but will go away as soon as you restart/reload mod_php/fpm. + +To change the default from ``2`` and check for changes on disk at most every ``60`` seconds, use the following setting: .. code:: ini @@ -146,16 +164,42 @@ To disable the revalidation completely: opcache.validate_timestamps = 0 -Any change to ``config.php`` will then require either restarting PHP, manually clearing the cache, or invalidating this particular script. +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). -For more details check out the `official documentation `_. To monitor OPcache usage, clear individual or all cache entries, `opcache-gui `_ can be used. +.. warning:: + To avoid false reports, if your environment isn't using the PHP default revalidation values, please do not report bugs/odd behavior after upgrading Nextcloud or Nextcloud apps until after you've + restarted mod_php/fpm (to confirm they are not simply caused by local revalidation configuration). -PHP 8.0 and above ship with a JIT compiler that can be enabled to benefit any CPU intensive apps you might be running. To enable a tracing JIT with all optimizations: +Sizing +^^^^^^ + +If any cache size limit is reached by more than 90%, the admin panel will show a related warning and suggested changes. + +For more details check out the `official PHP documentation `_. To monitor OPcache usage, clear individual or all cache entries, `opcache-gui `_ can be used. + +Comments +^^^^^^^^ + +Nextcloud strictly requires code comments to be preserved in opcode, which is the default. But in case PHP settings are changed on your system, you may need set the following: + +.. code:: ini + + opcache.save_comments = 1 + +JIT +^^^ + +PHP 8.0 and above ship with a JIT compiler that can be enabled on x86 platforms to benefit any CPU intensive apps you might be running. To enable a tracing JIT with all optimizations: .. code:: ini opcache.jit = 1255 - opcache.jit_buffer_size = 128M + opcache.jit_buffer_size = 8M + +.. note:: + + Single Nextcloud instances have shown to use less than 2 MiB of the configured JIT buffer size, so that 8 MiB is sufficient by a large margin. The overall OPcache usage however raises by a larger amount, so that ``opcache.memory_consumption`` might need to be raised in some cases. The Nextcloud admin panel will then show a related warning. + JIT buffer usage can be monitored with `opcache-gui `_ as well. Previews -------- @@ -168,13 +212,8 @@ external microservice: `Imaginary `_. Imaginary is currently incompatible with server-side-encryption. See https://github.com/nextcloud/server/issues/34262 -.. warning:: - - Imaginary is currently known to have issues with HEIC images. - See https://github.com/nextcloud/server/issues/35643 - We strongly recommend running our custom docker image that is more up to date than the official image. -You can find the image at `docker.io/nextcloud/aio-imaginary:latest`. +You can find the image at `https://hub.docker.com/r/nextcloud/aio-imaginary`. To do so, you will need to deploy the service and make sure that it is not accessible from outside of your servers. Then you can configure @@ -202,8 +241,8 @@ Nextcloud to use Imaginary by editing your `config.php`: For large instance, you should follow `Imaginary's scalability recommendation `. -Settings: -^^^^^^^^^ +Settings +^^^^^^^^ If you want set the preview format for imaginary. You can change between jpeg and webp, the default is jpeg: diff --git a/admin_manual/installation/source_installation.rst b/admin_manual/installation/source_installation.rst index c74601efc..dd36ded2a 100644 --- a/admin_manual/installation/source_installation.rst +++ b/admin_manual/installation/source_installation.rst @@ -14,6 +14,8 @@ If you prefer an automated installation, you have the option to: .. note:: Please note that the community options are not officially supported by Nextcloud GmbH. +.. tip:: For an enterprise-ready and scalable installation based on Helm Charts (also available for Podman), please `contact Nextcloud GmbH `_. + In case you prefer installing from the source tarball, you can setup Nextcloud from scratch using a classic LAMP stack (Linux, Apache, MySQL/MariaDB, PHP). This document provides a complete walk-through for installing Nextcloud on @@ -120,6 +122,14 @@ Additional Apache configurations a2enmod setenvif + and apply the following modifications the configuration:: + + ProxyFCGIBackendType FPM + + + SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 + + * You must disable any server-configured authentication for Nextcloud, as it uses Basic authentication internally for DAV services. If you have turned on authentication on a parent folder (via e.g. an ``AuthType Basic`` @@ -234,16 +244,41 @@ SELinux-enabled distributions such as Fedora and CentOS. .. _php_fpm_tips_label: -php-fpm configuration notes ---------------------------- +PHP-FPM configuration +--------------------- -**System environment variables** +Overview +^^^^^^^^ + +`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 +should be adjusted. + +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 +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 severely 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. + +System environment variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When you are using ``php-fpm``, system environment variables like PATH, TMP or others are not automatically populated in the same way as when using ``php-cli``. A PHP call like ``getenv('PATH');`` can therefore return an empty result. So you may need to manually configure environment -variables in the appropropriate ``php-fpm`` ini/config file. +variables in the appropriate ``php-fpm`` ini/config file. Here are some example root paths for these ini/config files: @@ -292,14 +327,16 @@ Please keep in mind that it is possible to create different settings for ``php-cli`` and ``php-fpm``, and for different domains and Web sites. The best way to check your settings is with :ref:`label-phpinfo`. -**Maximum upload size** +Maximum upload size +^^^^^^^^^^^^^^^^^^^ If you want to increase the maximum upload size, you will also have to modify your ``php-fpm`` configuration and increase the ``upload_max_filesize`` and ``post_max_size`` values. You will need to restart ``php-fpm`` and your HTTP server in order for these changes to be applied. -**.htaccess notes for Apache** +.htaccess +^^^^^^^^^ Nextcloud comes with its own ``nextcloud/.htaccess`` file. Because ``php-fpm`` can't read PHP settings in ``.htaccess`` these settings and permissions must @@ -341,7 +378,7 @@ Download the the Appliance here: The `Nextcloud VM`_ is maintained by `T&M Hansson IT `_ and several different versions are -offered. Collabora, OnlyOffice, Full Text Search and other apps can easily be installed with the included scripts which you can choose to run during the first setup, or download them later and run it afterwards. You can find all the currently available automated app installations `on GitHub `_. +offered. Collabora, OnlyOffice, Full Text Search and other apps can easily be installed with the included scripts which you can choose to run during the first setup, or download them later and run it afterwards. You can find all the currently available automated app installations `on GitHub `_. The VM comes in different sizes and versions. @@ -406,14 +443,14 @@ Installation via install script One of the easiest ways of installing is to use the Nextcloud VM or NextcloudPI scripts. It's basically just two steps: -1. Download the latest `VM installation script `_. +1. Download the latest `VM installation script `_. 2. Run the script with:: sudo bash nextcloud_install_production.sh or -1. Download the latest `PI installation script `_. +1. Download the latest `PI installation script `_. 2. Run the script with:: sudo bash install.sh diff --git a/admin_manual/installation/system_requirements.rst b/admin_manual/installation/system_requirements.rst index 8549df69f..6dda025c5 100644 --- a/admin_manual/installation/system_requirements.rst +++ b/admin_manual/installation/system_requirements.rst @@ -14,19 +14,21 @@ For best performance, stability and functionality we have documented some recomm +------------------+-----------------------------------------------------------------------+ | Platform | Options | +==================+=======================================================================+ -| Operating System | - **Ubuntu 22.04 LTS** (recommended) | -| (64-bit) | - Ubuntu 20.04 LTS | +| Operating System | - Ubuntu 24.04 LTS | +| (64-bit) | - **Ubuntu 22.04 LTS** (recommended) | | | - **Red Hat Enterprise Linux 9** (recommended) | | | - Red Hat Enterprise Linux 8 | | | - Debian 12 (Bookworm) | | | - SUSE Linux Enterprise Server 15 | | | - openSUSE Leap 15.5 | | | - CentOS Stream | +| | - Alpine Linux | +------------------+-----------------------------------------------------------------------+ -| Database | - **MySQL 8.0+** or MariaDB 10.3/10.5/**10.6** (recommended)/10.11 | -| | - Oracle Database 11g (*only as part of an enterprise subscription*) | -| | - PostgreSQL 12/13/14/15/16 | -| | - SQLite (*only recommended for testing and minimal-instances*) | +| Database | - MySQL 8.0 / **8.4** or MariaDB 10.6/ **10.11** (recommended) / 11.4 | +| | - Oracle Database 11g, 18, 21, 23 | +| | (*only as part of an enterprise subscription*) | +| | - PostgreSQL 13/14/15/16/17 | +| | - SQLite 3.24+ (*only recommended for testing and minimal-instances*) | +------------------+-----------------------------------------------------------------------+ | Webserver | - **Apache 2.4 with** ``mod_php`` **or** ``php-fpm`` (recommended) | | | - nginx with ``php-fpm`` | @@ -34,6 +36,7 @@ For best performance, stability and functionality we have documented some recomm | PHP Runtime | - 8.1 (*deprecated*) | | | - 8.2 | | | - **8.3** (*recommended*) | +| | - 8.4 | +------------------+-----------------------------------------------------------------------+ See :doc:`source_installation` for minimum PHP-modules and additional software for installing Nextcloud. @@ -103,6 +106,7 @@ of our clients. * **Windows** 10+ * **macOS** Lion (10.14)+ (64-bits only) + * Please note that your server may need to be Apple App Transport Security compliant in order for the desktop client to connect successfully. This may involve using a digital certificate that is adequately signed to the standards established by Apple. More information is provided by Apple in their developer documentation: https://developer.apple.com/documentation/security/preventing-insecure-network-connections * **Linux** (64-bits only) Should run on any distribution newer than Ubuntu 18.04 with our official AppImage package Mobile apps @@ -121,11 +125,9 @@ Talk App ^^^^^^^^ - **iOS** 15.0+ -- **Android** 7.0+ -- **Nextcloud Server** 14.0+ -- **Nextcloud Talk** 4.0+ - -.. note:: When using Nextcloud Talk 12.0+ please update the Android Talk App to the newest version (or at least to v12.1). +- **Android** 8.0+ +- **Nextcloud Server** 19.0+ +- **Nextcloud Talk** 9.0+ Web browser ----------- diff --git a/admin_manual/installation/uninstallation.rst b/admin_manual/installation/uninstallation.rst new file mode 100644 index 000000000..b2bc8d18a --- /dev/null +++ b/admin_manual/installation/uninstallation.rst @@ -0,0 +1,24 @@ +============== +Uninstallation +============== + +The application is stored in a server directory and works with a database to store the metadata for files and their shares (EFSS functionality). + +There are no general uninstallation instructions, as Nextcloud offers a high degree of flexibility with regard to the operating model or operating platform; examples include abstract containers, virtual machines or “bare metal”, i.e. installation directly on one or more servers. + +It is therefore important for the uninstallation to understand where the Nextcloud application is installed and where the corresponding data is located. + +- Application directory (created before installation) +- File storage of the users (configured within the application directory or outside) +- Metadata storage in the database (within the application directory when using SQLite or outside on the same or another server) +- Caching via Redis server or similar (if used) + +For uninstallation, a decision must be made as to whether the file storage should be backed up or whether the data should also be deleted. In addition, either the corresponding servers must be completely deprovisioned or the application directory deleted, as well as the database schemas and Redis entries, depending on the deployment scenario. If dedicated containers or virtual machines are used, these must be deprovisioned and the Nextcloud application must also be deprovisioned. + +To uninstall, you can read values from your configuration in ``config`` directory. Check: + +- Source code (manually installed, usually in ``/var/www`` or ``/opt/nextcloud``): remove the directory on all servers +- 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 diff --git a/admin_manual/issues/code_signing.rst b/admin_manual/issues/code_signing.rst index da573a21d..e8e1b6f16 100644 --- a/admin_manual/issues/code_signing.rst +++ b/admin_manual/issues/code_signing.rst @@ -176,7 +176,7 @@ Rescans are triggered at installation, and by updates. You may run scans manuall occ integrity:check-core occ integrity:check-app $appid -See :doc:`../configuration_server/occ_command` to learn more about using ``occ``. +See :doc:`../occ_command` to learn more about using ``occ``. Errors ------ diff --git a/admin_manual/issues/general_troubleshooting.rst b/admin_manual/issues/general_troubleshooting.rst index 178c41f68..c6658bf09 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -51,14 +51,37 @@ different issues. Always disable 3rd party apps before upgrades, and for troubleshooting. Please refer to the :ref:`apps_commands_label` on how to disable an app from command line. -Nextcloud logfiles -^^^^^^^^^^^^^^^^^^ +Internal Server Errors +^^^^^^^^^^^^^^^^^^^^^^ -In a standard Nextcloud installation the log level is set to ``Normal``. To find -any issues you need to raise the log level to ``All`` in your ``config.php`` -file, or to **Everything** on your Nextcloud Admin page. Please see -:doc:`../configuration_server/logging_configuration` for more information on -these log levels. +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 +default) and possibly your web server's error log (depending on where the failure is +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 + with the failing transaction. + +Nextcloud log files +^^^^^^^^^^^^^^^^^^^ + +The Nextcloud log file is located in the data directory by default - e.g. +``data/nextcloud.log``. If the Web UI is still reachable, it is also available +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 + (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 +information on these log levels. Some logging - for example JavaScript console logging - needs debugging enabled. Edit :file:`config/config.php` and change ``'debug' => false,`` to @@ -68,9 +91,6 @@ For JavaScript issues you will also need to view the javascript console. All major browsers have developer tools for viewing the console, and you usually access them by pressing F12. -.. note:: The logfile of Nextcloud is located in the data directory - ``nextcloud/data/nextcloud.log``. - .. _label-phpinfo: PHP version and information @@ -210,6 +230,7 @@ these modules: 3. PHP +* Tideways * eAccelerator .. _trouble-webdav-label: diff --git a/admin_manual/maintenance/manual_upgrade.rst b/admin_manual/maintenance/manual_upgrade.rst index 44aac2d49..4a99bca44 100644 --- a/admin_manual/maintenance/manual_upgrade.rst +++ b/admin_manual/maintenance/manual_upgrade.rst @@ -2,10 +2,26 @@ Upgrade manually ================ -.. seealso:: +Overview +-------- - If you upgrade from a previous major version please see :ref:`critical changes` - first. +In some environments using the Built-in Updater in Web mode is not reliable (such as due to web server +timeouts) and running it in command-line mode is not an option (such as in some shared hosting environments). +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, +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. + +.. important:: + 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 a good idea to revisit them even when proceeding with minor and maintenance upgrades just + in case. .. warning:: @@ -14,6 +30,10 @@ Upgrade manually following the standard :doc:`upgrade requirements <./upgrade>` (such as upgrading to the latest maintenance release *before* upgrading to a new major release). + +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 diff --git a/admin_manual/maintenance/migrating.rst b/admin_manual/maintenance/migrating.rst index 7890d9efc..583b77e79 100644 --- a/admin_manual/maintenance/migrating.rst +++ b/admin_manual/maintenance/migrating.rst @@ -56,9 +56,16 @@ the new location. It is also assumed that the authentication method Depending on the original installation method and the OS the files are located in different locations. On the new system make sure to pick the appropriate locations. If you change any paths, make sure to adapt the paths - in the Nextcloud config.php file. Note: This step might take several hours, - depending on your installation. - + in the Nextcloud config.php file. + + .. note:: + This step might take several hours, depending on your installation. + + .. warning:: + Changing the location of the data directory might cause a corruption of relations + in the database and is not supported. + + #. Check the config.php file of the **ORIGINAL** system to see if it has the ``data-fingerprint`` set to a non-empty value. If this is the case, make sure to also run the ``maintenance:data-fingerprint`` command on the **NEW** diff --git a/admin_manual/maintenance/migrating_owncloud.rst b/admin_manual/maintenance/migrating_owncloud.rst index f5dfc5e33..1650ea6cc 100644 --- a/admin_manual/maintenance/migrating_owncloud.rst +++ b/admin_manual/maintenance/migrating_owncloud.rst @@ -12,13 +12,11 @@ So it is quite easy, to migrate from one ownCloud version to at least one Nextcl However this does only work with versions that are close enough database and code-wise. See the table below for a version map, where migrating is easily possible: -+-------------------+------------------------------+ -| ownCloud | Nextcloud | -+===================+==============================+ -| 10.13.x | 25.0.x (but at least 25.0.2) | -+-------------------+------------------------------+ -| 10.5.x | 20.0.x (but at least 20.0.5) | -+-------------------+------------------------------+ ++-------------------+-------------------------------+ +| ownCloud | Nextcloud | ++===================+===============================+ +| 10.13.x | 25.0.x (but at least 25.0.13) | ++-------------------+-------------------------------+ .. note:: Since ownCloud does not and will not support PHP 8.0 or higher, you need to migrate from ownCloud 10.13.x to Nextcloud 25 and then diff --git a/admin_manual/maintenance/restore.rst b/admin_manual/maintenance/restore.rst index df3a56c8b..9290f146b 100644 --- a/admin_manual/maintenance/restore.rst +++ b/admin_manual/maintenance/restore.rst @@ -82,7 +82,7 @@ PostgreSQL Synchronising with clients after data recovery ---------------------------------------------- -By default the Nextcloud server is considered the authorative source for the data. +By default the Nextcloud server is considered the authoritative source for the data. If the data on the server and the client differs clients will default to fetching the data from the server. @@ -96,9 +96,15 @@ to try an recover as much data as possible. Files missing on the server are therefore recovered from the clients and in case of different content the users will be asked. +This can also help in rare scenarios when the database is newer than the data directory. +The server will restore the data from the clients and preserve the shares. +Until then the files would be visible but not accessible. +A :ref:`files:scan ` is required afterwards to update the database. + .. note:: The usage of `maintenance:data-fingerprint` can cause conflict dialogues and difficulties deleting files on the client. Therefore it's only recommended to prevent dataloss if the backup was outdated. + This command does not require the server to be in maintenance mode. If you are running multiple application servers you will need to make sure the config files are synced between them so that the updated `data-fingerprint` diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst index c1aa2384d..cb5bc215c 100644 --- a/admin_manual/maintenance/update.rst +++ b/admin_manual/maintenance/update.rst @@ -15,18 +15,21 @@ and data, and it automates updating you have paid support or ask for help in the Nextcloud forums to see if your issue can be resolved without downgrading. -You should maintain regular backups (see :doc:`backup`), and make a backup -before every update. The built-in updater does not backup your database or data -directory. +.. danger:: + You should maintain regular backups (see :doc:`backup`), and make a backup + before every update. The built-in updater does not backup your database or data + directory. What does the updater do? ------------------------- .. note:: - The updater itself only replaces the existing files with the ones from the - version it updates to. The migration steps needs to be executed afterwards. - The command line mode provides a way to do this right after the code was - successfully replaced. + 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, + 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 + URL to trigger the migration phase's web UI. The built-in updater performs these operations: @@ -160,18 +163,13 @@ Using the command line based updater The command line based updater works in the exact same way the web based updater works. The steps and checks are the very same. -.. warning:: APCu is disabled by default on CLI which could cause issues with nextcloud's - command line based updater. Please make sure you set the ``apc.enable_cli`` to ``1`` on your ``php.ini`` - config file or append ``--define apc.enable_cli=1`` to the command line based updater call - (like ``sudo -u www-data php --define apc.enable_cli=1 /var/www/nextcloud/updater/updater.phar``). - The steps are basically the same as for the web based updater: 1. You should see a notification at the top of any Nextcloud page when there is a new update available. Go to the admin settings page and scroll to the section "Version". This section has a button to open the updater. This section as well as the update notification is only available if the update - notication app is enabled in the apps management. + notification app is enabled in the apps management. .. image:: images/updater-1-update-available.png @@ -221,7 +219,7 @@ It is possible to run the command line based updater in a non-interactive mode. The updater then doesn't ask any interactive questions. It is assumed that if an update is available it should be installed and the ``occ upgrade`` command is executed as well. After finishing the maintenance mode will be turned off -except an error occured during the ``occ upgrade`` or the replacement of the +except an error occurred during the ``occ upgrade`` or the replacement of the code. To execute this, run the command with the ``--no-interaction`` option. (i.e. @@ -230,3 +228,29 @@ To execute this, run the command with the ``--no-interaction`` option. (i.e. .. image:: images/updater-cli-8-no-interaction.png :class: terminal-image +Troubleshooting +--------------- + +* 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 + 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 + 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. + +* 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 + simply visit the URL of your instance to complete the database migrations and app + upgrade phase. + +* Reach out to the community help forum for assistance (https://help.nextcloud.com) diff --git a/admin_manual/maintenance/upgrade.rst b/admin_manual/maintenance/upgrade.rst index aa209a933..39c4e38b2 100644 --- a/admin_manual/maintenance/upgrade.rst +++ b/admin_manual/maintenance/upgrade.rst @@ -2,28 +2,46 @@ How to upgrade ============== -There are three ways to upgrade your Nextcloud server: +Overview +-------- -* With the :doc:`Updater `. -* :doc:`Manually upgrading ` with the Nextcloud ``.tar`` archive - from our `Download page `_. -* :doc:`Upgrading ` via the snap packages. -* Manually upgrading is also an option for users on shared hosting; download - and unpack the Nextcloud tarball to your PC. Delete your existing Nextcloud - files, except ``data/`` and ``config/`` files, on your hosting account. Then - transfer the new Nextcloud files to your hosting account, again - preserving your existing ``data/`` and ``config/`` files. +The approach used to upgrade your Nextcloud Server depends on your installation type. This +manual mainly focuses on the methods that apply to an Archive based installation. If you installed +using Snap, Docker, a pre-built VM, or a package management tool then refer to the installation +and update instructions for that installation method for the most accurate upgrading inststructions +(generally located at the distribution point for the install method you chose). -When an update is available for your Nextcloud server, you will see a -notification at the top of your Nextcloud Web interface. When you click the -notification it brings you here, to this page. +There are two ways to upgrade an Archive based Nextcloud Server deployment: -**It is best to keep your Nextcloud server upgraded regularly**, and to install -all point releases and major releases. -Major releases are 18, 19 or 20. Point releases are intermediate releases for each major release. For example 18.0.4 and 19.0.2 are point releases. +* With the :doc:`Built-in Updater ` (via the web or command-line interfaces). +* :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. +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 + :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 + 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 +**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 + 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. + +Approaching Upgrades +-------------------- Nextcloud must be upgraded step by step: - * Before you can upgrade to the next major release, Nextcloud upgrades to the latest point release. + * 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 @@ -84,11 +102,11 @@ Maintenance mode You can put your Nextcloud server into maintenance mode before performing upgrades, or for performing troubleshooting or maintenance. Please see -:doc:`../configuration_server/occ_command` to learn how to put your server into +:doc:`../occ_command` to learn how to put your server into the maintenance mode (``maintenance:mode``) or execute repair commands (``maintenance:repair``) with the ``occ`` command. -The :doc:`build-in Updater ` does this for you before replacing the +The :doc:`built-in Updater ` does this for you before replacing the existing Nextcloud code with the code of the new Nextcloud version. ``maintenance:mode`` locks the sessions of logged-in users and prevents new @@ -131,4 +149,4 @@ Those include for example:: $ sudo -u www-data php occ db:add-missing-indices $ sudo -u www-data php occ db:add-missing-primary-keys -You can use the ``--dry-run`` option to output the SQL queries instead of executing them. \ No newline at end of file +You can use the ``--dry-run`` option to output the SQL queries instead of executing them. diff --git a/admin_manual/configuration_server/occ_command.rst b/admin_manual/occ_command.rst similarity index 89% rename from admin_manual/configuration_server/occ_command.rst rename to admin_manual/occ_command.rst index ccd967e16..8ed4a2182 100644 --- a/admin_manual/configuration_server/occ_command.rst +++ b/admin_manual/occ_command.rst @@ -45,6 +45,7 @@ occ command Directory * :ref:`disable_user_label` * :ref:`system_tags_commands_label` * :ref:`antivirus_commands_label` +* :ref:`setupchecks_commands_label` * `Debugging`_ .. _http_user_label: @@ -179,7 +180,7 @@ Enabling autocompletion ----------------------- .. note:: Command autocompletion currently only works if the user you use to execute the occ commands has a profile. - ``www-data`` in most cases is ``nologon`` and therefor **cannot** use this feature. + ``www-data`` in most cases is ``nologon`` and therefore **cannot** use this feature. Autocompletion is available for bash (and bash based consoles). To enable it, you have to run **one** of the following commands:: @@ -267,6 +268,13 @@ Enable an app for specific groups of users:: sudo -u www-data php occ app:enable --groups admin --groups sales files_external files_external enabled for groups: admin, sales +Enable multiple apps simultaneously:: + + sudo -u www-data php occ app:enable app1 app2 app3 + app1 enabled + app2 enabled + app3 enabled + Disable an app:: sudo -u www-data php occ app:disable files_external @@ -300,6 +308,10 @@ To show available update(s) without updating:: sudo -u www-data php occ app:update --showonly +To update an app to an unstable release, for instance News:: + + sudo -u www-data php occ app:update --allow-unstable news + .. _background_jobs_selector_label: Background jobs selector @@ -324,7 +336,7 @@ The other two commands are: * ``background:cron`` * ``background:webcron`` -See :doc:`background_jobs_configuration` to learn more. +See :doc:`configuration_server/background_jobs_configuration` to learn more. .. _config_commands_label: @@ -357,6 +369,7 @@ While setting a configuration value, multiple options are available: .. _Appconfig Concepts: https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/config/appconfig.html#concept-overview +.. TODO ON RELEASE: Update version number above on release You can list all configuration values with one command:: @@ -513,7 +526,9 @@ A set of commands to create and manage addressbooks and calendars:: dav dav:create-addressbook Create a dav addressbook + dav:list-addressbooks List all addressbooks of a user dav:create-calendar Create a dav calendar + dav:create-subscription Create a dav calendar subscription dav:delete-calendar Delete a dav calendar dav:fix-missing-caldav-changes Insert missing calendarchanges rows for existing events dav:list-calendars List all calendars of a user @@ -535,6 +550,20 @@ This example creates a new calendar for molly:: Molly will immediately see these in the Calendar and Contacts apps. +The syntax for ``dav:create-subscription`` is +``dav:create-subscription [user] [name] [url] [optional color]``. This example creates the subscription subscription for the lunar +calendar ``Lunar Calendar`` for the user molly:: + + sudo -u www-data php occ dav:create-subscription molly "Lunar Calendar" webcal://cantonbecker.com/astronomy-calendar/astrocal.ics + +Molly will immediately see this new subscription calendar in the Calendar app. + +Optionally, a color for the new subscription calendar can be passed as a HEX color code:: + + sudo -u www-data php occ dav:create-subscription molly "Lunar Calendar" calendar webcal://cantonbecker.com/astronomy-calendar/astrocal.ics "#ff5733" + +If not set, the theming default color will be used. + ``dav:delete-calendar [--birthday] [-f|--force] []`` deletes the calendar named ``name`` (or the birthday calendar if ``--birthday`` is specified) of the user ``uid``. You can use the force option ``-f`` or @@ -548,11 +577,17 @@ This example will delete the birthday calendar of user molly:: sudo -u www-data php occ dav:delete-calendar --birthday molly -``dav:lists-calendars [user]`` will display a table listing the calendars for a given user. +``dav:list-calendars [user]`` and ``dav:list-addressbooks [user]`` will display a +table listing the calendars or addressbooks for a given user. + This example will list all calendars for user annie:: sudo -u www-data php occ dav:list-calendars annie +This example will list all addressbooks for user annie:: + + sudo -u www-data php occ dav:list-addressbooks annie + ``dav:dav:fix-missing-caldav-changes [user]`` tries to restore calendar sync changes when data in the calendarchanges table has been lost. If the user ID is omitted, the command runs for all users. This can take a while. ``dav::move-calendar [name] [sourceuid] [destinationuid]`` allows the admin @@ -743,18 +778,23 @@ to synchronize federated servers:: File operations --------------- -``occ`` has three commands for managing files in Nextcloud:: +Available ``occ`` commands for the ``files`` namespace:: - files - files:cleanup Cleanup filecache - files:repair-tree Try and repair malformed filesystem tree structures - files:scan Rescan filesystem - files:scan-app-data Rescan the AppData folder - files:transfer-ownership All files' and folders' ownerships are moved to another - user. Outgoing shares are moved as well. - Incoming shares are not moved by default because the - sharing user holds the ownership of the respective files. - There is however an option to enable moving incoming shares. + files:cleanup cleanup filecache + files:copy Copy a file or folder + files:delete Delete a file or folder + files:get Get the contents of a file + files:move Move a file or folder + files:object:delete Delete an object from the object store + files:object:get Get the contents of an object + files:object:put Write a file to the object store + files:put Write contents of a file + files:recommendations:recommend + files:reminders List file reminders + files:repair-tree Try and repair malformed filesystem tree structures + files:scan rescan filesystem + files:scan-app-data rescan the AppData folder + files:transfer-ownership All files and folders are moved to another user - outgoing shares and incoming user file shares (optionally) are moved as well. .. _occ_files_scan_label: @@ -837,6 +877,18 @@ with the files on the actual storage.:: Arguments: folder The appdata subfolder to scan [default: ""] +.. _occ_cleanup_previews: + +Cleanup previews +^^^^^^^^^^^^^^^^ + +``preview:cleanup`` removes all of the server's preview files. This is useful +when changing the previews configuration (sizes, quality or file), and especially +on systems using Object Storage as Primary Storage where the ``appdata_xxx/preview`` +folder can't simply be deleted. + +See :doc:`configuration_files/previews_configuration`. + Cleanup ^^^^^^^ @@ -895,6 +947,8 @@ In this case no sub-directory is created and all files will appear directly in t It is also possible to transfer only one directory along with its contents. This can be useful to restructure your organization or quotas. The ``--path`` argument is given as the path to the directory as seen from the source user:: sudo -u www-data php occ files:transfer-ownership --path="path_to_dir" + +Incoming shares are not moved by default because the sharing user holds the ownership of the respective files. There is however an option to enable moving incoming shares. In case the incoming shares must be transferred as well, use the argument ``--transfer-incoming-shares`` with ``0`` or ``1`` as parameters :: @@ -928,13 +982,18 @@ Commands for handling shares:: Files external -------------- +These commands are used for managing Nextcloud's *External Storage* feature. In +addition to replicating the configuration capabilities in the Web UI, additional +capabilities include exporting / importing configurations, scanning *External +Storage* mounts that require login credentials, and configuring update notifications +(if supported by the storage type). + .. note:: These commands are only available when the "External storage support" app (``files_external``) is enabled. -Commands for managing external storage:: +Available commands for the "files_external" namespace:: - files_external files_external:applicable Manage applicable users and groups for a mount files_external:backends Show available authentication and storage backends files_external:config Manage backend configuration for a mount @@ -942,13 +1001,13 @@ Commands for managing external storage:: files_external:delete Delete an external mount files_external:export Export mount configurations files_external:import Import mount configurations - files_external:list List configured mounts - files_external:option Manage mount options for a mount - files_external:verify Verify mount configuration + files_external:list List configured admin or personal mounts files_external:notify Listen for active update notifications for a configured external mount + files_external:option Manage mount options for a mount + files_external:scan Scan an external storage for changed files + files_external:verify Verify mount configuration -These commands replicate the functionality in the Nextcloud Web GUI, plus two new -features: ``files_external:export`` and ``files_external:import``. +``files_external:scan`` provides the ability to provide a username and/or password for cases where login credentials are used. Use ``files_external:export`` to export all admin mounts to stdout, and ``files_external:export [user_id]`` to export the mounts of the specified @@ -1141,6 +1200,7 @@ backups and other tasks that require locking users out until you are finished:: maintenance:repair repair this installation maintenance:theme:update Apply custom theme changes maintenance:update:htaccess Updates the .htaccess file + maintenance:repair-share-owner Fix some shares owner if it felt out of sync ``maintenance:mode`` locks the sessions of all logged-in users, including administrators, and displays a status screen warning that the server is in @@ -1168,7 +1228,7 @@ mimetype, run ``maintenance:mimetype:update-db --repair-filecache`` to apply the change to existing files. Run the ``maintenance:theme:update`` command if the icons of your custom theme are not -updated correctly. This updates the mimetypelist.js and cleares the image cache. +updated correctly. This updates the mimetypelist.js and clears the image cache. .. _security_commands_label: @@ -1176,7 +1236,7 @@ Security -------- Use these commands to manage server-wide security related parameters. Currently this -includes :doc:`bruteforce_configuration` and SSL certificates (the latter are useful when +includes :doc:`configuration_server/bruteforce_configuration` and SSL certificates (the latter are useful when creating federation connections with other Nextcloud servers that use self-signed certificates:: security @@ -1272,14 +1332,16 @@ units. Trashbin -------- -:: +These commands allow for manually managing various aspects of the trash bin (deleted files):: trashbin - trashbin:cleanup [--all-users] [--] [...] Permanently remove deleted files - trashbin:restore [--all-users] [--scope[=SCOPE]] [--since[=SINCE]] [--until[=UNTIL]] [--dry-run] [--] [...] Restore deleted files according to the given filters + trashbin:cleanup Permanently remove deleted files + trashbin:expire Expires the users trashbin + trashbin:size Configure the target trashbin size + trashbin:restore Restore all deleted files according to the given filters .. note:: - This command is only available when the "Deleted files" app + These commands are only available when the "Deleted files" app (``files_trashbin``) is enabled. The ``trashbin:cleanup [--all-users] [--] [...]`` command removes the deleted files of the specified @@ -1338,16 +1400,21 @@ The ``--dry-run`` option can be used to simulate the restore without actually re User commands ------------- -The ``user`` commands create and remove users, reset passwords, display a simple +The ``user`` commands create and remove users, reset passwords, manage authentication tokens / sessions, display a simple report showing how many users you have, and when a user was last logged in:: user user:add adds a user - user:add-app-password adds a app password named "cli" + user:add-app-password adds a app password named "cli" (deprecated: alias for user:auth-tokens:add) + user:auth-tokens:add Add app password for the named account + user:auth-tokens:delete Deletes an authentication token + user:auth-tokens:list List authentication tokens of an user + user:clear-avatar-cache clear avatar cache user:delete deletes the specified user user:disable disables the specified user user:enable enables the specified user user:info shows information about the specific user + user:keys:verify Verify if the stored public key matches the stored private key user:lastseen shows when the user was logged in last time user:list shows list of all registered users user:report shows how many users have access @@ -1357,10 +1424,13 @@ report showing how many users you have, and when a user was last logged in:: the stored private key +user:add +^^^^^^^^ + You can create a new user with their display name, login name, and any group memberships with the ``user:add`` command. The syntax is:: - user:add [--password-from-env] [--display-name[="..."]] [-g|--group[="..."]] + user:add [--password-from-env] [--generate-password] [--display-name[="..."]] [-g|--group[="..."]] [--email EMAIL] uid The ``display-name`` corresponds to the **Full Name** on the Users page in your @@ -1396,6 +1466,29 @@ Jones:: Display name set to "Fred Jones" User "fred" added to group "users" +``generate-password`` allows you to set a securely generated password for the user. +This is never shown in the output and can be used to create users with temporary +passwords. This can be used in conjunction with the ``email`` option to create +users with a temporary password and send a welcome email to the user's email +address without user interaction:: + + sudo -u www-data php occ user:add layla --generate-password --email layla@example.tld + The account "layla" was created successfully + Welcome email sent to layla@example.tld + +The ``email`` option allows you to set the user's email address when creating +the user. A welcome email will be sent to the user's email address if +``newUser.sendEmail`` is set to ``yes`` in ``core``'s app config or not set at all:: + + sudo -u www-data php occ user:add layla --email layla@example.tld + Enter password: + Confirm password: + The account "layla" was created successfully + Welcome email sent to layla@example.tld + +user:resetpassword +^^^^^^^^^^^^^^^^^^ + You can reset any user's password, including administrators (see :doc:`../configuration_user/reset_admin_password`):: @@ -1411,10 +1504,16 @@ You may also use ``password-from-env`` to reset passwords:: layla' Successfully reset password for layla +user:delete +^^^^^^^^^^^ + You can delete users:: sudo -u www-data php occ user:delete fred +user:lastseen +^^^^^^^^^^^^^ + View a specific user's most recent login:: sudo -u www-data php occ user:lastseen layla @@ -1427,8 +1526,9 @@ View a list of all users' most recent login:: bob has never logged in. layla's last login: 2024-03-20 17:18 stephanie's last login: 2024-01-11 13:26 - - + +user:setting +^^^^^^^^^^^^ Read user settings:: @@ -1459,6 +1559,9 @@ Delete a setting:: sudo -u www-data php occ user:setting layla settings email --delete +user:report +^^^^^^^^^^^ + Generate a simple report that counts all users, including users on external user authentication servers such as LDAP:: @@ -1483,6 +1586,11 @@ There might be a discrepancy between the total number of users compared to the n Users that have never logged in before are not counted as active or disabled users. Some user backends also do not allow a count for the number of users. +user:list +^^^^^^^^^ + +You can use the command ``user:list`` to list users. By default it will limit the output to 500 users but you can override that with options ``--limit`` and ``--offset``. Use ``--disabled`` to only list disabled users. + .. _group_commands_label: Group commands @@ -1532,14 +1640,15 @@ removes the existing group "beer":: List configured groups via the ``group:list`` command. The syntax is:: - group:list [-l|--limit] [-o|--offset] [--output="..."] + group:list [-l|--limit [LIMIT]] [-o|--offset [OFFSET]] [-i|--info] [--output [OUTPUT]] -``limit`` allows you to specify the number of groups to retrieve. +``limit`` allows you to specify the number of groups to retrieve (default: ``500``). ``offset`` is an offset for retrieving groups. -``output`` specifies the output format (plain, json or json_pretty). Default is -plain. +``info`` Show additional info (backend). + +``output`` Output format: ``plain``, ``json`` or ``json_pretty`` (default: ``plain``). .. _versions_label: @@ -1748,7 +1857,7 @@ check for that user via the occ command:: .. note:: This is not supported by all providers. -To re-enable two-factor auth again use the following commmand:: +To re-enable two-factor auth again use the following command:: sudo -u www-data php occ twofactorauth:enable @@ -1826,6 +1935,25 @@ Mark a file as scanned or unscanned:: sudo -u www php occ files_antivirus:mark +.. _setupchecks_commands_label: + +Setupchecks +----------- + +Run the setupchecks via occ:: + + sudo -u www php occ setupchecks + +Example output:: + + dav: + ✓ DAV system address book: No outstanding DAV system address book sync. + network: + ✓ WebDAV endpoint: Your web server is properly set up to allow file synchronization over WebDAV. + ✓ Data directory protected + ✓ Internet connectivity + ... + .. _occ_debugging: Debugging diff --git a/admin_manual/office/example-ubuntu.rst b/admin_manual/office/example-ubuntu.rst index efcdf2099..9023a6e67 100644 --- a/admin_manual/office/example-ubuntu.rst +++ b/admin_manual/office/example-ubuntu.rst @@ -1,5 +1,5 @@ ==================================== -Installation example on Ubuntu 20.04 +Installation example on Ubuntu 24.04 ==================================== Import signing keys: @@ -14,7 +14,7 @@ Add repository: .. code-block:: bash - sudo echo "deb https://www.collaboraoffice.com/repos/CollaboraOnline/CODE-ubuntu2004 ./" > /etc/apt/sources.list.d/collaboraonline.sources + sudo echo "Types: deb\nURIs: https://www.collaboraoffice.com/repos/CollaboraOnline/CODE-deb\nSuites: ./\nSigned-By: /usr/share/keyrings/collaboraonline-release-keyring.gpg" > /etc/apt/sources.list.d/collaboraonline.sources Install packages **************** diff --git a/admin_manual/release_notes/index.rst b/admin_manual/release_notes/index.rst index 13eb0e2f6..2921954ea 100644 --- a/admin_manual/release_notes/index.rst +++ b/admin_manual/release_notes/index.rst @@ -14,6 +14,7 @@ These sub pages will cover the most important changes in Nextcloud, as well as s .. toctree:: :maxdepth: 1 + upgrade_to_31.rst upgrade_to_30.rst upgrade_to_28.rst upgrade_to_27.rst diff --git a/admin_manual/release_notes/upgrade_to_28.rst b/admin_manual/release_notes/upgrade_to_28.rst index 5fd9fe19b..bd2cda912 100644 --- a/admin_manual/release_notes/upgrade_to_28.rst +++ b/admin_manual/release_notes/upgrade_to_28.rst @@ -18,6 +18,27 @@ Web server configuration * For Nginx, please refer to our recommended :ref:`Nginx configuration`. * For other setups, make sure to add ``.mjs`` to the list of static file extensions in web server configs and in case define its MIME type in ``/etc/mime.types``. +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. + +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: + +- verifying all entries in ``trusted_domains`` and the value of ``overwrite.cli.url`` are valid, resolvable in DNS, and reachable *from the Nextcloud Server itself* +- verifying that the Server can reach its own URL(s) +- verifying all ``overwrite*`` config values are reasonable + +In diagnosing the above, many admins have found it useful to review not only their `config.php` (for cleanup) but also: + +- their local DNS resolvers and ``/etc/hosts`` files for reasonableness +- their firewall configurations +- their container network configuration if using Docker/etc (especially for outbound connectivity) + +.. tip:: Testing of connectivity and reachability of specific URLs can usually be tested from servers or containers via ``curl`` or ``wget``. + Monitoring ---------- @@ -46,4 +67,4 @@ We expect LibreOffice to be started with the given parameters, so it's unfavorab 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``. \ No newline at end of file +.. 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_notes/upgrade_to_30.rst b/admin_manual/release_notes/upgrade_to_30.rst index faccddbad..f1b7fe0cf 100644 --- a/admin_manual/release_notes/upgrade_to_30.rst +++ b/admin_manual/release_notes/upgrade_to_30.rst @@ -7,4 +7,32 @@ System requirements * PHP 8.1 is now deprecated but still supported. * PHP 8.0 is no longer supported. -* PostgreSQL 9.4 is no longer supported. \ No newline at end of file +* PostgreSQL 9.4 is no longer supported. +* MariaDB 10.3 and 10.5 are no longer supported. + +Web server configuration +------------------------ + +Make sure that your web server is serving files with the ``webp`` extension (WebP images) correctly as static assets. +This is included in the shipped ``.htaccess`` file but if you use another web server or custom configuration you need to check this manually. + +Nextcloud configuration +----------------------- + +Changes to the available options in ``config.php``. + +* The option ``blacklisted_files`` is now deprecated and replaced with ``forbidden_filenames`` +* The option ``forbidden_chars`` is now deprecated and replaced with ``forbidden_filename_characters`` +* The option ``forbidden_filename_basenames`` was added to allow bocking files with specific basenames (the filename without extension (before the first dot)) +* The option ``forbidden_filename_extensions`` was added to allow blocking extensions from being used on filenames + +Previews for PDF files with Imaginary +------------------------------------- + +The preview provider ``OC\Preview\Imaginary`` is no longer generating previews for PDF files. +Add the new preview provider ``OC\Preview\ImaginaryPDF`` to ``enabledPreviewProviders`` to enable preview generation with Imaginary for PDF files. + +Automated clean-up of app password +---------------------------------- + +Nextcloud 30 will :ref:`clean-up unused app passwords`. diff --git a/admin_manual/release_notes/upgrade_to_31.rst b/admin_manual/release_notes/upgrade_to_31.rst new file mode 100644 index 000000000..703426a12 --- /dev/null +++ b/admin_manual/release_notes/upgrade_to_31.rst @@ -0,0 +1,30 @@ +======================= +Upgrade to Nextcloud 31 +======================= + +System requirements +------------------- + +* PHP 8.1 is now deprecated but still supported. +* PHP 8.4 is now supported, but 8.3 is recommended. + +PHP configuration +----------------- + +We have a new setup warning to check if the memory reserved for APCu is high enough. +If you see this warning, you should increase the memory reserved for APCu. +You can do this by increasing the value of the ``apc.shm_size`` directive in your ``php.ini`` file. +It is generally advised to review this value and increase it if necessary depending on your instance size. + +Nextcloud configuration +----------------------- + +Maximum chunk size +^^^^^^^^^^^^^^^^^^ + +We have adjusted the default maximum chunk size for big file uploading. +Previously it was set to 10MiB, it is now increased to 100MiB. + +Also the configuration was moved from an app configuration to the system configuration (``config.php``). +If you set up a custom value previously the value will be automatically migrated to the system configuration during the update. +But if you need to set a new custom value you need now to use the system configuration, see also :ref:`files_configure_max_chunk_size`. diff --git a/admin_manual/release_schedule.rst b/admin_manual/release_schedule.rst index d34adacfd..5dd68ecb4 100644 --- a/admin_manual/release_schedule.rst +++ b/admin_manual/release_schedule.rst @@ -7,7 +7,7 @@ Overview Nextcloud releases multiple major versions *throughout* the year, but maintains support for *each* major version for one full year each through "lighter" maintenance updates (and regularly `backporting `_ applicable security and bug fixes). This permits a high velocity development cadence, while still giving administrators flexibility when planning deployments, upgrades, and maintenance activities. -A detailed `schedule for upcoming major and maintenance releases `_ (as well as end-of-life projections) is regularly updated to faciliate planning deployment, testing, and upgrade planning. +A detailed `schedule for upcoming major and maintenance releases `_ (as well as end-of-life projections) is regularly updated to facilitate planning deployment, testing, and upgrade planning. Whether you want the latest features and optimizations, want to help with testing, or just want to wait until everything is perfectly ready to go, you've got options with regards to which version of Nextcloud Server to initially deploy as well as how frequently to do major upgrades. diff --git a/admin_manual/webhook_listeners/index.rst b/admin_manual/webhook_listeners/index.rst new file mode 100644 index 000000000..b57d34670 --- /dev/null +++ b/admin_manual/webhook_listeners/index.rst @@ -0,0 +1,692 @@ +================= +Webhook Listeners +================= + +.. _webhook_listeners: + +Nextcloud supports listening to internal events via webhooks. + +Installation +------------ + + * Enable the ``webhook_listeners`` app that comes bundled with Nextcloud + +.. code-block:: bash + + occ app:enable webhook_listeners + +Listening to events +------------------- + +You can use the OCS API to add webhooks for specific events: https://docs.nextcloud.com/server/latest/developer_manual/_static/openapi.html#/operations/webhook_listeners-webhooks-index + +.. TODO ON RELEASE: Update version number above on release + +Note: When authenticating with the OCS API to register webhooks the account you authenticate as must have administrator rights or delegated administrator rights. + +Filters +~~~~~~~ + +When registering a webhook listener, you can specify a filter parameter. The value of this parameter must be a JSON object whose properties represent filter conditions. The ``{}`` is an empty query, meaning no specific criteria, so all events are matched. + +If you would like to match events fired by a specific user, you can pass ``{ "user.uid": "bob" }`` to match all events fired in the context of user ``"bob"``. + +If you would like to enforce multiple criteria, you can simply pass multiple properties ``{ "event.tableId": 42, "event.rowId": 3 }`` + +If you would like to match values partially, you can use regular expressions: ``{ "user.uid": "/admin_.*/"}`` will match any user whose user ID starts with ``admin_``. This can be especially useful for filesystem events for filtering by path: ``{ "event.node.path": "/^\\/.*\\/files\\/Special folder\\//"}`` will match files inside the ``Special folder`` of any user (Note especially, that the slashes in the path need to be escaped with two back-slashes, once because we're inside a json string and once because we're inside a regular expression). + +You can also use additional comparison operators (``$eq, $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 } } }`` to accept events after April 1st 2024. + + +Speeding up webhook dispatch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This app uses background jobs to trigger the registered webhooks. Thus, by default, webhooks will be triggered only every 5 minutes, as the default cron interval is 5 minutes. +To trigger webhooks earlier, you can set up a background job worker. 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 a tmux session, preferably 4 or more times for parallel processing of multiple requests by different or the same user. +It would be best to run one command per screen session or per tmux window/pane to keep the logs visible and the worker easily restartable. + +.. code-block:: + + set -e; while true; do sudo -u www-data occ background-job:worker -v -t 60 "OCA\WebhookListeners\BackgroundJobs\WebhookCall"; done + +For Nextcloud-AIO you should use this command on the host server. + +.. code-block:: + + set -e; while true; do sudo docker exec -u www-data -it nextcloud-aio-nextcloud php occ background-job:worker -v -t 60 "OCA\WebhookListeners\BackgroundJobs\WebhookCall"; done + +You may want to adjust the number of workers and the timeout (in seconds) to your needs. +The logs of the worker can be checked by attaching to the screen or tmux session. + +Systemd service +^^^^^^^^^^^^^^^ + +1. Create a systemd service file in ``/etc/systemd/system/nextcloud-webhook-worker@.service`` with the following content: + +.. code-block:: + + [Unit] + Description=Nextcloud Webhook worker %i + After=network.target + + [Service] + ExecStart=/opt/nextcloud-webhook-worker/taskprocessing.sh %i + Restart=always + StartLimitInterval=60 + StartLimitBurst=10 + + [Install] + WantedBy=multi-user.target + +2. Create a shell script in ``/opt/nextcloud-webhook-worker/taskprocessing.sh`` with the following content and make sure to make it executable: + +.. code-block:: + + #!/bin/sh + echo "Starting Nextcloud Webhook Worker $1" + cd /path/to/nextcloud + sudo -u www-data php occ background-job:worker -t 60 'OCA\WebhookListeners\BackgroundJobs\WebhookCall' + +You may want to adjust the timeout to your needs (in seconds). + +3. Enable and start the service 4 or more times: + +.. code-block:: + + for i in {1..4}; do systemctl enable --now nextcloud-webhook-worker@$i.service; done + +The status of the workers can be checked with (replace 1 with the worker number): + +.. code-block:: + + systemctl status nextcloud-webhook-worker@1.service + +The list of workers can be checked with: + +.. code-block:: + + systemctl list-units --type=service | grep nextcloud-webhook-worker + +The complete logs of the workers can be checked with (replace 1 with the worker number): + +.. code-block:: + + sudo journalctl -xeu nextcloud-webhook-worker@1.service -f + +It is recommended to restart this worker at least once a day to make sure code changes are effective and avoid memory leaks, in this example the service restarts every 60 seconds. + +Nextcloud Webhook Events +------------------------ + +This is an exhaustive list of available events. It features the event ID and the available variables for filtering. + + * OCA\\Forms\\Events\\FormSubmittedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "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, + }, + "submission": array{ + "id": int, + "formId": int, + "userId": string, + "timestamp": int, + }, + } + } + + * OCA\\Tables\\Event\\RowAddedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "tableId": int, + "rowId": int, + "previousValues": null|array, + "values": null|array + } + } + + * OCA\\Tables\\Event\\RowDeletedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "tableId": int, + "rowId": int, + "previousValues": null|array, + "values": null|array + } + } + + * OCA\\Tables\\Event\\RowUpdatedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "tableId": int, + "rowId": int, + "previousValues": null|array, + "values": null|array + } + } + + * OCP\\Calendar\\Events\\CalendarObjectCreatedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "calendarId": int, + "calendarData": array{ + "id": int, + "uri": string, + "{http://calendarserver.org/ns/}getctag": string, + "{http://sabredav.org/ns}sync-token": int, + "{urn:ietf:params:xml:ns:caldav}supported-calendar-component-set": 'Sabre\CalDAV\Xml\Property\SupportedCalendarComponentSet', + "{urn:ietf:params:xml:ns:caldav}schedule-calendar-transp": 'Sabre\CalDAV\Xml\Property\ScheduleCalendarTransp' + "{urn:ietf:params:xml:ns:caldav}calendar-timezone": string|null + }, + "shares": list, + "objectData": array{ + "id": int, + "uri": string, + "lastmodified": int, + "etag": string, + "calendarid": int, + "size": int, + "component": string|null, + "classification": int + } + } + } + + * OCP\\Calendar\\Events\\CalendarObjectDeletedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "calendarId": int, + "calendarData": array{ + "id": int, + "uri": string, + "{http://calendarserver.org/ns/}getctag": string, + "{http://sabredav.org/ns}sync-token": int, + "{urn:ietf:params:xml:ns:caldav}supported-calendar-component-set": 'Sabre\CalDAV\Xml\Property\SupportedCalendarComponentSet', + "{urn:ietf:params:xml:ns:caldav}schedule-calendar-transp": 'Sabre\CalDAV\Xml\Property\ScheduleCalendarTransp' + "{urn:ietf:params:xml:ns:caldav}calendar-timezone": string|null + }, + "shares": list, + "objectData": array{ + "id": int, + "uri": string, + "lastmodified": int, + "etag": string, + "calendarid": int, + "size": int, + "component": string|null, + "classification": int + } + } + } + + * OCP\\Calendar\\Events\\CalendarObjectMovedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "sourceCalendarId": int, + "sourceCalendarData": array{ + "id": int, + "uri": string, + "{http://calendarserver.org/ns/}getctag": string, + "{http://sabredav.org/ns}sync-token": int, + "{urn:ietf:params:xml:ns:caldav}supported-calendar-component-set": 'Sabre\CalDAV\Xml\Property\SupportedCalendarComponentSet', + "{urn:ietf:params:xml:ns:caldav}schedule-calendar-transp": 'Sabre\CalDAV\Xml\Property\ScheduleCalendarTransp' + "{urn:ietf:params:xml:ns:caldav}calendar-timezone": string|null + }, + "targetCalendarId": int, + "targetCalendarData": array{ + "id": int, + "uri": string, + "{http://calendarserver.org/ns/}getctag": string, + "{http://sabredav.org/ns}sync-token": int, + "{urn:ietf:params:xml:ns:caldav}supported-calendar-component-set": 'Sabre\CalDAV\Xml\Property\SupportedCalendarComponentSet', + "{urn:ietf:params:xml:ns:caldav}schedule-calendar-transp": 'Sabre\CalDAV\Xml\Property\ScheduleCalendarTransp' + "{urn:ietf:params:xml:ns:caldav}calendar-timezone": string|null + }, + "sourceShares": list, + "targetShares": list, + "objectData": array{ + "id": int, + "uri": string, + "lastmodified": int, + "etag": string, + "calendarid": int, + "size": int, + "component": string|null, + "classification": int + } + } + } + + * OCP\\Calendar\\Events\\CalendarObjectMovedToTrashEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "calendarId": int, + "calendarData": array{ + "id": int, + "uri": string, + "{http://calendarserver.org/ns/}getctag": string, + "{http://sabredav.org/ns}sync-token": int, + "{urn:ietf:params:xml:ns:caldav}supported-calendar-component-set": 'Sabre\CalDAV\Xml\Property\SupportedCalendarComponentSet', + "{urn:ietf:params:xml:ns:caldav}schedule-calendar-transp": 'Sabre\CalDAV\Xml\Property\ScheduleCalendarTransp' + "{urn:ietf:params:xml:ns:caldav}calendar-timezone": string|null + }, + "shares": list, + "objectData": array{ + "id": int, + "uri": string, + "lastmodified": int, + "etag": string, + "calendarid": int, + "size": int, + "component": string|null, + "classification": int + } + } + } + + * OCP\\Calendar\\Events\\CalendarObjectRestoredEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "calendarId": int, + "calendarData": array{ + "id": int, + "uri": string, + "{http://calendarserver.org/ns/}getctag": string, + "{http://sabredav.org/ns}sync-token": int, + "{urn:ietf:params:xml:ns:caldav}supported-calendar-component-set": 'Sabre\CalDAV\Xml\Property\SupportedCalendarComponentSet', + "{urn:ietf:params:xml:ns:caldav}schedule-calendar-transp": 'Sabre\CalDAV\Xml\Property\ScheduleCalendarTransp' + "{urn:ietf:params:xml:ns:caldav}calendar-timezone": string|null + }, + "shares": list, + "objectData": array{ + "id": int, + "uri": string, + "lastmodified": int, + "etag": string, + "calendarid": int, + "size": int, + "component": string|null, + "classification": int + } + } + } + + * OCP\\Calendar\\Events\\CalendarObjectUpdatedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "calendarId": int, + "calendarData": array{ + "id": int, + "uri": string, + "{http://calendarserver.org/ns/}getctag": string, + "{http://sabredav.org/ns}sync-token": int, + "{urn:ietf:params:xml:ns:caldav}supported-calendar-component-set": 'Sabre\CalDAV\Xml\Property\SupportedCalendarComponentSet', + "{urn:ietf:params:xml:ns:caldav}schedule-calendar-transp": 'Sabre\CalDAV\Xml\Property\ScheduleCalendarTransp' + "{urn:ietf:params:xml:ns:caldav}calendar-timezone": string|null + }, + "shares": list, + "objectData": array{ + "id": int, + "uri": string, + "lastmodified": int, + "etag": string, + "calendarid": int, + "size": int, + "component": string|null, + "classification": int + } + } + } + + * OCP\\Files\\Events\\Node\\BeforeNodeCreatedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "node": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\BeforeNodeTouchedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "node": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\BeforeNodeWrittenEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "node": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\BeforeNodeReadEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "node": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\BeforeNodeDeletedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "node": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\NodeCreatedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "node": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\NodeTouchedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "node": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\NodeWrittenEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "node": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\NodeReadEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "node": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\NodeDeletedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "node": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\NodeCopiedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "source": array{"id": string, "path": string} + "target": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\NodeRestoredEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "source": array{"id": string, "path": string} + "target": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\NodeRenamedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "source": array{"id": string, "path": string} + "target": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\BeforeNodeCopiedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "source": array{"id": string, "path": string} + "target": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\BeforeNodeRestoredEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "source": array{"id": string, "path": string} + "target": array{"id": string, "path": string} + } + } + + * OCP\\Files\\Events\\Node\\BeforeNodeRenamedEvent + + .. code-block:: text + + array{ + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + "source": array{"id": string, "path": string} + "target": array{"id": string, "path": string} + } + } + +* OCP\\SystemTag\\MapperEvent + + .. code-block:: text + + array { + "user": array {"uid": string, "displayName": string}, + "time": int, + "event": array{ + "class": string, + 'eventType' => 'OCP\SystemTag\ISystemTagObjectMapper::assignTags' | 'OCP\SystemTag\ISystemTagObjectMapper::unassignTags', + 'objectType' => string (e.g. 'files'), + 'objectId' => string, + 'tagIds' => int[], + } + } \ No newline at end of file diff --git a/admin_manual/windmill_workflows/images/windmill_approval_step_config.png b/admin_manual/windmill_workflows/images/windmill_approval_step_config.png new file mode 100644 index 000000000..92e48ef46 Binary files /dev/null and b/admin_manual/windmill_workflows/images/windmill_approval_step_config.png differ diff --git a/admin_manual/windmill_workflows/images/windmill_initial_workspace_selection.png b/admin_manual/windmill_workflows/images/windmill_initial_workspace_selection.png new file mode 100644 index 000000000..477c0f505 Binary files /dev/null and b/admin_manual/windmill_workflows/images/windmill_initial_workspace_selection.png differ diff --git a/admin_manual/windmill_workflows/images/windmill_later_workspace_selection.png b/admin_manual/windmill_workflows/images/windmill_later_workspace_selection.png new file mode 100644 index 000000000..04370c542 Binary files /dev/null and b/admin_manual/windmill_workflows/images/windmill_later_workspace_selection.png differ diff --git a/admin_manual/windmill_workflows/index.rst b/admin_manual/windmill_workflows/index.rst new file mode 100644 index 000000000..3bdec10ea --- /dev/null +++ b/admin_manual/windmill_workflows/index.rst @@ -0,0 +1,143 @@ +================== +Windmill Workflows +================== + +Nextcloud integrates the Windmill workflow engine (https://www.windmill.dev/) to allow advanced custom workflows interacting with your Nextcloud instance. + +Installation +------------ + + * Install Windmill + + * Either as a standalone install or via the External App "Flow" in Nextcloud (see :ref:`External Apps`) + + * Enable the ``webhook_listeners`` app that comes with Nextcloud + +.. code-block:: bash + + occ app:enable webhook_listeners + +Selecting the right Workspace +----------------------------- + +With Windmill installed as an ExApp, the first time one visits Windmill's web interface, +make sure to select the right workspace on the first run: +Only the pre-existing "nextcloud" workspace is hooked up to nextcloud's internal event system, +all other workspaces will need manual webhook setups for each workflow. +If the wrong workspace is selected on the first run, it is always possible to switch workspace later in the left sidebar. + +.. image:: images/windmill_initial_workspace_selection.png + :alt: Screenshot of the workspace selector screen when opening Windmill for the first time + +If you wish to change to a different workspace at a later time, you can do so via the workspace selector in the left sidebar of Windmill. + +.. image:: images/windmill_later_workspace_selection.png + :alt: Screenshot of the workspace selector when a workspace is already opened + +Setting up the Correct Nextcloud URL +------------------------------------ + +During the initial installation, the ExApp Flow will create a **Nextcloud Authentication Resource** for AppAPI. + +This resource includes a **baseUrl** field, which specifies the URL that Windmill scripts/apps use to reach the Nextcloud instance. In most cases, this URL will be configured correctly. However, certain configurations and network topologies may result in an incorrect URL, which you will need to adjust manually. + +To set the correct URL, navigate to the Windmill interface, go to the **Resources** tab, locate the resource labeled ``u/admin/exapp_resource``, click the three dots on the right, and select the "Edit" button. + +Building a workflow +------------------- + +Each workflow in Windmill is a listener to a Nextcloud Webhook Event. +If you are using the ExApp-packaged Windmill, it will automatically register webhooks for the workflows you build using the following mechanism. +If you are not using the ExApp-packaged windmill install then you will have to register +webhooks for your workflows manually via the webhook_listeners API: +see https://docs.nextcloud.com/server/latest/developer_manual/_static/openapi.html#/operations/webhook_listeners-webhooks-index + +.. TODO ON RELEASE: Update version number above on release + +The magic listener script +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first script (after the "Input" block) in any workflow you build that should listen to a Nextcloud webhook must have "Summary" set to the exact, literal string ``CORE:LISTEN_TO_EVENT``. It must be an empty script with two parameters that you should fill statically: ``events``, which is a list of event IDs to listen to and ``filters`` a filter condition that 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 :ref:`the webhook_listeners documentation`. + +You can copy the following Deno script for this: + +.. code-block:: typescript + + export async function main(events: string[], filters: object) { } + +The webhook data will be made available on the flow "Input" block, **not** the ``CORE:LISTEN_TO_EVENT`` block. Updates to the webhook configuration take effect only when the flow is deployed. Consider disabling any schedule for the flow, since it will be started when a webhook is received. + +Nextcloud Scripts +----------------- + +Nextcloud makes available a variety of scripts to be used in Windmill for interfacing with Nextcloud apps. You can find them +at https://hub.windmill.dev/integrations/nextcloud and https://hub.windmill.dev/integrations/nextcloud/approvals +or in your windmill instance when selecting existing scripts for creating a new workflow. + +To synchronize the scripts with the ones provided by the Windmill hub, +you can run a flow named "Synchronize Hub Resource types with instance" in the Windmill admin workspace. + +You can create your own Nextcloud-related scripts by taking one of the existing ones as example. +In a script, when sending a request to Nextcloud, make sure that the ``EX-APP-ID`` header is set to ``flow``. +Your custom scripts can make requests to any endpoint of the +`Nextcloud OCS API `_ . + +All the scripts we provide have a set of common input parameters: + +* nextcloudResource: This should be set to the path of the Windmill resource that was automatically created and contains what is necessary to authenticate against Nextcloud with the AppAPI authentication method. For example "u/wapp_user/appapi_nextcloud". You can find this path by looking at the resource list in Windmill. +* userId: This is the ID of the user you want the request to be authenticated as. +* useAppApiAuth: This is a boolean to choose between using the AppAPI authentication or basic auth. More details in the next section. + +Authentication +~~~~~~~~~~~~~~ + +All bricks have the option to use "AppAPI Authentication" or normal authentication using a Nextcloud resource in Windmill. +When using normal authentication you will need to provide the correct password or app password of the user +on behalf of whom you want to execute the script. When using "AppAPI Authentication" you can impersonate any Nextcloud user. +This will only work when using the ExApp-packaged version of windmill. + +Passing values between blocks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When specifying script inputs you can either fill the parameters with static values or make references to the workflow input and the previous workflow steps. + +In order to reference the workflow input, use the ``flow_input`` variable. +For example, ``flow_input.event.form.hash`` will reference the hash of a form from a nextcloud Forms event. + +Each step in a workflow is automatically assigned a letter identifier. +In order to reference results from previous steps in your parameters, use the ``results`` variable with the id of the step +to reference as a sub property. For example, use ``results.e.submission.answers`` to use the answers of of a form submission +retrieved via the "Get form submission from Nextcloud Forms" script identified with the letter "e". + +Approval/Suspend steps +~~~~~~~~~~~~~~~~~~~~~~ + +Windmill allows using so-called approval steps, which are essentially asynchronous scripts that wait for the call to an additional webhook URL. +The most prominent use case for this are approval workflows where you get automated input from somewhere which needs to be approved by a human. +Once the human approves or disapproves by triggering the webhook URL the workflow will resume. + +In order to turn a newly added step into an approval step, the workflow edit screen, +select the script and in the bottom right pan, go in the "Advanced" tab, "Suspend" sub tab and check "Suspend/Approval/Prompt". + +.. image:: images/windmill_approval_step_config.png + :alt: Screenshot of the workspace edit screen to turn a normal step into an Approval step + +Using the scripts provided for Nextcloud, you can send approval links to the humans in charge of approving +via Nextcloud Talk or a simple notification in Nextcloud. +Of course, you may also use any of the other scripts for sending messages available in the Windmill hub. + +Windmill has a default approval user interface at a specific URL, but it looks very technical. +We recommend using the `approve_links `_ app +which allows creating a beautiful temporary approval page with a custom message and approve and disapprove buttons. + +FAQ +--- + +Can I create a script? +~~~~~~~~~~~~~~~~~~~~~~ + +If the Windmill Hub does not contain any script to perform the action you have in mind, +you can take an existing Nextcloud script as example and create your own. +Your custom scripts can make requests to any endpoint of the +`Nextcloud OCS API `_ . + diff --git a/conf.py b/conf.py index 7ad81c245..08b572e8b 100644 --- a/conf.py +++ b/conf.py @@ -8,7 +8,9 @@ dir_path = os.path.dirname(os.path.realpath(__file__)) sys.path.insert(0, os.path.abspath(dir_path + '/_ext')) now = datetime.datetime.now() -extensions = ['sphinx_rtd_theme', 'sphinx_rtd_dark_mode', 'sphinx_copybutton'] +os.environ["READTHEDOCS"] = "True" + +extensions = ['sphinx_rtd_theme', 'sphinx_rtd_dark_mode', 'sphinx_copybutton', 'sphinxcontrib.mermaid'] # General information about the project. copyright = str(now.year) + ' Nextcloud GmbH' @@ -24,9 +26,10 @@ release = version # RTD theme options html_theme_options = { - 'logo_only': True, - 'style_external_links': True, - 'display_version': False, + 'logo_only': True, + 'navigation_with_keys': True, + 'style_external_links': True, + 'version_selector': False, } # relative path to subdirectories @@ -36,8 +39,10 @@ html_logo = "../_shared_assets/static/logo-white.png" rst_epilog = '.. |version| replace:: %s' % version # building the versions list -version_start = 27 # THIS IS THE SUPPORTED VERSION NUMBER -version_stable = 29 # INCREASE THIS NUMBER TO THE LATEST STABLE VERSION NUMBER +version_start = 29 # THIS IS THE OLDEST SUPPORTED VERSION NUMBER + + # THIS IS THE VERSION THAT IS MAPPED TO https://docs.nextcloud.com/server/stable/ +version_stable = 31 # CHANGING IT MUST RESULT IN A CHANGE OF THE SYMLINK ON THE LIVE SERVER # Also search for "TODO ON RELEASE" in the rst files @@ -58,7 +63,6 @@ else: html_context = { 'current_version': version, 'READTHEDOCS': True, - 'extra_css_files': ['_static/custom.css'], # force github plugin 'display_github': True, @@ -68,6 +72,12 @@ html_context = { 'theme_vcs_pageview_mode': 'edit/%s/' % github_branch, # to be completed by each individual conf.py } +html_static_path = ['_static'] +# Extra CSS relative to html_static_path +html_css_files = [ + 'custom.css' +] + edit_on_github_project = 'nextcloud/documentation' edit_on_github_branch = 'master' diff --git a/developer_manual/Makefile b/developer_manual/Makefile index 805a74fa1..d679c9e81 100644 --- a/developer_manual/Makefile +++ b/developer_manual/Makefile @@ -115,7 +115,7 @@ latex: latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf + buf_size=10000000 $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." pdf: diff --git a/developer_manual/_templates/versions.html b/developer_manual/_templates/versions.html new file mode 100644 index 000000000..e8a3a5a13 --- /dev/null +++ b/developer_manual/_templates/versions.html @@ -0,0 +1,18 @@ +{% if READTHEDOCS %} +{# Add rst-badge after rst-versions for small badge style. #} +
+ + Read the Docs + v: {{ current_version }} + + +
+
+
{{ _('Versions') }}
+ {% for slug, url in versions %} +
{{ slug }}
+ {% endfor %} +
+
+
+{% endif %} \ No newline at end of file diff --git a/developer_manual/app_development/dependency_management.rst b/developer_manual/app_development/dependency_management.rst index e3df8d800..c243f0a5f 100644 --- a/developer_manual/app_development/dependency_management.rst +++ b/developer_manual/app_development/dependency_management.rst @@ -4,7 +4,7 @@ Dependency management ===================== -It's possible to build a Nextcloud app with existing software packages. +You can leverage existing software packages to build a Nextcloud app. .. _app-composer: @@ -34,6 +34,84 @@ Dependency hell Be careful with which packages you add to an app. PHP can not load two version of the same class twice, hence there can be conflicts between Nextcloud Server and an app or between two or more apps if they require the same package. So try to keep the number of production dependencies to a minimum and see :ref:`app-composer-bin-tools`. +Alternatively you can use [composer-bin-plugin](https://github.com/bamarni/composer-bin-plugin) to avoid dependency conflicts between apps. + +1. Install composer-bin-plugin according to their docs. + + .. code-block:: shell + + composer require --dev bamarni/composer-bin-plugin + +2. Install the tools you need in the vendor-bin directory. + + .. code-block:: shell + + 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'; + Conflict example **************** diff --git a/developer_manual/app_development/info.rst b/developer_manual/app_development/info.rst index f0e94dfc5..ec131e2d6 100644 --- a/developer_manual/app_development/info.rst +++ b/developer_manual/app_development/info.rst @@ -23,12 +23,12 @@ A minimum valid **info.xml** would look like this: An RSS/Atom feed reader An RSS/Atom feed reader 8.8.2 - agpl + AGPL-3.0-or-later Bernhard Posselt multimedia https://github.com/nextcloud/news/issues - + @@ -47,7 +47,7 @@ A full blown example would look like this (needs to be utf-8 encoded): # Description\nAn RSS/Atom feed reader 8.8.2 - agpl + AGPL-3.0-or-later Bernhard Posselt Alessandro Cosentino Jan-Christoph Borchardt @@ -75,7 +75,7 @@ A full blown example would look like this (needs to be utf-8 encoded): curl SimpleXML iconv - + OCA\DAV\CardDAV\Sync\SyncJob @@ -175,7 +175,25 @@ version licence * required - * must contain **agpl**, **mpl*** and/or **apache** as the only valid values. These refer to the AGPLv3, MPL 2.0 and Apache License 2.0 + * can occur multiple times with different licenses + * must contain one of the following licenses (for apps targeting v31 or higher, see the `SPDX License List `_ for details): + + * **AGPL-3.0-only** + * **AGPL-3.0-or-later** + * **Apache-2.0** + * **GPL-3.0-only** + * **GPL-3.0-or-later** + * **MIT** + * **MPL-2.0** + + * (deprecated, for apps targeting v30 or lower) the following shorthand aliases are also used: + + * **agpl** (AGPL-3.0) + * **apache** (Apache-2.0) + * **gpl3** (GPL-3.0) + * **mit** (MIT) + * **mpl** (MPL-2.0) + author * required * can occur multiple times with different authors @@ -225,7 +243,7 @@ discussion * optional * must contain a URL to the project's discussion page/forum * will be rendered on the app detail page as the "ask question or discuss" button - * if absent, it will default to our forum at https://help.nextcloud.com/ and create a new category in the apps category + * if absent, it will default to our forum at https://help.nextcloud.com/ bugs * required * must contain a URL to the project's bug tracker diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/index.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/index.rst index cace76a4b..4aae36348 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/index.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/index.rst @@ -11,6 +11,8 @@ These sub pages will cover the most important changes in Nextcloud, as well as s .. toctree:: :maxdepth: 1 + upgrade_to_32.rst + upgrade_to_31.rst upgrade_to_30.rst upgrade_to_29.rst upgrade_to_28.rst 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 53f67c2f0..f44a964e4 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 @@ -51,7 +51,7 @@ The code that initializes an app or anything that should run for every request a PSR-3 integration ^^^^^^^^^^^^^^^^^ -Nextcloud 20 is the first major release of Nextcloud that brings full compatibility with :ref:`psr3`. From this point on it is highly recommended to use this interface mainly as the old ``\OCP\ILogger`` got deprecated with the last remaining changes. The majority of methods are identical between the Nextcloud-specific interface and the PSR one. Pay attention to usages of ``\OCP\ILogger::logException`` as that method does not exist on the PSR logger. However, you can specifcy an ``exception`` key in the ``$context`` argument of any ``\Psr\Log\LoggerInterface`` method and Nextcloud will format it like it did with the old ``logException``. +Nextcloud 20 is the first major release of Nextcloud that brings full compatibility with :ref:`psr3`. From this point on it is highly recommended to use this interface mainly as the old ``\OCP\ILogger`` got deprecated with the last remaining changes. The majority of methods are identical between the Nextcloud-specific interface and the PSR one. Pay attention to usages of ``\OCP\ILogger::logException`` as that method does not exist on the PSR logger. However, you can specify an ``exception`` key in the ``$context`` argument of any ``\Psr\Log\LoggerInterface`` method and Nextcloud will format it like it did with the old ``logException``. .. _upgrade-psr11: diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_21.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_21.rst index 93ab9f1e2..21b40ea2f 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_21.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_21.rst @@ -80,5 +80,5 @@ Nextcloud 21 is the last major release that supports an app's ``appinfo/database Replaced well-known handler API ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -There was an old, unused and inofficial mechanism to hook into well-known discovery via config settings. This includes ``host-meta``, ``host-meta.json``, ``nodeinfo`` and ``webfinger``. A :ref:`new public API replaces this mechanism` in Nextcloud 21. +There was an old, unused and unofficial mechanism to hook into well-known discovery via config settings. This includes ``host-meta``, ``host-meta.json``, ``nodeinfo`` and ``webfinger``. A :ref:`new public API replaces this mechanism` in Nextcloud 21. diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_27.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_27.rst index 426071559..16e0e089a 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_27.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_27.rst @@ -25,12 +25,12 @@ Front-end changes General ^^^^^^^ -* With Nextcloud 27 you can also provide module javascript files with the ``.mjs`` file extension. For backwards compatibilty you can provide files with the same name but the ``.js`` file extension which will be loaded for Nextcloud versions before 27. +* With Nextcloud 27 you can also provide module javascript files with the ``.mjs`` file extension. For backwards compatibility you can provide files with the same name but the ``.js`` file extension which will be loaded for Nextcloud versions before 27. Added APIs ^^^^^^^^^^ -* A new Files Router API allows you to control the files router service and update views, querys or param without page reload. See :ref:`FilesAPI` +* A new Files Router API allows you to control the files router service and update views, queries or param without page reload. See :ref:`FilesAPI` Back-end changes ---------------- diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_30.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_30.rst index c00d5da50..1ccf78eb6 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_30.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_30.rst @@ -5,9 +5,55 @@ Upgrade to Nextcloud 30 General ------- +A new dependency type ``backend`` was added to info.xml. +If your app requires or makes use of the CalDAV backend in server, please add the backend +``caldav`` to the dependencies of your app. + +.. code-block:: xml + + + caldav + + +If no app is requiring the CalDAV backend, the CalDAV section in the admin settings will be hidden. +Currently, there is no other effect but that might change in the future. + +Capabilities +------------ + +``files`` +^^^^^^^^^ + +- ``blacklist_files_regex`` is deprecated now use ``forbidden_filenames`` instead +- ``forbidden_filename_characters`` was added to provide a list of characters not allowed within filenames +- ``forbidden_filename_extensions`` was added to provide a list of extensions (suffixes) not allowed for filenames + Front-end changes ----------------- +The overall design was changed to be less round and more compact, +as a part of this some CSS variables were added and other deprecated with Nextcloud 30, see :ref:`cssvars`. + +Clickable area +^^^^^^^^^^^^^^ +The size of the CSS variable ``--clickable-area`` variable has shrunk from ``44px`` to ``34px``. +This will result in several regressions and paper-cuts in your app that will need to be manually fixed. +It's recommended to: + +1) Link the ``@nextcloud/vue`` current master to your app (pull often cause fixes are getting in there too); +2) Do a codebase-wide search of `44px` and replace with the variable `--default-clickable-area` if appropriate; +3) Check for regressions and visual bugs; +4) Report the regression of your app in this issue (you can create a heading with the name of your own app); +5) Also report ``@nextlcoud/vue`` library regressions if they're not reported already in their list; +6) Fix regression in your app (only the ones that are unrelated to the ``@nextcloud/vue`` components); + +Line height +^^^^^^^^^^^ +The ``--default-line-height`` variable has changed from ``24px``` to ``1.5`` for the ``--default-font-size`` this +means that the actual value in pixel will go from 24 to 22.5. Although this is a slight change, it's recommended +to check for visual regressions in your app. + + Font sizes ^^^^^^^^^^ @@ -15,33 +61,65 @@ Nextcloud now provides meaningful default styles for heading elements. This can cause visual regressions if your code does not explicitly set font size and weight. If you need to use heading elements outside of text content, you might need to adjust their styles. -Added APIs -^^^^^^^^^^ +Border radius +^^^^^^^^^^^^^ -Changed APIs -^^^^^^^^^^^^ +The border radius CSS variables have been refactored: -Removed APIs -^^^^^^^^^^^^ +- Added -Removed globals -^^^^^^^^^^^^^^^ + - ``--border-radius-small`` was added for smaller elements like chips. + - ``--border-radius-container`` was added for smaller containers like action menus. + - ``--border-radius-container-large`` was added for larger containers like body or modals. + - ``--border-radius-element`` was added for interactive elements such as buttons, input, navigation and list items. + +- Deprecated + + - ``--border-radius`` is deprecated now in favor of ``--border-radius-small``. + - ``--border-radius-large`` is deprecated now in favor of ``--border-radius-element``. + - ``--border-radius-pill`` is deprecated now in favor of ``--border-radius-element``. + - ``--border-radius-rounded`` is deprecated now in favor of ``--border-radius-container``. + +CSP Nonce +^^^^^^^^^ + +A bug was fixed that prevented Nextcloud form using the ``CSP_NONCE`` environment variable, +this now means that the CSP nonce for JavaScript assets is no longer (guaranteed to be) based on the CSRF token. +Instead administrators can choose to use a differently generated token. +When using JavaScript modules this does not make a difference, as they are imported and the nonce has only to be set on the root module (done by Nextcloud), +but if you are using Webpack or otherwise dynamically load scripts, you now need adjust the CSP nonce handling. + +Get the CSP nonce: + +- Either use ``getCSPNonce`` from the ``@nextcloud/auth`` :ref:`package`, which is also backwards compatible. +- Or directly read the nonce from the ```` tag. + +When using Webpack: + +.. code-block:: diff + + - import { getRequestToken } from '@nextcloud/auth' + - __webpack_nonce__ = btoa(getRequestToken()) + + import { getCSPNonce } from '@nextcloud/auth' + + __webpack_nonce__ = getCSPNonce() Deprecated APIs ^^^^^^^^^^^^^^^ -* ``OC.dialogs.fileexists`` was already deprecated in Nextcloud 29, but is now also marked as such. +- ``OC.config.blacklist_files_regex`` is deprecated now, use the ``files`` capabilities instead +- ``OC.config.forbidden_filename_characters`` is deprecated now, use the ``files`` capabilities instead +- ``OC.dialogs.fileexists`` was already deprecated in Nextcloud 29, but is now also marked as such. Use ``openConflictPicker`` from `@nextcloud/upload `_ instead. -* Most ``OC.dialogs`` API is now deprecated and will be removed in the future. For generic dialogs use the ``DialogBuilder`` from the :ref:`js-library_nextcloud-dialogs`. +- Most ``OC.dialogs`` API is now deprecated and will be removed in the future. For generic dialogs use the ``DialogBuilder`` from the :ref:`js-library_nextcloud-dialogs`. A list of the now deprecated methods: - * ``OC.dialogs.alert`` - * ``OC.dialogs.info`` - * ``OC.dialogs.confirm`` - * ``OC.dialogs.confirmDestructive`` - * ``OC.dialogs.confirmHtml`` - * ``OC.dialogs.prompt`` - * ``OC.dialogs.message`` + - ``OC.dialogs.alert`` + - ``OC.dialogs.info`` + - ``OC.dialogs.confirm`` + - ``OC.dialogs.confirmDestructive`` + - ``OC.dialogs.confirmHtml`` + - ``OC.dialogs.prompt`` + - ``OC.dialogs.message`` Back-end changes ---------------- @@ -81,11 +159,33 @@ Added APIs - ``OCP\Activity\Exceptions\InvalidValueException`` is thrown by ``OCP\Activity\IEvent::set*()`` when the value did not match the required criteria - ``OCP\Activity\Exceptions\SettingNotFoundException`` is thrown by ``OCP\Activity\IManager::getSettingById()`` when no setting with the given identifier registered - ``OCP\Activity\Exceptions\UnknownActivityException`` should be thrown by ``OCP\Activity\IProvider::parse()`` when they didn't handle the event +- ``OCP\AppFramework\Db\QbMapper::yieldEntities()`` was added to allow iterating over entities by returning a ``Generator`` without loading all of them into memory. +- ``OCP\Authentication\Token\IToken::SCOPE_FILESYSTEM`` and ``OCP\Authentication\Token\IToken::SCOPE_SKIP_PASSWORD_VALIDATION`` constants were introduced as constants for token scopes. Previously, the value of ``SCOPE_FILESYSTEM`` was hardcoded. - ``OCP\Notification\IncompleteNotificationException`` is thrown by ``OCP\Notification\IManager::notify()`` when not all required fields have been set on the ``OCP\Notification\INotification`` object - ``OCP\Notification\IncompleteParsedNotificationException`` is thrown by ``OCP\Notification\IManager::prepare()`` when no ``OCP\Notification\INotifier`` handled the ``OCP\Notification\INotification`` object - ``OCP\Notification\InvalidValueException`` is thrown by ``OCP\Notification\IAction::set*()`` and ``OCP\Notification\INotification::set*()`` when the value did not match the required criteria - ``OCP\Notification\UnknownNotificationException`` should be thrown by ``OCP\Notification\INotifier::prepare()`` when they didn't handle the notification -- ``OCA\Files_Trashbin\Trash\ITrashItem::getDeletedBy`` should return the user who deleted the item or null if unknown +- ``OCA\Files_Trashbin\Trash\ITrashItem::getDeletedBy()`` should return the user who deleted the item or null if unknown +- ``OCP\IUser::getPasswordHash()`` should return the password hash of the user +- ``OCP\IUser::setPasswordHash()`` should set the password hash of the user +- ``OCP\AppFramework\Http\Attribute\OpenAPI::SCOPE_EX_APP`` attribute for scoping APIs only to be used by ExApps. +- ``OCP\AppFramework\Http\Attribute\ExAppRequired`` attribute for restricting controller methods to be only accessible by ExApps. +- ``OCP\Collaboration\Reference\IPublicReferenceProvider`` added for reference providers that support reference lookups from public shares. +- ``OCP\Files\IFilenameValidator`` was added to allow storage independent filename validation. +- ``OCP\Files\Storage\IStorage::setOwner()`` was added to allow setting the owner of a storage so it can be handled independently from the current session user. This is especially useful for storages that have a shared ownership like groupfolders, external storages where the storage owner needs to be set to the user that is initializing the storage through their personal mountpoint. +- ``ShareAPIController::sendShareEmail()`` was added and is accessible via ocs ``/api/v1/shares/{shareId}/send-email``. See :ref:`send-email` documentation. +- ``OCP\Calendar\Room\IManager::update()`` was added to update all rooms from all backends right now. +- ``OCP\Calendar\Resource\IManager::update()`` was added to update all resources from all backends right now. +- ``OCP\App\IAppManager::BACKEND_CALDAV`` was added to represent the caldav backend dependency for ``isBackendRequired()``. +- ``OCP\App\IAppManager::isBackendRequired()`` was added to check if at least one app requires a specific backend (currently only ``caldav``). +- ``OCP\Accounts\IAccountManager::PROPERTY_BIRTHDATE`` was added to allow users to configure their date of birth in their profiles. +- ``OCP\TaskProcessing``` was added to unify task processing of AI tasks and other types of tasks. See :ref:`Task Processing` +- ``OCP\AppFramework\Bootstrap\IRegistrationContext::registerTaskProcessingProvider()`` was added to allow registering task processing providers +- ``OCP\AppFramework\Bootstrap\IRegistrationContext::registerTaskProcessingTaskType()`` was added to allow registering task processing task types +- ``OCP\Files\IRootFolder::getAppDataDirectoryName()`` was added to allow getting the name of the app data directory +- ``OCP\Console\ReservedOptions`` was added and contains constants for options reserved for occ core features. ``--debug-log`` and ``--debug-log-level`` are now reserved by occ as they allow to show debug information to the output on any occ command. +- ``OCP\Security\IHasher::validate()`` should return true if the passed string is a valid hash generated by ``OCP\Security\IHasher::hash()`` +- ``OCP\AppFramework\Http\JSONResponse()`` constructor now supports passing additional ``json_encode`` flags, see https://www.php.net/manual/en/function.json-encode.php for details Changed APIs ^^^^^^^^^^^^ @@ -95,6 +195,10 @@ Changed APIs - Calling ``OCP\Activity\IEvent::setLink()`` with a relative URL is deprecated and will throw ``OCP\Activity\Exceptions\InvalidValueException`` in a future version. - ``OCP\Activity\IManager::publish()`` throws ``OCP\Activity\Exceptions\IncompleteActivityException`` instead of ``\InvalidArgumentException`` when a required field is not set before publishing. - ``OCP\Activity\IProvider::parse()`` should no longer throw ``\InvalidArgumentException``. ``OCP\Activity\Exceptions\UnknownNotificationException`` should be thrown when the provider does not want to handle the event. ``\InvalidArgumentException`` are logged as debug for now and will be logged as error in the future to help developers find issues from code that unintentionally threw ``\InvalidArgumentException`` +- ``OCP\Dashboard\IIconWidget::getIconUrl()`` clarification: The URL must be an absolute URL. The served icon should be dark. The icon will be inverted automatically in mobile clients and when using dark mode. +- ``OCP\Dashboard\IWidget::getId()`` clarification: Implementations should only return ``a-z``, ``0-9``, ``-`` and ``_`` based strings starting with a letter, as the identifier is used in CSS classes and that is otherwise invalid +- ``OCP\Dashboard\IWidget::getIconClass()`` clarification: The returned CSS class should render a dark icon. The icon will be inverted automatically in mobile clients and when using dark mode. Therefore, it is NOT recommended to use a css class that sets the background with ``var(--icon-…)``` as those will adapt to dark/bright mode in the web and still be inverted resulting in a dark icon on dark background. +- ``OCP\Files\Lock\ILockManager::registerLazyLockProvider()`` was added to replace ``registerLockProvider`` and allows to register a lock provider that is only loaded when needed. - ``OCP\Notification\IAction::set*()`` (all setters) throw ``OCP\Notification\InvalidValueException`` instead of ``\InvalidArgumentException`` when the value does not match the required criteria. - Calling ``OCP\Notification\IAction::setLink()`` with a relative URL is deprecated and will throw ``OCP\Notification\InvalidValueException`` in a future version. - ``OCP\Notification\IApp::notify()`` throws ``OCP\Notification\IncompleteNotificationException`` instead of ``\InvalidArgumentException`` when a required field is not set before notifying. @@ -103,9 +207,82 @@ Changed APIs - Calling ``OCP\Notification\INotification::setLink()`` with a relative URL is deprecated and will throw ``OCP\Notification\InvalidValueException`` in a future version. - Calling ``OCP\Notification\INotification::setIcon()`` with a relative URL is deprecated and will throw ``OCP\Notification\InvalidValueException`` in a future version. - ``OCP\Notification\INotifier::prepare()`` should no longer throw ``\InvalidArgumentException``. ``OCP\Notification\UnknownNotificationException`` should be thrown when the notifier does not want to handle the notification. ``\InvalidArgumentException`` are logged as debug for now and will be logged as error in the future to help developers find issues from code that unintentionally threw ``\InvalidArgumentException`` +- ``OCP\IGroupManager::isAdmin()`` should be used instead of checking is current user is part of admin group manually. +- ``IAttributes`` ``enabled`` key have bee renamed to ``value`` and supports more than boolean. +- ``OCP\DB\Exception`` uses the reason code ``REASON_LOCK_WAIT_TIMEOUT`` now, instead of ``REASON_SERVER`` for a LockWaitTimeoutException. +- ``OCP\Share\IShare::setNoExpirationDate()`` now sets an overwrite flag for falsy expiry date values, this flag is used to determine whether the system should overwrite falsy expiry date values before creating a share. +- ``OCP\Share\IShare::getNoExpirationDate()`` retrieves the value of the ``noExpirationDate`` flag. + +Deprecated APIs +^^^^^^^^^^^^^^^ + +- Using the ``@PasswordConfirmationRequired`` annotation is deprecated and the ``#[OCP\AppFramework\Http\Attribute\PasswordConfirmationRequired]`` attribute should be used instead. +- Using the ``@CORS`` annotation is deprecated and the ``#[OCP\AppFramework\Http\Attribute\CORS]`` attribute should be used instead. +- Using the ``@PublicPage`` annotation is deprecated and the ``#[OCP\AppFramework\Http\Attribute\PublicPage]`` attribute should be used instead. +- Using the ``@ExAppRequired`` annotation is deprecated and the ``#[OCP\AppFramework\Http\Attribute\ExAppRequired]`` attribute should be used instead. +- Using the ``@AuthorizedAdminSetting`` annotation is deprecated and the ``#[OCP\AppFramework\Http\Attribute\AuthorizedAdminSetting]`` attribute should be used instead. +- Using the ``@SubAdminRequired`` annotation is deprecated and the ``#[OCP\AppFramework\Http\Attribute\SubAdminRequired]`` attribute should be used instead. +- Using the ``@NoAdminRequired`` annotation is deprecated and the ``#[OCP\AppFramework\Http\Attribute\NoAdminRequired]`` attribute should be used instead. +- Using the ``@StrictCookieRequired`` annotation is deprecated and the ``#[OCP\AppFramework\Http\Attribute\StrictCookiesRequired]`` attribute should be used instead. +- Using the ``@NoCSRFRequired`` annotation is deprecated and the ``#[OCP\AppFramework\Http\Attribute\NoCSRFRequired]`` attribute should be used instead. +- Using the ``OCP\Group\Backend\ICreateGroupBackend`` interface is now deprecated and the ``OCP\Group\Backend\ICreateNamedGroupBackend`` interface should be used instead. +- Calling ``OCP\DB\QueryBuilder\IExpressionBuilder::andX()`` without arguments is deprecated and will throw an exception in a future version as the underlying library is removing the functionality. +- Calling ``OCP\DB\QueryBuilder\IExpressionBuilder::orX()`` without arguments is deprecated and will throw an exception in a future version as the underlying library is removing the functionality. +- Calling ``OCP\DB\QueryBuilder\IQueryBuilder::delete()`` with ``$alias`` is deprecated and will throw an exception in a future version as the underlying library is removing the functionality. +- Calling ``OCP\DB\QueryBuilder\IQueryBuilder::getQueryPart()`` is deprecated and will throw an exception in a future version as the underlying library is removing the functionality. +- Calling ``OCP\DB\QueryBuilder\IQueryBuilder::getQueryParts()`` is deprecated and will throw an exception in a future version as the underlying library is removing the functionality. +- Calling ``OCP\DB\QueryBuilder\IQueryBuilder::getState()`` is deprecated and will throw an exception in a future version as the underlying library is removing the functionality. +- Calling ``OCP\DB\QueryBuilder\IQueryBuilder::resetQueryPart()`` is deprecated and will throw an exception in a future version as the underlying library is removing the functionality. Create a new query builder object instead. +- Calling ``OCP\DB\QueryBuilder\IQueryBuilder::resetQueryParts()`` is deprecated and will throw an exception in a future version as the underlying library is removing the functionality. Create a new query builder object instead. +- Calling ``OCP\DB\QueryBuilder\IQueryBuilder::update()`` with ``$alias`` is deprecated and will throw an exception in a future version as the underlying library is removing the functionality. +- Calling ``OCP\IDBConnection::getDatabasePlatform()`` is deprecated and will throw an exception in a future version as the underlying library is renaming and removing platforms which breaks the backwards-compatibility. Use ``getDatabaseProvider()`` instead. +- Calling ``OCP\Files\Lock\ILockManager::registerLockProvider()`` is deprecated and will be removed in the future. Use ``registerLazyLockProvider()`` instead. +- Using ``OCP\Translation`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). +- Using ``OCP\Translation\CouldNotTranslateException`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). +- Using ``OCP\Translation\IDetectLanguageProvider`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). +- Using ``OCP\Translation\ITranslationManager`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). +- Using ``OCP\Translation\ITranslationProvider`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). +- Using ``OCP\Translation\ITranslationProviderWithId`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). +- Using ``OCP\Translation\ITranslationProviderWithUserId`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). +- Using ``OCP\Translation\LanguageTuple`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). +- Using ``OCP\SpeechToText`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``SpeechToText`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\SpeechToText\Events\AbstractTranscriptionEvent`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``SpeechToText`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\SpeechToText\Events\TranscriptionFailedEvent`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``SpeechToText`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\SpeechToText\Events\TranscriptionSuccessfulEvent`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``SpeechToText`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\SpeechToText\ISpeechToTextManager`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``SpeechToText`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\SpeechToText\ISpeechToTextProvider`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``SpeechToText`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\SpeechToText\ISpeechToTextProviderWithId`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``SpeechToText`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\SpeechToText\ISpeechToTextProviderWithUserId`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``SpeechToText`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage\Task`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage\IProviderWithUserId`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage\IProvider`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage\IManager`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage\Exception\TextToImageException`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage\Exception\TaskNotFoundException`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage\Exception\TaskFailureException`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage\Events\TaskSuccessfulEvent`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage\Events\TaskFailedEvent`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextToImage\Events\AbstractTextToImageEvent`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextToImage`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\Events\AbstractTextProcessingEvent`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\Events\TaskFailedEvent`` is deprecated and will be removed in the future.Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\Events\TaskSuccessfulEvent`` is deprecated and will be removed in the future.Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\Exception\TaskFailureException`` is deprecated and will be removed in the future.Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\FreePromptTaskType`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\HeadlineTaskType`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\IManager`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\IProvider`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\IProviderWithExpectedRuntime`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\IProviderWithId`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\IProviderWithUserId`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\ITaskType`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\SummaryTaskType`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\Task`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. +- Using ``OCP\TextProcessing\TopicsTaskType`` is deprecated and will be removed in the future. Use ``OCP\TaskProcessing`` instead (see :ref:`Task Processing`). Existing ``TextProcessing`` providers will continue to work with the TaskProcessing API until then. Removed APIs ^^^^^^^^^^^^ -Removed events -^^^^^^^^^^^^^^ +- ``OCP\Util::isValidFileName`` was deprecated in 8.1.0 and is now removed, use either ``OCP\Files\Storage\IStorage::verifyPath`` or the new ``OCP\Files\IFilenameValidator``. +- ``OCP\Util::getForbiddenFileNameChars`` was removed, use either ``OCP\Files\Storage\IStorage::verifyPath`` or the new ``OCP\Files\IFilenameValidator`` for filename validation. 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 new file mode 100644 index 000000000..95bc950a2 --- /dev/null +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst @@ -0,0 +1,180 @@ +======================= +Upgrade to Nextcloud 31 +======================= + +General +------- + +- TBD + +Front-end changes +----------------- + +User-, guest-, and public-template layout +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The main layout for all apps (the user, guest and public template) has been changed, +the main content is no longer rendered within a ``
`` element with the class ``content`` but in a ``div`` element with the class ``content``. +The reason for this is to allow writing Vue 3 based apps which would incorrectly render two stacked ``main``-elements otherwise. + +For Vue 2 apps this **does not change anything**. +But if you just use vanilla templates or other frameworks this changes the page layout and might require adjustments. +We recommend you to wrap your content in a custom ``main``-element if you use non or not Vue as the framework. + +Logical position CSS rules +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +With Nextcloud 31 all server provided styles are migrated to use `logical positioning `_ +instead of physical, this allows the front-end layout to adjust to different language directions (right-to-left). +App developers are strongly encouraged to migrate their apps to logical positioning too. + +Examples for logical vs physical positioning: + +- ``margin-inline-start: 4px;`` instead of ``margin-left: 4px;`` +- ``inset-inline-end: 8px;`` instead of ``right: 8px`` + +Files and Files sharing +^^^^^^^^^^^^^^^^^^^^^^^ + +With Nextcloud 28 the Files app front-end was migrated to Vue and the private API ( ``OCA.Files`` ) was removed, +but for public shares the legacy frontend-end was still used. With Nextcloud 31 public shares also use the new Vue front-end. +This means accessing the legacy private API in ``OCA.Files`` is no longer possible, all existing apps should migrate to the :ref:`public API`. + +To make migration easier utility functions are provided in the ``@nextcloud/sharing`` :ref:`package` +to check whether the current Files app instance is a public share or not, and if so to fetch the share token. + +.. code-block:: JavaScript + + import { isPublicShare, getSharingToken } from '@nextcloud/sharing/public' + + if (isPublicShare()) { + console.info('This is a public share with the sharing token: ', getSharingToken()) + } + + +Added APIs +^^^^^^^^^^ + +- If an app supports file conversion, it may now register an ``\OCP\Files\Conversion\ConversionProvider`` which will + be called automatically based on the supported MIME types. An app may register as many of these as needed. + +Changed APIs +^^^^^^^^^^^^ + +- TBD + +Deprecated APIs +^^^^^^^^^^^^^^^ + +- TBD + +Removed APIs +^^^^^^^^^^^^ + +- ``OCA.FilesSharingDrop`` removed as part of the Vue migration. Use the Files app API provided by the :ref:`package` . +- ``$.Event('OCA.Notification.Action')`` jQuery event removed from Notifications app as part of the Vue migration. Use ``@nextcloud/event-bus`` :ref:`package` instead. + +.. code-block:: JavaScript + + import { subscribe, unsubscribe } from '@nextcloud/event-bus' + + subscribe('notifications:action:execute', (event) => { + console.info('Notification action has been executed:', event.notification, event.action) + }) + +Back-end changes +---------------- + +Support for PHP 8.4 added +^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this release support for PHP 8.4 was added. Follow the steps below to make your app compatible. + +1. If ``appinfo/info.xml`` has a dependency specification for PHP, increase the ``max-version`` to 8.4. +However, it is recommended to always support all PHP versions that are compatible with supported Nextcloud version. +In that case the ``php``-dependencies entries can be omitted. + +.. code-block:: xml + + + + + + + +2. If your app has a ``composer.json`` and the file contains the PHP restrictions from ``info.xml``, adjust it as well. + +.. code-block:: json + + { + "require": { + "php": ">=8.1 <=8.4" + } + } + +3. If you have :ref:`continuous integration ` set up, extend your test matrix with PHP 8.4 tests and linters. +This happens automatically when you reuse our `GitHub Workflow templates `__, +but you can also use the underlying `icewind1991/nextcloud-version-matrix Action `__ directly. + +Information about code changes can be found on `php.net `__ and `stitcher.io `__. + +Added APIs +^^^^^^^^^^ + +- It is now possible to download folders as zip or tar archives using the WebDAV backend using :code:`GET` requests. + See the relevant :ref:`endpoint documentation`. +- ``OCP\SetupCheck\CheckServerResponseTrait`` was added to ease implementing custom :ref:`setup checks` + which need to check HTTP calls to the the server itself. +- Any implementation of ``OCP\Files\Mount\IMountPoint`` can additionally implement ``OCP\Files\Mount\IShareOwnerlessMount`` which allows everyone with share permission to edit and delete any share on the files and directories below the mountpoint. +- ``OCP\Navigation\Events\LoadAdditionalEntriesEvent`` is dispatched when the navigation manager needs to know about its entries, apart of standard app entries that are loaded automatically. This is only relevant for apps that provide extraneous entries. +- ``OCP\User\Backend\ILimitAwareCountUsersBackend`` was added as a replacement for ``ICountUsersBackend``. It allows to specify a limit to the user count to avoid counting all users when the caller do not need it. You can safely ignore the limit if it does not make sense for your usecase. + +Changed APIs +^^^^^^^^^^^^ + +- Clarify ``OCP\Files\Storage\IStorage::getOwner()`` returns ``string|false``. +- Added method parameter and return types to all inheritors of ``OCP\Files\Storage\IStorage``. To migrate in a backwards compatible manner: + + #. Add all return types to your implementation now. + #. Add all parameter types to your implementation once Nextcloud 31 is the lowest supported version. + +- The Nextcloud implementation of the ``log`` method of ``Psr\Log\LoggerInterface`` now supports ``Psr\Log\LogLevel`` as log level parameter. +- The ``OCP\DB\QueryBuilder\IQueryBuilder`` now supports more date / time related parameter types: + + - ``PARAM_DATE_MUTABLE`` and ``PARAM_DATE_IMMUTABLE`` for passing a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the date part. + - ``PARAM_TIME_MUTABLE`` and ``PARAM_TIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the time part. + - ``PARAM_DATETIME_MUTABLE`` and ``PARAM_DATETIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance without handling of the timezone. + - ``PARAM_DATETIME_TZ_MUTABLE`` and ``PARAM_DATETIME_TZ_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance with handling of the timezone. + +- The ``OCP\\DB\\Types`` now support more date and time related types for usage with the ``Entity``: + + - ``DATE_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the date part set. + - ``TIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the time part set. + - ``DATETIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set but without timezone information. + - ``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. + +Deprecated APIs +^^^^^^^^^^^^^^^ + +- The ``/s/{token}/download`` endpoint for downloading public shares is deprecated. + Instead use the Nextcloud provided :ref:`WebDAV endpoint`. +- ``OCP\DB\QueryBuilder\IQueryBuilder::PARAM_DATE`` is deprecated in favor of ``PARAM_DATETIME_MUTABLE`` + to make clear that this type also includes the time part of a date time instance. +- ``OCP\User\Backend\ICountUsersBackend`` was deprecated. Please implement and use ``OCP\User\Backend\ILimitAwareCountUsersBackend`` instead. + +Removed APIs +^^^^^^^^^^^^ + +- Legacy, non functional, ``OC_App::getForms`` was removed. +- The private and legacy ``OC_Files`` class was removed. + Instead use ``OCP\AppFramework\Http\StreamResponse`` or ``OCP\AppFramework\Http\ZipResponse``. +- The private and legacy Ajax endpoint for downloading file archives (``/apps/files/ajax/download.php``) was removed. + Instead use the Nextcloud provided :ref:`WebDAV endpoint`. +- All ``OCP\ILogger`` logging methods, deprecated since Nextcloud 20, are removed. + - The interface now only holds the Nextcloud internal logging level constants. + For all logging ``Psr\Log\LoggerInterface`` should be used. + - The ``OCP\ILogger`` interface can no longer be dependency injected as it now only holds constants. + - ``OCP\IServerContainer::getLogger`` was removed, use dependency injection with ``Psr\Log\LoggerInterface`` instead. +- The internal class ``OC\AppFramework\Logger`` was removed, it should have been never used by apps. + All using apps should migrate to ``Psr\Log\LoggerInterface``. diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_32.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_32.rst new file mode 100644 index 000000000..e99cee745 --- /dev/null +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_32.rst @@ -0,0 +1,55 @@ +======================= +Upgrade to Nextcloud 32 +======================= + +General +------- + +- TBD + +Front-end changes +----------------- + +Added APIs +^^^^^^^^^^ + +- TBD + +Changed APIs +^^^^^^^^^^^^ + +- TBD + +Deprecated APIs +^^^^^^^^^^^^^^^ + +- TBD + +Removed APIs +^^^^^^^^^^^^ + +- TBD + +Back-end changes +---------------- + +Added APIs +^^^^^^^^^^ + +- TBD + +Changed APIs +^^^^^^^^^^^^ + +- TBD + +Deprecated APIs +^^^^^^^^^^^^^^^ + +- The files API endpoint ``/apps/files/api/v1/thumbnail/`` for generating previews is deprecated. + Instead use the preview endpoint provided by Nextcloud core (``/core/preview``). + +Removed APIs +^^^^^^^^^^^^ + +- TBD diff --git a/developer_manual/app_publishing_maintenance/index.rst b/developer_manual/app_publishing_maintenance/index.rst index c1237b4d6..4f5bc498e 100644 --- a/developer_manual/app_publishing_maintenance/index.rst +++ b/developer_manual/app_publishing_maintenance/index.rst @@ -10,6 +10,7 @@ Transforming source files into a deliverable is documented in the :ref:`app-rele maintainer release_process Publishing App on the App Store + monetizing publishing code_signing release_automation diff --git a/developer_manual/app_publishing_maintenance/monetizing.rst b/developer_manual/app_publishing_maintenance/monetizing.rst new file mode 100644 index 000000000..90ad427ed --- /dev/null +++ b/developer_manual/app_publishing_maintenance/monetizing.rst @@ -0,0 +1,40 @@ +.. _app-store-monetizing: + +=================== +Monetizing your app +=================== + +.. sectionauthor:: Edward Ly + + +The Nextcloud app store offers various features that enable app developers to receive some financial compensation for their work. + +Donations +--------- + +App developers can add optional donation links/buttons that lead to configurable URLs. +This could be done by adding one or more donation tags in the app's ``info.xml`` file:: + + https://paypal.com/example + https://stripe.com/example + https://other.service.com/example + +The currently supported types include ``paypal`` and ``stripe``. +Having a type will display the corresponding service logo next to the donation link (or a generic logo if the type is not specified or is set to ``other``). +If a link/button title is not specified, it defaults to ``Donate to support this app``. +These buttons will appear in the appstore and in the app settings, and clicking on them will open their links in a new browser tab. + +.. note:: All donations received go directly to the developers. Nextcloud does not keep any commissions. + +Enterprise support +------------------ + +App developers can also add an optional ``Request quote`` button that will be shown in the appstore and app settings. +This button leads to the `Nextcloud sales form `_ where enterprise support for the app can be requested. +If Nextcloud receives an interesting request, the sales team will reach out to the developers to discuss a partnership to provide support together (similar to other apps such as Collabora and OnlyOffice). +Enterprise support targets larger Nextcloud installations of 100 users or more. + +To enable or disable the button, head to the **Enterprise support** page in the appstore account settings and click on **Mark as supported/unsupported** as appropriate next to the desired apps. + +.. image:: ../images/enterprise-support-settings.png + :alt: enterprise support settings page diff --git a/developer_manual/app_publishing_maintenance/publishing.rst b/developer_manual/app_publishing_maintenance/publishing.rst index c5800637c..bbe902d25 100644 --- a/developer_manual/app_publishing_maintenance/publishing.rst +++ b/developer_manual/app_publishing_maintenance/publishing.rst @@ -31,7 +31,7 @@ These are the app guidelines an app has to comply with to have a chance to be ap Legal and security ^^^^^^^^^^^^^^^^^^ -* Apps must be licensed under AGPLv3+ or any compatible license. +* Apps must be licensed under AGPL-3.0-or-later or any compatible license. * Apps must not use 'Nextcloud' in their name. * Irregular and unannounced security audits of all apps can and will take place. * If any indication of malicious intent or bad faith is found the developer(s) in question can count on a minimum 2 year ban from any Nextcloud infrastructure. diff --git a/developer_manual/app_publishing_maintenance/release_automation.rst b/developer_manual/app_publishing_maintenance/release_automation.rst index ecfe0c56b..908c682a6 100644 --- a/developer_manual/app_publishing_maintenance/release_automation.rst +++ b/developer_manual/app_publishing_maintenance/release_automation.rst @@ -106,8 +106,8 @@ If your repository lives within the nextcloud organization you need to use an en environment: release runs-on: ubuntu-latest -In this example we use the "release" environment, open the settings of your repository and open the "Envionments" tab, add a new environment with the name "release", make sure to activate "Required reviewers" only add the people you trust, they will be able to approve a release. -Save your rules and at the bottom add the following envionment secrets. +In this example we use the "release" environment, open the settings of your repository and open the "Environments" tab, add a new environment with the name "release", make sure to activate "Required reviewers" only add the people you trust, they will be able to approve a release. +Save your rules and at the bottom add the following environment secrets. * ``APP_PRIVATE_KEY`` your apps private key * ``APP_PUBLIC_CRT`` your apps certificate, this one could be public but for easy usage we add it as a secret @@ -127,7 +127,7 @@ Also make sure to remove ``environment: release`` . Makefile changes for code signing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As your certificate and your private key now are stored in environment variables you need somehow covert them to a file. +As your certificate and your private key now are stored in environment variables you need somehow convert them to a file. One example you may use is provided by the news app. .. code-block:: php diff --git a/developer_manual/app_publishing_maintenance/release_process.rst b/developer_manual/app_publishing_maintenance/release_process.rst index c13dc9e00..74cb7a376 100644 --- a/developer_manual/app_publishing_maintenance/release_process.rst +++ b/developer_manual/app_publishing_maintenance/release_process.rst @@ -91,7 +91,7 @@ The release process is identical to the one of a final release, only the version The updater channel defines if pre-releases are installed by the server. This setting can be found in the admin setting or in the ``config/config.php`` file. The server will install pre-releases if its update channel is set ``beta``, ``daily``, or ``git``. For all other settings, pre-releases will not be installed. -.. tip:: Don't publish the pre-releases as nightly version on the app store or Nextcloud installations won't be able to update. Releasing with any (alpha-numeric) suffix is sufficient to mark the release as not production ready and instances are still able to update to it. +.. tip:: Don't publish the pre-releases as nightly version on the app store or Nextcloud installations won't be able to update. Releasing with any (alphanumeric) suffix is sufficient to mark the release as not production ready and instances are still able to update to it. Nightly releases ~~~~~~~~~~~~~~~~ diff --git a/developer_manual/basics/_available_events_ocp.rst b/developer_manual/basics/_available_events_ocp.rst new file mode 100644 index 000000000..e118b3460 --- /dev/null +++ b/developer_manual/basics/_available_events_ocp.rst @@ -0,0 +1,976 @@ +.. This file is generated by nextcloud-ocp-events. +.. Always change the source file. + +``OCP\Accounts\UserUpdatedEvent`` +********************************* + +.. versionadded:: 28 + +This event is triggered when the account data of a user was updated. + +``OCP\App\Events\AppDisableEvent`` +********************************** + +.. versionadded:: 27 + +This event is triggered when an app is disabled. + +``OCP\App\Events\AppEnableEvent`` +********************************* + +.. versionadded:: 27 + +This event is triggered when an app is enabled. + +``OCP\App\Events\AppUpdateEvent`` +********************************* + +.. versionadded:: 27 + +This event is triggered when an app is updated. + +``OCP\App\ManagerEvent`` +************************ + +.. versionadded:: 9 + +Class ManagerEvent + +``OCP\AppFramework\Http\Events\BeforeLoginTemplateRenderedEvent`` +***************************************************************** + +.. versionadded:: 28 + +Emitted before the rendering step of the login TemplateResponse. + +``OCP\AppFramework\Http\Events\BeforeTemplateRenderedEvent`` +************************************************************ + +.. versionadded:: 20 + +Emitted before the rendering step of each TemplateResponse. The event holds a +flag that specifies if an user is logged in. + +``OCP\Authentication\Events\AnyLoginFailedEvent`` +************************************************* + +.. versionadded:: 26 + +Emitted when the authentication fails + +``OCP\Authentication\Events\LoginFailedEvent`` +********************************************** + +.. versionadded:: 19 + +Emitted when the authentication fails, but only if the login name can be associated with an existing user. + +``OCP\Authentication\TwoFactorAuth\RegistryEvent`` +************************************************** + +.. versionadded:: 15 + + +``OCP\Authentication\TwoFactorAuth\TwoFactorProviderChallengeFailed`` +********************************************************************* + +.. versionadded:: 28 + + +``OCP\Authentication\TwoFactorAuth\TwoFactorProviderChallengePassed`` +********************************************************************* + +.. versionadded:: 28 + + +``OCP\Authentication\TwoFactorAuth\TwoFactorProviderDisabled`` +************************************************************** + +.. versionadded:: 20 + + +``OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserDisabled`` +********************************************************************* + +.. versionadded:: 22 + + +``OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserEnabled`` +******************************************************************** + +.. versionadded:: 22 + + +``OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserRegistered`` +*********************************************************************** + +.. versionadded:: 28 + + +``OCP\Authentication\TwoFactorAuth\TwoFactorProviderForUserUnregistered`` +************************************************************************* + +.. versionadded:: 28 + + +``OCP\Authentication\TwoFactorAuth\TwoFactorProviderUserDeleted`` +***************************************************************** + +.. versionadded:: 28 + + +``OCP\BeforeSabrePubliclyLoadedEvent`` +************************************** + +.. versionadded:: 26 + +Dispatched before Sabre is loaded when accessing public webdav endpoints +This can be used to inject a Sabre plugin for example + +``OCP\Collaboration\AutoComplete\AutoCompleteEvent`` +**************************************************** + +.. versionadded:: 16 + + +``OCP\Collaboration\AutoComplete\AutoCompleteFilterEvent`` +********************************************************** + +.. versionadded:: 28 + + +``OCP\Collaboration\Reference\RenderReferenceEvent`` +**************************************************** + +.. versionadded:: 25 + +Event emitted when apps might render references like link previews or smart picker widgets. +This can be used to inject scripts for extending that. +Further details can be found in the :ref:`Reference providers` deep dive. + +``OCP\Collaboration\Resources\LoadAdditionalScriptsEvent`` +********************************************************** + +.. versionadded:: 25 + +This event is used by apps to register their own frontend scripts for integrating +projects in their app. Apps also need to dispatch the event in order to load +scripts during page load + +``OCP\Comments\CommentsEntityEvent`` +************************************ + +.. versionadded:: 9.1 + +.. versionchanged:: 28.0.0 + Dispatched as a typed event + +Class CommentsEntityEvent + +``OCP\Comments\CommentsEvent`` +****************************** + +.. versionadded:: 9 + +Class CommentsEvent + +``OCP\Config\BeforePreferenceDeletedEvent`` +******************************************* + +.. versionadded:: 25 + + +``OCP\Config\BeforePreferenceSetEvent`` +*************************************** + +.. versionadded:: 25 + + +``OCP\Console\ConsoleEvent`` +**************************** + +.. versionadded:: 9 + +Class ConsoleEvent + +``OCP\Contacts\Events\ContactInteractedWithEvent`` +************************************************** + +.. versionadded:: 19 + +An event that allows apps to notify other components about an interaction +between two users. This can be used to build better recommendations and +suggestions in user interfaces. +Emitters should add at least one identifier (uid, email, federated cloud ID) +of the recipient of the interaction. + +``OCP\DB\Events\AddMissingColumnsEvent`` +**************************************** + +.. versionadded:: 28 + +Event to allow apps to register information about missing database columns +This event will be dispatched for checking on the admin settings and when running +occ db:add-missing-columns which will then create those columns + +``OCP\DB\Events\AddMissingIndicesEvent`` +**************************************** + +.. versionadded:: 28 + +Event to allow apps to register information about missing database indices +This event will be dispatched for checking on the admin settings and when running +occ db:add-missing-indices which will then create those indices + +``OCP\DB\Events\AddMissingPrimaryKeyEvent`` +******************************************* + +.. versionadded:: 28 + +Event to allow apps to register information about missing database primary keys +This event will be dispatched for checking on the admin settings and when running +occ db:add-missing-primary-keys which will then create those keys + +``OCP\DirectEditing\RegisterDirectEditorEvent`` +*********************************************** + +.. versionadded:: 18 + +Event to allow to register the direct editor. + +``OCP\EventDispatcher\GenericEvent`` +************************************ + +.. versionadded:: 18 + +Class GenericEvent +convenience reimplementation of \Symfony\Component\GenericEvent against +\OCP\EventDispatcher\Event + +``OCP\Federation\Events\TrustedServerRemovedEvent`` +*************************************************** + +.. versionadded:: 25 + + +``OCP\Files\Cache\AbstractCacheEvent`` +************************************** + +.. versionadded:: 22 + + +``OCP\Files\Cache\CacheEntryInsertedEvent`` +******************************************* + +.. versionadded:: 21 + +Event for when an existing entry in the cache gets inserted + +``OCP\Files\Cache\CacheEntryRemovedEvent`` +****************************************** + +.. versionadded:: 21 + +Event for when an existing entry in the cache gets removed + +``OCP\Files\Cache\CacheEntryUpdatedEvent`` +****************************************** + +.. versionadded:: 21 + +Event for when an existing entry in the cache gets updated + +``OCP\Files\Cache\CacheInsertEvent`` +************************************ + +.. versionadded:: 16 + +Event for when a new entry gets added to the cache + +``OCP\Files\Cache\CacheUpdateEvent`` +************************************ + +.. versionadded:: 16 + +Event for when an existing entry in the cache gets updated + +``OCP\Files\Events\BeforeDirectFileDownloadEvent`` +************************************************** + +.. versionadded:: 25 + +This event is triggered when a user tries to download a file +directly. + +``OCP\Files\Events\BeforeFileScannedEvent`` +******************************************* + +.. versionadded:: 18 + + +``OCP\Files\Events\BeforeFolderScannedEvent`` +********************************************* + +.. versionadded:: 18 + + +``OCP\Files\Events\BeforeZipCreatedEvent`` +****************************************** + +.. versionadded:: 25 + + +``OCP\Files\Events\FileCacheUpdated`` +************************************* + +.. versionadded:: 18 + + +``OCP\Files\Events\FileScannedEvent`` +************************************* + +.. versionadded:: 18 + + +``OCP\Files\Events\FolderScannedEvent`` +*************************************** + +.. versionadded:: 18 + + +``OCP\Files\Events\InvalidateMountCacheEvent`` +********************************************** + +.. versionadded:: 24 + +Used to notify the filesystem setup manager that the available mounts for a user have changed + +``OCP\Files\Events\Node\BeforeNodeCopiedEvent`` +*********************************************** + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\BeforeNodeCreatedEvent`` +************************************************ + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\BeforeNodeDeletedEvent`` +************************************************ + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\BeforeNodeReadEvent`` +********************************************* + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\BeforeNodeRenamedEvent`` +************************************************ + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\BeforeNodeTouchedEvent`` +************************************************ + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\BeforeNodeWrittenEvent`` +************************************************ + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\FilesystemTornDownEvent`` +************************************************* + +.. versionadded:: 24 + +Event fired after the filesystem has been torn down + +``OCP\Files\Events\Node\NodeCopiedEvent`` +***************************************** + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\NodeCreatedEvent`` +****************************************** + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\NodeDeletedEvent`` +****************************************** + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\NodeRenamedEvent`` +****************************************** + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\NodeTouchedEvent`` +****************************************** + +.. versionadded:: 20 + + +``OCP\Files\Events\Node\NodeWrittenEvent`` +****************************************** + +.. versionadded:: 20 + + +``OCP\Files\Events\NodeAddedToCache`` +************************************* + +.. versionadded:: 18 + + +``OCP\Files\Events\NodeAddedToFavorite`` +**************************************** + +.. versionadded:: 28 + + +``OCP\Files\Events\NodeRemovedFromCache`` +***************************************** + +.. versionadded:: 18 + + +``OCP\Files\Events\NodeRemovedFromFavorite`` +******************************************** + +.. versionadded:: 28 + + +``OCP\Files\Template\BeforeGetTemplatesEvent`` +********************************************** + +.. versionadded:: 30 + + +``OCP\Files\Template\FileCreatedFromTemplateEvent`` +*************************************************** + +.. versionadded:: 21 + + +``OCP\Files\Template\RegisterTemplateCreatorEvent`` +*************************************************** + +.. versionadded:: 30 + + +``OCP\FilesMetadata\Event\MetadataBackgroundEvent`` +*************************************************** + +.. versionadded:: 28 + +MetadataBackgroundEvent is an event similar to MetadataLiveEvent but dispatched +on a background thread instead of live thread. Meaning there is no limit to +the time required for the generation of your metadata. + +``OCP\FilesMetadata\Event\MetadataLiveEvent`` +********************************************* + +.. versionadded:: 28 + +MetadataLiveEvent is an event initiated when a file is created or updated. +The app contains the Node related to the created/updated file, and a FilesMetadata that already +contains the currently known metadata. + +Setting new metadata, or modifying already existing metadata with different value, will trigger +the save of the metadata in the database. + +``OCP\FilesMetadata\Event\MetadataNamedEvent`` +********************************************** + +.. versionadded:: 28 + +MetadataNamedEvent is an event similar to MetadataBackgroundEvent completed with a target name, +used to limit the refresh of metadata only listeners capable of filtering themselves out. +Meaning that when using this event, your app must implement a filter on the event's registered +name returned by getName() + +This event is mostly triggered when a registered name is added to the files scan + i.e. ./occ files:scan --generate-metadata [name] + +``OCP\Group\Events\BeforeGroupChangedEvent`` +******************************************** + +.. versionadded:: 26 + + +``OCP\Group\Events\BeforeGroupCreatedEvent`` +******************************************** + +.. versionadded:: 18 + + +``OCP\Group\Events\BeforeGroupDeletedEvent`` +******************************************** + +.. versionadded:: 18 + + +``OCP\Group\Events\BeforeUserAddedEvent`` +***************************************** + +.. versionadded:: 18 + + +``OCP\Group\Events\BeforeUserRemovedEvent`` +******************************************* + +.. versionadded:: 18 + + +``OCP\Group\Events\GroupChangedEvent`` +************************************** + +.. versionadded:: 26 + + +``OCP\Group\Events\GroupCreatedEvent`` +************************************** + +.. versionadded:: 18 + + +``OCP\Group\Events\GroupDeletedEvent`` +************************************** + +.. versionadded:: 18 + + +``OCP\Group\Events\SubAdminAddedEvent`` +*************************************** + +.. versionadded:: 21 + + +``OCP\Group\Events\SubAdminRemovedEvent`` +***************************************** + +.. versionadded:: 21 + + +``OCP\Group\Events\UserAddedEvent`` +*********************************** + +.. versionadded:: 18 + + +``OCP\Group\Events\UserRemovedEvent`` +************************************* + +.. versionadded:: 18 + + +``OCP\Log\Audit\CriticalActionPerformedEvent`` +********************************************** + +.. versionadded:: 22 + +Emitted when the admin_audit app should log an entry + +``OCP\Log\BeforeMessageLoggedEvent`` +************************************ + +.. versionadded:: 28 + +Even for when a log item is being logged + +``OCP\Mail\Events\BeforeMessageSent`` +************************************* + +.. versionadded:: 19 + +Emitted before a system mail is sent. It can be used to alter the message. + +``OCP\OCM\Events\ResourceTypeRegisterEvent`` +******************************************** + +.. versionadded:: 28 + +Use this event to register additional OCM resources before the API returns +them in the OCM provider list and capability + +``OCP\Preview\BeforePreviewFetchedEvent`` +***************************************** + +.. versionadded:: 25.0.1 + +.. versionchanged:: 28.0.0 + the constructor arguments ``$width``, ``$height``, ``$crop`` and ``$mode`` are no longer nullable. + +Emitted before a file preview is being fetched. +It can be used to block preview rendering by throwing a ``OCP\Files\NotFoundException`` + +``OCP\Profile\BeforeTemplateRenderedEvent`` +******************************************* + +.. versionadded:: 25 + +Emitted before the rendering step of the public profile page happens. + +``OCP\SabrePluginEvent`` +************************ + +.. versionadded:: 8.2 + + +``OCP\Security\CSP\AddContentSecurityPolicyEvent`` +************************************************** + +.. versionadded:: 17 + +Allows to inject something into the default content policy. This is for +example useful when you're injecting Javascript code into a view belonging +to another controller and cannot modify its Content-Security-Policy itself. +Note that the adjustment is only applied to applications that use AppFramework +controllers. + +WARNING: Using this API incorrectly may make the instance more insecure. +Do think twice before adding whitelisting resources. Please do also note +that it is not possible to use the `disallowXYZ` functions. + +``OCP\Security\Events\GenerateSecurePasswordEvent`` +*************************************************** + +.. versionadded:: 18 + +Event to request a secure password to be generated + +``OCP\Security\Events\ValidatePasswordPolicyEvent`` +*************************************************** + +.. versionadded:: 18 + +This event can be emitted to request a validation of a password. +If a password policy app is installed and the password +is invalid, an `\OCP\HintException` will be thrown. + +``OCP\Security\FeaturePolicy\AddFeaturePolicyEvent`` +**************************************************** + +.. versionadded:: 17 + +Event that allows to register a feature policy header to a request. + +``OCP\Settings\Events\DeclarativeSettingsGetValueEvent`` +******************************************************** + +.. versionadded:: 29 + + +``OCP\Settings\Events\DeclarativeSettingsRegisterFormEvent`` +************************************************************ + +.. versionadded:: 29 + + +``OCP\Settings\Events\DeclarativeSettingsSetValueEvent`` +******************************************************** + +.. versionadded:: 29 + + +``OCP\Share\Events\BeforeShareCreatedEvent`` +******************************************** + +.. versionadded:: 28 + + +``OCP\Share\Events\BeforeShareDeletedEvent`` +******************************************** + +.. versionadded:: 28 + + +``OCP\Share\Events\ShareAcceptedEvent`` +*************************************** + +.. versionadded:: 28 + + +``OCP\Share\Events\ShareCreatedEvent`` +************************************** + +.. versionadded:: 18 + + +``OCP\Share\Events\ShareDeletedEvent`` +************************************** + +.. versionadded:: 21 + + +``OCP\Share\Events\ShareDeletedFromSelfEvent`` +********************************************** + +.. versionadded:: 28 + + +``OCP\Share\Events\VerifyMountPointEvent`` +****************************************** + +.. versionadded:: 19 + + +``OCP\SpeechToText\Events\TranscriptionFailedEvent`` +**************************************************** + +.. versionadded:: 27 + +This Event is emitted if a transcription of a media file using a Speech-To-Text provider failed + +``OCP\SpeechToText\Events\TranscriptionSuccessfulEvent`` +******************************************************** + +.. versionadded:: 27 + +This Event is emitted when a transcription of a media file happened successfully + +``OCP\SystemTag\ManagerEvent`` +****************************** + +.. versionadded:: 9 + +Class ManagerEvent + +``OCP\SystemTag\MapperEvent`` +***************************** + +.. versionadded:: 9 + +Class MapperEvent + +``OCP\SystemTag\SystemTagsEntityEvent`` +*************************************** + +.. versionadded:: 9.1 + +.. versionchanged:: 28.0.0 + Dispatched as a typed event + +Class SystemTagsEntityEvent + +``OCP\TaskProcessing\Events\TaskFailedEvent`` +********************************************* + +.. versionadded:: 30 + + +``OCP\TaskProcessing\Events\TaskSuccessfulEvent`` +************************************************* + +.. versionadded:: 30 + + +``OCP\TextProcessing\Events\TaskFailedEvent`` +********************************************* + +.. versionadded:: 27.1 + + +``OCP\TextProcessing\Events\TaskSuccessfulEvent`` +************************************************* + +.. versionadded:: 27.1 + + +``OCP\TextToImage\Events\TaskFailedEvent`` +****************************************** + +.. versionadded:: 28 + + +``OCP\TextToImage\Events\TaskSuccessfulEvent`` +********************************************** + +.. versionadded:: 28 + + +``OCP\User\Events\BeforePasswordUpdatedEvent`` +********************************************** + +.. versionadded:: 18 + +Emitted before the user password is updated. + +``OCP\User\Events\BeforeUserCreatedEvent`` +****************************************** + +.. versionadded:: 18 + +Emitted before a new user is created on the back-end. + +``OCP\User\Events\BeforeUserDeletedEvent`` +****************************************** + +.. versionadded:: 18 + + +``OCP\User\Events\BeforeUserLoggedInEvent`` +******************************************* + +.. versionadded:: 18 + + +``OCP\User\Events\BeforeUserLoggedInWithCookieEvent`` +***************************************************** + +.. versionadded:: 18 + +Emitted before a user is logged in via remember-me cookies. + +``OCP\User\Events\BeforeUserLoggedOutEvent`` +******************************************** + +.. versionadded:: 18 + +Emitted before a user is logged out. + +``OCP\User\Events\OutOfOfficeChangedEvent`` +******************************************* + +.. versionadded:: 28 + +Emitted when a user's out-of-office period has changed + +``OCP\User\Events\OutOfOfficeClearedEvent`` +******************************************* + +.. versionadded:: 28 + +Emitted when a user's out-of-office period is cleared + +``OCP\User\Events\OutOfOfficeEndedEvent`` +***************************************** + +.. versionadded:: 28 + +Emitted when a user's out-of-office period ended + +``OCP\User\Events\OutOfOfficeScheduledEvent`` +********************************************* + +.. versionadded:: 28 + +Emitted when a user's out-of-office period is scheduled + +``OCP\User\Events\OutOfOfficeStartedEvent`` +******************************************* + +.. versionadded:: 28 + +Emitted when a user's out-of-office period started + +``OCP\User\Events\PasswordUpdatedEvent`` +**************************************** + +.. versionadded:: 18 + +Emitted when the user password has been updated. + +``OCP\User\Events\PostLoginEvent`` +********************************** + +.. versionadded:: 18 + + +``OCP\User\Events\UserChangedEvent`` +************************************ + +.. versionadded:: 18 + + +``OCP\User\Events\UserCreatedEvent`` +************************************ + +.. versionadded:: 18 + +Emitted when a new user has been created on the back-end. + +``OCP\User\Events\UserDeletedEvent`` +************************************ + +.. versionadded:: 18 + + +``OCP\User\Events\UserFirstTimeLoggedInEvent`` +********************************************** + +.. versionadded:: 28 + + +``OCP\User\Events\UserLiveStatusEvent`` +*************************************** + +.. versionadded:: 20 + + +``OCP\User\Events\UserLoggedInEvent`` +************************************* + +.. versionadded:: 18 + + +``OCP\User\Events\UserLoggedInWithCookieEvent`` +*********************************************** + +.. versionadded:: 18 + +Emitted when a user has been successfully logged in via remember-me cookies. + +``OCP\User\Events\UserLoggedOutEvent`` +************************************** + +.. versionadded:: 18 + +Emitted when a user has been logged out successfully. + +``OCP\User\GetQuotaEvent`` +************************** + +.. versionadded:: 20 + +Event to allow apps to + +``OCP\WorkflowEngine\Events\LoadSettingsScriptsEvent`` +****************************************************** + +.. versionadded:: 20 + +Emitted when the workflow engine settings page is loaded. + +``OCP\WorkflowEngine\Events\RegisterChecksEvent`` +************************************************* + +.. versionadded:: 18 + + +``OCP\WorkflowEngine\Events\RegisterEntitiesEvent`` +*************************************************** + +.. versionadded:: 18 + + +``OCP\WorkflowEngine\Events\RegisterOperationsEvent`` +***************************************************** + +.. versionadded:: 18 + + diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst index 34bb1ddc3..c8de6729c 100644 --- a/developer_manual/basics/controllers.rst +++ b/developer_manual/basics/controllers.rst @@ -335,11 +335,176 @@ Cookies can be set or modified directly on the response class: } } - Responses --------- -Similar to how every controller receives a request object, every controller method has to return a Response. This can be in the form of a Response subclass or in the form of a value that can be handled by a registered responder. +Similar to how every controller receives a request object, every controller method has to return a Response. +This can be in the form of a Response subclass or in the form of a value that can be handled by a registered responder. + +There are different kinds of responses available, like HTML-based responses, data responses, or other. +The app decides of which kind the response is, by returning an appropriate ``Response`` object in the corresponding controller method. +The following sections give an overview over the various kinds and how to implement them. + +.. _controller_html_responses: + +HTML-based Responses +-------------------- + +HTML pages are typically served using template responses. +This is typically used as a starting point to load the website. +This code linked by the template is by default encapsulated by the server to provide some common styling (e.g. the header row). +The code then uses JavaScript to load further components (see :ref:`Frontend building in Vue`) and the actual data. +This section only focuses on the actual HTML content, not the data to fill into the dynamic pages. + +.. _controller_template: + +Templates +^^^^^^^^^ + +A :doc:`template ` can be rendered by returning a TemplateResponse. A TemplateResponse takes the following parameters: + +* **appName**: tells the template engine in which app the template should be located +* **templateName**: the name of the template inside the templates/ folder without the .php extension +* **parameters**: optional array parameters that are available in the template through $_, e.g.:: + + array('key' => 'something') + + can be accessed through:: + + $_['key'] + +* **renderAs**: defaults to *user*, tells Nextcloud if it should include it in the web interface, or in case *blank* is passed solely render the template + +.. code-block:: php + + 'hi'); + return new TemplateResponse($this->appName, $templateName, $parameters); + } + + } + +Public page templates +^^^^^^^^^^^^^^^^^^^^^ + +For public pages, that are rendered to users who are not logged in to the +Nextcloud instance, a ``OCP\\AppFramework\\Http\\Template\\PublicTemplateResponse`` should be used, to load the +correct base template. It also allows adding an optional set of actions that +will be shown in the top right corner of the public page. + + +.. code-block:: php + + appName, 'main', []); + $template->setHeaderTitle('Public page'); + $template->setHeaderDetails('some details'); + $template->setHeaderActions([ + new SimpleMenuAction('download', 'Label 1', 'icon-css-class1', 'link-url', 0), + new SimpleMenuAction('share', 'Label 2', 'icon-css-class2', 'link-url', 10), + ]); + return $template; + } + + } + +The header title and subtitle will be rendered in the header, next to the logo. +The action with the highest priority (lowest number) will be used as the +primary action, others will shown in the popover menu on demand. + +A ``OCP\\AppFramework\\Http\\Template\\SimpleMenuAction`` will be a link with an icon added to the menu. App +developers can implement their own types of menu renderings by adding a custom +class implementing the ``OCP\\AppFramework\\Http\\Template\\IMenuAction`` interface. + +Data-based responses +-------------------- + +In contrast to the HTML template responses, the data responses return some user-data in packed form. +There are different encodings thinkable like JSON, XML, or other formats. +The main point is that the data is requested by the browser using JavaScript on behalf of the shown website. +The user only indirectly requested the data by user interaction with the frontend. + + +.. _ocscontroller: + +OCS +^^^ + +.. note:: + This is purely for compatibility reasons. If you are planning to offer an external API, go for a :ref:`REST APIs ` instead. + +In order to simplify exchange of data between the Nextcloud backend and any client (be it the web frontend or whatever else), the OCS API has been introduced. +To use OCS in your API you can use the **OCP\\AppFramework\\OCSController** base class and return your data in the form of a **DataResponse** in the following way: + +.. code-block:: php + + ` can be registered as with any other ``Controller`` method. +The ``OCSController`` class have however automatically two responders pre-installed: +Both JSON (``application/json``) and XML (``text/xml``) are generated on-the-fly depending on the request by the browser/user. +To select the output format, the ``?format=`` query parameter or the ``Accept`` header of the request work out of the box, no intervention is required. +It is advised to prefer the header generally, as this is the more standardized way. + +To make routing work for OCS, the route must be registered in the core. +This can be done in two ways: +You can add an attribute `#[ApiRoute]` to the controller method. +Alternatively, you can add :ref:`a separate 'ocs' entry` to the routing table in ``appinfo/routes.php`` of your app. +Inside these, there are the same information as there are for normal routes. + +.. code-block:: php + + [ + [ + 'name' => 'Share#getShares', + 'url' => '/api/v1/shares', + 'verb' => 'GET', + ], + ], + ]; + +Now your method will be reachable via ``/ocs/v2.php/apps//api/v1/shares`` + +.. versionadded:: 29 + You can use the attribute ``ApiRoute`` as described in :doc:`Routing ` instead of the entry in ``appinfo/routes.php`` as an alternative. + JSON ^^^^ @@ -382,6 +547,36 @@ Because returning JSON is such a common task, there's even a shorter way to do t Why does this work? Because the dispatcher sees that the controller did not return a subclass of a Response and asks the controller to turn the value into a Response. That's where responders come in. +Handling errors +^^^^^^^^^^^^^^^ + +Sometimes a request should fail, for instance if an author with id 1 is requested but does not exist. In that case use an appropriate `HTTP error code `_ to signal the client that an error occurred. + +Each response subclass has access to the **setStatus** method which lets you set an HTTP status code. To return a JSONResponse signaling that the author with id 1 has not been found, use the following code: + +.. code-block:: php + + ` can be rendered by returning a TemplateResponse. A TemplateResponse takes the following parameters: - -* **appName**: tells the template engine in which app the template should be located -* **templateName**: the name of the template inside the templates/ folder without the .php extension -* **parameters**: optional array parameters that are available in the template through $_, e.g.:: - - array('key' => 'something') - - can be accessed through:: - - $_['key'] - -* **renderAs**: defaults to *user*, tells Nextcloud if it should include it in the web interface, or in case *blank* is passed solely render the template - -.. code-block:: php - - 'hi'); - return new TemplateResponse($this->appName, $templateName, $parameters); - } - - } - -Public page templates -^^^^^^^^^^^^^^^^^^^^^ - -For public pages, that are rendered to users who are not logged in to the -Nextcloud instance, a ``OCP\\AppFramework\\Http\\Template\\PublicTemplateResponse`` should be used, to load the -correct base template. It also allows adding an optional set of actions that -will be shown in the top right corner of the public page. - - -.. code-block:: php - - appName, 'main', []); - $template->setHeaderTitle('Public page'); - $template->setHeaderDetails('some details'); - $template->setHeaderActions([ - new SimpleMenuAction('download', 'Label 1', 'icon-css-class1', 'link-url', 0), - new SimpleMenuAction('share', 'Label 2', 'icon-css-class2', 'link-url', 10), - ]); - return $template; - } - - } - -The header title and subtitle will be rendered in the header, next to the logo. -The action with the highest priority (lowest number) will be used as the -primary action, others will shown in the popover menu on demand. - -A ``OCP\\AppFramework\\Http\\Template\\SimpleMenuAction`` will be a link with an icon added to the menu. App -developers can implement their own types of menu renderings by adding a custom -class implementing the ``OCP\\AppFramework\\Http\\Template\\IMenuAction`` interface. - - +Some special responses are available as well. +These are discussed here. Redirects ^^^^^^^^^ @@ -643,9 +765,6 @@ By default all responses are rendered at once and sent as a string through middl } - - - If you want to use a custom, lazily rendered response simply implement the interface **OCP\\AppFramework\\Http\\ICallbackResponse** for your response: .. code-block:: php @@ -666,157 +785,31 @@ If you want to use a custom, lazily rendered response simply implement the inter .. note:: Because this code is rendered after several usually built in helpers, you need to take care of errors and proper HTTP caching by yourself. -Modifying the content security policy -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Security considerations +----------------------- -By default Nextcloud disables all resources which are not served on the same domain, forbids cross domain requests and disables inline CSS and JavaScript by setting a `Content Security Policy `_. -However if an app relies on third-party media or other features which are forbidden by the current policy the policy can be relaxed. +Depending on your use-case, you can tighten or loosen the security measurements installed by default on the routes. +This section gives you a quick overview over the options. -.. note:: Double check your content and edge cases before you relax the policy! Also read the `documentation provided by MDN `_ - -To relax the policy pass an instance of the ContentSecurityPolicy class to your response. The methods on the class can be chained. - -The following methods turn off security features by passing in **true** as the **$isAllowed** parameter - -* **allowInlineScript** (bool $isAllowed) -* **allowInlineStyle** (bool $isAllowed) -* **allowEvalScript** (bool $isAllowed) -* **useStrictDynamic** (bool $isAllowed) - - Trust all scripts that are loaded by a trusted script, see 'script-src' and 'strict-dynamic' - -* **useStrictDynamicOnScripts** (bool $isAllowed) - - Trust all scripts that are loaded by a trusted script which was loaded using a ``