mirrors/nextcloud-documentation
3
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2025-10-26 11:18:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into rakekniven-patch-1

Browse Source
This commit is contained in:
rakekniven 2021-10-04 16:26:44 +02:00
commit b0c8a7fd2d
634 changed files with 42946 additions and 6968 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
.github/workflows/fixup.yml vendored Normal file
View File

@ -0,0 +1,20 @@
# 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: Pull request checks
on: pull_request
jobs:
commit-message-check:
name: Block fixup and squash commits
runs-on: ubuntu-latest
steps:
- name: Run check
uses: xt0rted/block-autosquash-commits-action@v2
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}

8
.github/workflows/sphinxbuild.yml vendored
View File

@ -1,7 +1,11 @@
name: "Pull Request Docs Check"
on:
- pull_request
- push
pull_request:
push:
branches:
- master
- stable*
jobs:
user_manual:

7
.gitignore vendored
View File

@ -34,3 +34,10 @@ developer_manual/design/icons.txt
# pipenv / virtualenv
venv
# VScode
.vscode/
*.code-workspace
# Local History for Visual Studio Code
.history/

28
README.rst
View File

@ -50,54 +50,54 @@ from GitHub.
Editing
-------
Contributing to the documentation requires a Github account. Make sure you are
Contributing to the documentation requires a GitHub account. Make sure you are
working in the correct branch for your version of Nextcloud or client apps.
If your edits pertain to multiple manual versions, be prepared to backport as
needed.
To edit a document, you can edit the .rst files on your local system, or work
directly on Github. The latter is only suitable for small fixes and improvements
directly on GitHub. The latter is only suitable for small fixes and improvements
because substantial editing efforts can better be controlled on your local PC.
The best way is to install a complete Sphinx build environment and work on your
local PC. You will be able to make your own local builds, which is the fastest
and best way to preview for errors. Sphinx will report syntax errors, missing
images, and formatting errors. The Github preview is not complete and misses
images, and formatting errors. The GitHub preview is not complete and misses
many mistakes. Create a new branch against the master or stable branch you are
editing, make your edits, then push your new branch to Github and open a new PR.
editing, make your edits, then push your new branch to GitHub and open a new PR.
To edit on Github, fork the repository (see top-right of the screen, under
To edit on GitHub, fork the repository (see top-right of the screen, under
your username). You will then be able to make changes easily. Once done,
you can create a pull request and get the changes reviewed and back into
the official repository.
When editing either on your own local PC or on Github, be sure to sign of
When editing either on your own local PC or on GitHub, be sure to sign of
commits, to certify adherence to the Developer Certificate of Origin,
see https://github.com/probot/dco . Your commit messages need to have,
see https://github.com/probot/dco . Your commit messages need to have,
the name and email address of the contributor.
Signed-off-by: Awesome Contributor <awesome.contributor@reach.me>
If using the command line and your name and email are configured, you can use
If using the command line and your name and email are configured, you can use
git commit -s -m 'Commit message'
In both settings be sure that your email address matches that in your Github profile,
In both settings be sure that your email address matches that in your GitHub profile,
which if you have privacy enabled will be github.username@users.noreply.github.com
Translations
------------
[Help translate the documentation](https://www.transifex.com/nextcloud/nextcloud-user-documentation/dashboard/).
`Help translate the documentation <https://www.transifex.com/nextcloud/nextcloud-user-documentation/dashboard/>`_.
For developers that want to ease the translation process, please read [this documentation](https://docs.transifex.com/integrations/sphinx-doc).
For developers that want to ease the translation process, please read `this documentation <https://docs.transifex.com/integrations/sphinx-doc>`_.
Building
--------
1. Install `pipenv` - https://pipenv.readthedocs.io/en/latest/
2. Create a Python environment (typically inside this repository): `pipenv --python 3.8`
2. Create a Python environment (typically inside this repository): `pipenv --python 3.9`
3. Change into the environment: `pipenv shell`
4. Install the dependencies `pip install -r requirements.txt`
5. Now you can use `make ...` to build all the stuff - for example `make html` to build the HTML flavor of all manuals

8
admin_manual/configuration_database/linux_database_configuration.rst
View File

@ -140,7 +140,7 @@ You can quit the prompt by entering::
quit;
An Nextcloud instance configured with MySQL would contain the hostname on which
A Nextcloud instance configured with MySQL would contain the hostname on which
the database is running, a valid username and password to access it, and the
name of the database. The :file:`config/config.php` as created by the
:doc:`../installation/installation_wizard` would therefore contain entries like
@ -164,6 +164,8 @@ In case of UTF8MB4 you will also find::
SSL for MySQL Database
^^^^^^^^^^^^^^^^^^^^^^
Enabling SSL is only necessary if your database does not reside on the same server as your Nextcloud instance.
If you do not connect over localhost and need to allow remote connections then you should enable SSL.
This just covers the SSL database configuration on the Nextcloud server. First you need to configure your database server accordingly.
::
@ -174,7 +176,7 @@ This just covers the SSL database configuration on the Nextcloud server. First y
\PDO::MYSQL_ATTR_SSL_CA => '/../ca-cert.pem',
\PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => true,
],
Adjust the paths to the pem files for your environment.
PostgreSQL database
@ -332,7 +334,7 @@ the respective host name::
+---------------+--------+
| Variable_name | Value |
+---------------+--------+
| version | 5.1.67 |
| version | 8.0.22 |
+---------------+--------+
1 row in set (0.00 sec)
mysql> quit

115
admin_manual/configuration_database/mysql_4byte_support.rst
View File

@ -9,65 +9,40 @@ Enabling MySQL 4-byte support
In order to use Emojis (textbased smilies) on your Nextcloud server with a MySQL database, the
installation needs to be tweaked a bit.
1. Make sure your database is set to use the Barracuda InnoDB file format (this is only needed on MySQL 5.x and MariaDB < 10.3):
.. note::
Login to your mysql database and run::
This manual only covers MySQL 8 or newer and MariaDB 10.3 or newer. If you use an older version, please check an older version of the documentation
mysql> show variables like 'innodb_file_format';
+--------------------+-----------+
| Variable_name | Value |
+--------------------+-----------+
| innodb_file_format | Barracuda |
+--------------------+-----------+
1 row in set (0.00 sec)
1. Make sure the following InnoDB settings are set on your MySQL server::
If your `innodb_file_format` is set as 'Antelope' you must upgrade your file format using::
[mysqld]
innodb_file_per_table=1
mysql> SET GLOBAL innodb_file_format=Barracuda;
Note::
.. note::
mysql> show variables like 'innodb_file_per_table';
+-----------------------+-------+
| Variable_name | Value |
+-----------------------+-------+
| innodb_file_per_table | ON |
+-----------------------+-------+
1 row in set (0.00 sec)
On some shared hosts, you may not have the permissions to upgrade the InnoDB file format, meaning you are unable to use utf8mb4
2. Make sure the following InnoDB settings are set on your MySQL server:
a. MySQL 8.0 or later::
[mysqld]
innodb_file_per_table=1
Note::
mysql> show variables like 'innodb_file_per_table';
+-----------------------+-------+
| Variable_name | Value |
+-----------------------+-------+
| innodb_file_per_table | ON |
+-----------------------+-------+
1 row in set (0.00 sec)
b. MySQL older than 8.0::
[mysqld]
innodb_large_prefix=true
innodb_file_format=barracuda
innodb_file_per_table=1
3. Open a shell, change dir (adjust ``/var/www/nextcloud`` to your nextcloud location if needed), and put your nextcloud instance in maintenance mode, if it isn't already::
2. Open a shell, change dir (adjust ``/var/www/nextcloud`` to your nextcloud location if needed), and put your nextcloud instance in maintenance mode, if it isn't already::
$ cd /var/www/nextcloud
$ sudo -u www-data php occ maintenance:mode --on
4. Restart the MySQL server in case you changed the configuration in step 1.
5. Change your databases character set and collation::
3. Restart the MySQL server in case you changed the configuration in step 1.
4. Change your databases character set and collation::
ALTER DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
6. Set the ``mysql.utf8mb4`` config to true in your config.php::
5. Set the ``mysql.utf8mb4`` config to true in your config.php::
$ sudo -u www-data php occ config:system:set mysql.utf8mb4 --type boolean --value="true"
7. Convert all existing tables to the new collation by running the repair step::
6. Convert all existing tables to the new collation by running the repair step::
$ sudo -u www-data php occ maintenance:repair
@ -75,7 +50,7 @@ installation needs to be tweaked a bit.
This will also change the `ROW_FORMAT` to `COMPRESSED` for your tables, to make sure the used database storage size is not getting out of hand.
8. Disable maintenance mode::
7. Disable maintenance mode::
$ sudo -u www-data php occ maintenance:mode --off
@ -84,55 +59,3 @@ Now you should be able to use Emojis in your file names, calendar events, commen
.. note::
Also make sure your backup strategy still work. If you use ``mysqldump`` make sure to add the ``--default-character-set=utf8mb4`` option. Otherwise your backups are broken and restoring them will result in ``?`` instead of the emojis, making files inaccessible.
MariaDB support
---------------
MariaDB 10.3 or later
=====================
1. Make sure the following InnoDB settings are set on your MariaDB server::
[mysqld]
innodb_file_per_table=1
2. Restart the MariaDB server.
3. Continue at step 3 of the **MySQL** instructions.
MariaDB 10.2 or earlier
=======================
.. note::
All mysql statements have to be executed as privileged database user. (Using "normal" nextcloud database user will result in empty query sets due to missing privileges for INFORMATION_SCHEMA database.)
1. Make sure the following InnoDB settings are set on your MySQL server::
[mysqld]
innodb_large_prefix=true
innodb_file_format=barracuda
innodb_file_per_table=1
2. Restart the MariaDB server.
3. Figure out whether the file format was changed to Barracuda::
MariaDB> SELECT NAME, SPACE, FILE_FORMAT FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME like "nextcloud%";
If the file format is "Barracuda" for every single table, nothing special is left to do. Continue with the MySQL instructions at step 3. While testing, all tables' file format was "Antelope".
4. The tables needs to be migrated to "Barracuda" manually, one by one. SQL commands can be created easily, however::
MariaDB> USE INFORMATION_SCHEMA;
MariaDB> SELECT CONCAT("ALTER TABLE `", TABLE_SCHEMA,"`.`", TABLE_NAME, "` ROW_FORMAT=DYNAMIC;") AS MySQLCMD FROM TABLES WHERE TABLE_SCHEMA = "nextcloud";
This will return an SQL command for each table in the nextcloud database. The rows can be quickly copied into a text editor, the "|"s replaced and the SQL commands copied back to the MariaDB shell. If no error appeared (in doubt check step 2) all is done and nothing is left to do here. It can be proceded with the MySQL instructions from step 3 onwards.
5. It is possible, however, that some tables cannot be altered. The operations fails with: "ERROR 1478 (HY000): Table storage engine 'InnoDB' does not support the create option 'ROW_FORMAT'". In that case the failing tables have a SPACE value of 0 in step 2. It basically means that the table does not have an index file of its own, which is required for the Barracuda format. This can be solved with a slightly different SQL command::
MariaDB> ALTER TABLE `nextcloud`.`oc_tablename` ROW_FORMAT=DYNAMIC, ALGORITHM=COPY;
Replace oc_tablename with the failing table. If there are too many (did not happen here), SQL commands can be generated in a batch (task for the reader).
6. Now everything should be fine and the MySQL instructions can be followed from step 3 onwards.

22
admin_manual/configuration_files/big_file_upload_configuration.rst
View File

@ -40,6 +40,11 @@ relevant php.ini files) ::
php_value upload_max_filesize 16G
php_value post_max_size 16G
The ``upload_max_filesize`` and ``post_max_size`` settings may not apply to file uploads
through WebDAV single file PUT requests or `Chunked file uploads
<https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/chunking.html>`_
For those, PHP and webserver timeouts are the limiting factor on the upload size.
Adjust these values for your needs. If you see PHP timeouts in your logfiles,
increase the timeout values, which are in seconds::
@ -144,8 +149,19 @@ 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
sudo -u www-data php occ config:app:set files max_chunk_size --value 20971520
Put in a value in bytes or set ``--value 0`` for no chunking at all.
Put in a value in bytes (in this example, 20MB). Set ``--value 0`` for no chunking at all.
Default is 10485760 (10 MB).
Default is 10485760 (10 MiB).
Large file upload on object storage
-----------------------------------
`Chunked file uploads <https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/chunking.html>`_
do have a larger space consumption on the temporary folder when processing those uploads
on object storage as the individual chunks get downloaded from the storage and will be assembled
to the actual file on the Nextcloud servers temporary directory. It is recommended to increase
the size of your temp directory accordingly and also ensure that request timeouts are high
enough for PHP, webservers or any load balancers involved.

5
admin_manual/configuration_files/encryption_migration.rst
View File

@ -5,8 +5,7 @@ Encryption migration
Encryption format
-----------------
Nextcloud still supports the legacy encryption scheme used for server side encryption.
However it is recommended to check if you have to still support this scheme.
Nextcloud still supports the legacy encryption scheme used for server side encryption where the encrypted files did not contain header information. This may still be used for installations that still have encrypted files from <= ownCloud 6. Files will be updated to the new encryption format once they are written again. However it is recommended to check if you have to still support this scheme.
Starting with version 20 for new installations the legacy encryption will be off by default.
However if you are upgrading there is a migration path to check if you can disable legacy encryption.
@ -19,6 +18,6 @@ On the command line run:
occ encryption:scan:legacy-format
The command will tell you if you can remove the legacy encryption mode.
If so remove the `encryption.legacy_format_support` from your config.php or set it to `false`.
If so set the `encryption.legacy_format_support` in your config.php to 'false'.

5
admin_manual/configuration_files/external_storage/auth_mechanisms.rst
View File

@ -38,15 +38,18 @@ credentials and therefore cannot perform any background tasks on the storage:
* Sharing is disabled
* Background file scanning does not work
* Background versions expiration does not work
* Desktop and mobile clients that use tokens to authenticate can not access those shares
* Other services that might request the file through a different request like Collabora Online or OnlyOffice will not be able to open files from that storage
* The method cannot be used with SAML authentication, because Nextcloud does not get a hold of any credentials whatsoever
* The method cannot be used with SAML/SSO authentication, because Nextcloud does not get a hold of any credentials whatsoever
The **Log-in credentials, save in database** mechanism uses the Nextcloud login
credentials of the user to connect to the storage. These are stored in the
database encrypted with the shared secret. This allows to share files from
within this mount point.
* The method cannot be used with SAML/SSO authentication, because Nextcloud does not get a hold of any credentials whatsoever
The **User entered, store in database** mechanism work in the same way as the
"Username and password" mechanism but the credentials need to be specified by
each user individually. Before the first access to that mount point the user

BIN
admin_manual/configuration_files/external_storage/images/enable-app.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 5.9 KiB

BIN
admin_manual/configuration_files/external_storage/images/externalStorages_variables.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.8 KiB

2
admin_manual/configuration_files/external_storage/smb.rst
View File

@ -83,7 +83,7 @@ Decrease sync delay
^^^^^^^^^^^^^^^^^^^
Any updates detected by the notify command will only be synced to the client after the Nextcloud cron job has been executed
(usually every 15 minutes). If this interval is to high for your use case, you can decrease it by running ``occ files:scan --unscanned --all``
(usually every 15 minutes). If this interval is too high for your use case, you can decrease it by running ``occ files:scan --unscanned --all``
at the desired interval. Note that this might increase the server load and you'll need to ensure that there is no overlap between runs.
Hidden files upload failure or not shown

17
admin_manual/configuration_files/external_storage_configuration_gui.rst
View File

@ -48,6 +48,23 @@ re-check your configuration and network availability.
If there is an error on the storage, it will be marked as unavailable for ten
minutes. To re-check it, click the colored icon or reload your Admin page.
Usage of variables for mount paths
----------------------------------
The external storage mounting mechanism accepts variables in the mount path.
Use ``$user`` for automatic substitution with the logged in user's username.
Use ``$home`` for automatic substitution with a configurable home directory variable
(requires LDAP, see :ref:`LDAP_Special_Attributes` in the LDAP configuration documentation for details)
In the following example, the mount point for a logged in user "alice" would substitute
to ``/opt/userDirectories/alice/myPictures``.
.. figure:: external_storage/images/externalStorages_variables.png
:alt: External storage user variable substitution
User and group permissions
--------------------------

30
admin_manual/configuration_files/primary_storage.rst
View File

@ -154,7 +154,31 @@ The class to be used is :code:`\\OC\\Files\\ObjectStore\\S3`
Multibucket Object Store
------------------------
It's possible to configure Nextcloud to distribute its data over multiple buckets
for scalability purpose. You can find out more information about upscaling with
object storage and Nextcloud in the
It's possible to configure Nextcloud to distribute the data over multiple buckets
for scalability purposes.
To setup multiple buckets, use :code:`'objectstore_multibucket'` storage backend
in :code:`config.php`:
::
'objectstore_multibucket' => [
'class' => 'Object\\Storage\\Backend\\Class',
'arguments' => [
// optional, defaults to 64
'num_buckets' => 64,
// will be postfixed by an integer in the range from 0 to (num_nuckets-1)
'bucket' => 'nextcloud_',
...
],
],
Multibucket object store backend maps every user to a range of buckets and saves
all files for that user in their corresponding bucket.
.. note:: While it is possible to change the number of buckets used by an existing Nextcloud
instance, the user-to-buckets mapping is only created once, so only newly created
users will be mapped to the updated range of buckets.
You can find out more information about upscaling with object storage and Nextcloud in the
`Nextcloud customer portal <https://portal.nextcloud.com/article/object-store-as-primary-storage-16.html>`_.

27
admin_manual/configuration_server/admin_delegation_configuration.rst Normal file
View File

@ -0,0 +1,27 @@
======================
Admin right priviledge
======================
By default only members of the admin group can access and edit the admin
settings. It is sometimes needed to give some group of users access to a
setting page while not giving them access to everything. For this you can
use the *Admin right priviledge* settings.
.. note::
Not every setting pages support this features. This is due to either the
feature not being implemented yet for the specific setting page or due
to possible priviledge escalations.
Configuring Admin right priviledge
==================================
Go to the *Admin right priviledge* Admin page, you should be presented
with the list of settings that support this features.
.. figure:: images/admin-right.png
By clicking on the combobox, you will be able to choose which user groups
are able to access the selected setting. You can revoke the access at any
time by removing the group from the selection.

14
admin_manual/configuration_server/antivirus_configuration.rst
View File

@ -76,28 +76,28 @@ That should take care of everything. Enable verbose logging in ``scan.conf``
and ``freshclam.conf`` until it is running the way you want.
Docker, Docker-compose
To install ClamAV via docker or docker compose you can take one of unofficial images of ClamAV, or build one by yourself.
This example is based on docker image from https://github.com/UKHomeOffice/docker-clamav.
To install ClamAV via docker or docker compose you can take official image of ClamAV, or build one by yourself.
This example is based on docker image from https://github.com/Cisco-Talos/clamav.
You can mount ClamAV Socket from the Docker Container to the host System as volume. In this case you do not need to expose any port outside of container.
Also you need to edit config files as described above and added configuration for a local Socket. In this particular Image configuration parameters could be passed via ``CLAMD_SETTINGS_CSV``.
For a Docker run this command::
docker run --name clamav -d -v /var/run/clamav/:/var/run/clamav/ -e CLAMD_SETTINGS_CSV="LocalSocket=/var/run/clamav/clamd.ctl" quay.io/ukhomeofficedigital/clamav:latest
docker run --name clamav -d -v /var/run/clamav/:/var/run/clamav/ -v /var/docker/clamav/virus_db/:/var/lib/clamav/ clamav/clamav:stable_base
For a Docker-compose use following settings::
version: "3.6"
services:
clamav:
image: "quay.io/ukhomeofficedigital/clamav:latest"
image: "clamav/clamav:stable_base"
container_name: "clamav"
volumes:
# Socket
- /var/run/clamav/:/var/run/clamav/
# Virus DB
- /var/docker/clamav/virus_db/:/var/lib/clamav/
restart: unless-stopped
environment:
- CLAMD_SETTINGS_CSV=LocalSocket=/var/run/clamav/clamd.ctl
Enabling the antivirus app for files
------------------------------------

15
admin_manual/configuration_server/background_jobs_configuration.rst
View File

@ -57,6 +57,8 @@ access your server using the Internet. For example::
URL to call: http[s]://<domain-of-your-server>/nextcloud/cron.php
.. _system-cron-configuration-label:
Cron
^^^^
@ -88,6 +90,8 @@ Which returns::
.. note:: On some systems it might be required to call **php-cli** instead of **php**.
.. note:: For some configurations, it might be neccessary 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/
@ -103,25 +107,28 @@ This approach requires two files: **nextcloudcron.service** and **nextcloudcron.
[Unit]
Description=Nextcloud cron.php job
[Service]
User=www-data
ExecStart=/usr/bin/php -f /var/www/nextcloud/cron.php
ExecStart=/usr/bin/php -f /var/www/nextcloud/cron.php
KillMode=process
Replace the user ``www-data`` with the user of your http server and ``/var/www/nextcloud/cron.php`` with the location of **cron.php** in your nextcloud directory.
The ``KillMode=process`` setting is necessary for external programs that are started by the cron job to keep running after the cron job has finished.
Note that the **.service** unit file does not need an ``[Install]`` section. Please check your setup because we recommended it in earlier versions of this admin manual.
**nextcloudcron.timer** should look like this::
[Unit]
Description=Run Nextcloud cron.php every 5 minutes
[Timer]
OnBootSec=5min
OnUnitActiveSec=5min
Unit=nextcloudcron.service
[Install]
WantedBy=timers.target

2
admin_manual/configuration_server/bruteforce_configuration.rst
View File

@ -19,7 +19,7 @@ brute force protection kicking in.
The maximum delay is 25 seconds.
After a successfull login the attempts will be cleared. And once a user is
After a successful login the attempts will be cleared. And once a user is
properly authenticated they will not longer be hit by the delay.

17
admin_manual/configuration_server/caching_configuration.rst
View File

@ -131,6 +131,23 @@ You might need to restart apache for the changes to take effect::
Redis is very configurable; consult `the Redis documentation
<http://redis.io/documentation>`_ to learn more.
**Using the Redis session handler:** If you are using Redis for locking and/or caching,
you may also wish to use Redis for session management. Redis can be used for centralized
session management across multiple Nextcloud application servers, unlike the standard
`files` handler. If you use the Redis handler, though, you *MUST* ensure that session
locking is enabled. As of this writing, the Redis session handler does *NOT* enable
session locking by default, which can lead to session corruption in some Nextcloud apps
that make heavy use of session writes such as Talk. In addition, even when session locking
is enabled, if the application fails to acquire a lock, the Redis session handler does not
currently return an error. Adding the following settings in your `php.ini` file will
prevent session corruption when using Redis as your session handler: ::
redis.session.locking_enabled=1
redis.session.lock_retries=-1
redis.session.lock_wait_time=10000
More information on configuration of phpredis session handler can be found on the
`PhpRedis GitHub page <https://github.com/phpredis/phpredis>`_
Memcached
---------

201
admin_manual/configuration_server/config_sample_php_parameters.rst
View File

@ -264,6 +264,17 @@ login or shared items. User's locale preferences configured under "personal
Defaults to ``en``
::
'default_phone_region' => 'GB',
This sets the default region for phone numbers on your Nextcloud server,
using ISO 3166-1 country codes such as ``DE`` for Germany, ``FR`` for France, …
It is required to allow inserting phone numbers in the user profiles starting
without the country code (e.g. +49 for Germany).
No default value!
::
'force_locale' => 'en_US',
@ -278,15 +289,15 @@ Defaults to ``false``
::
'defaultapp' => 'files',
'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
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 Files app.
on. If no enabled apps are found it defaults to the dashboard app.
Defaults to ``files``
Defaults to ``dashboard,files``
::
@ -317,6 +328,9 @@ Defaults to ``60*60*24*15`` seconds (15 days)
The lifetime of a session after inactivity.
The maximum possible time is limited by the session.gc_maxlifetime php.ini setting
which would overwrite this option if it is less than the value in the config.php
Defaults to ``60*60*24`` seconds (24 hours)
::
@ -379,6 +393,16 @@ Defaults to ``true``
By default WebAuthn is available but it can be explicitly disabled by admins
::
'hide_login_form' => false,
By default the login form is always available. There are cases (SSO) where an
admin wants to avoid users entering their credentials to the system if the SSO
app is unavailable.
This will show an error. But the the direct login still works with adding ?direct=1
::
'skeletondirectory' => '/path/to/nextcloud/core/skeleton',
@ -393,6 +417,22 @@ to ``de``). If that does not exist either, it falls back to ``default``
Defaults to ``core/skeleton`` in the Nextcloud directory.
::
'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
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.
::
'lost_password_link' => 'https://example.org/link/to/password/reset',
@ -814,7 +854,9 @@ Defaults to ``false``
'updatechecker' => true,
Check if Nextcloud is up-to-date and shows a notification if a new version is
available.
available. It sends current version, php version, installation and last update
time and release channel to the updater server which responds with the latest
available version based on those metrics.
Defaults to ``true``
@ -1001,17 +1043,17 @@ Defaults to an empty array.
'logdateformat' => 'F d, Y H:i:s',
This uses PHP.date formatting; see http://php.net/manual/en/function.date.php
This uses PHP.date formatting; see https://www.php.net/manual/en/function.date.php
Defaults to ISO 8601 ``2005-08-15T15:52:01+00:00`` - see \DateTime::ATOM
(https://secure.php.net/manual/en/class.datetime.php#datetime.constants.atom)
(https://www.php.net/manual/en/class.datetime.php#datetime.constants.atom)
::
'logtimezone' => 'Europe/Berlin',
The timezone for logfiles. You may change this; see
http://php.net/manual/en/timezones.php
https://www.php.net/manual/en/timezones.php
Defaults to ``UTC``
@ -1190,7 +1232,6 @@ Defaults to ``''`` (empty string)
'OC\Preview\PNG',
'OC\Preview\JPEG',
'OC\Preview\GIF',
'OC\Preview\HEIC',
'OC\Preview\BMP',
'OC\Preview\XBitmap',
'OC\Preview\MP3',
@ -1206,6 +1247,7 @@ The following providers are disabled by default due to performance or privacy
concerns:
- OC\\Preview\\Illustrator
- OC\\Preview\\HEIC
- OC\\Preview\\Movie
- OC\\Preview\\MSOffice2003
- OC\\Preview\\MSOffice2007
@ -1223,7 +1265,6 @@ Defaults to the following providers:
- OC\\Preview\\BMP
- OC\\Preview\\GIF
- OC\\Preview\\HEIC
- OC\\Preview\\JPEG
- OC\\Preview\\MarkDown
- OC\\Preview\\MP3
@ -1364,8 +1405,17 @@ Defaults to ``none``
'host' => 'localhost', // can also be a unix domain socket: '/tmp/redis.sock'
'port' => 6379,
'timeout' => 0.0,
'read_timeout' => 0.0,
'user' => '', // Optional, if not defined no password will be used.
'password' => '', // Optional, if not defined no password will be used.
'dbindex' => 0, // Optional, if undefined SELECT will not run and will use Redis Server's default DB Index.
// If redis in-transit encryption is enabled, provide certificates
// SSL context https://www.php.net/manual/en/context.ssl.php
'ssl_context' => [
'local_cert' => '/certs/redis.crt',
'local_pk' => '/certs/redis.key',
'cafile' => '/certs/ca.crt'
]
],
Connection details for redis to use for memory caching in a single server configuration.
@ -1374,6 +1424,9 @@ For enhanced security it is recommended to configure Redis
to require a password. See http://redis.io/topics/security
for more information.
We also support redis SSL/TLS encryption as of version 6.
See https://redis.io/topics/encryption for more information.
::
'redis.cluster' => [
@ -1384,7 +1437,15 @@ for more information.
'timeout' => 0.0,
'read_timeout' => 0.0,
'failover_mode' => \RedisCluster::FAILOVER_ERROR,
'user' => '', // Optional, if not defined no password will be used.
'password' => '', // Optional, if not defined no password will be used.
// If redis in-transit encryption is enabled, provide certificates
// SSL context https://www.php.net/manual/en/context.ssl.php
'ssl_context' => [
'local_cert' => '/certs/redis.crt',
'local_pk' => '/certs/redis.key',
'cafile' => '/certs/ca.crt'
]
],
Connection details for a Redis Cluster
@ -1415,8 +1476,8 @@ https://github.com/phpredis/phpredis/commit/c5994f2a42b8a348af92d3acb4edff1328ad
'memcached_servers' => [
// hostname, port and optional weight. Also see:
// http://www.php.net/manual/en/memcached.addservers.php
// http://www.php.net/manual/en/memcached.addserver.php
// https://www.php.net/manual/en/memcached.addservers.php
// https://www.php.net/manual/en/memcached.addserver.php
['localhost', 11211],
//array('other.host.local', 11211),
],
@ -1587,10 +1648,17 @@ Defaults to ``\OC\Share20\ProviderFactory``
::
'sharing.maxAutocompleteResults' => 0,
'sharing.maxAutocompleteResults' => 25,
Define max number of results returned by the user search for auto-completion
Default is unlimited (value set to 0).
Define max number of results returned by the search for auto-completion of
users, groups, etc. The value must not be lower than 0 (for unlimited).
If more, different sources are requested (e.g. different user backends; or
both users and groups), the value is applied per source and might not be
truncated after collecting the results. I.e. more results can appear than
configured here.
Default is 25.
::
@ -1613,12 +1681,28 @@ Users can change this for their account in their personal sharing settings
Set to true to enforce that internal shares need to be accepted
::
'sharing.allow_custom_share_folder' => true,
Set to false to prevent users from setting a custom share_folder
::
'sharing.enable_share_mail' => true,
Set to false to stop sending a mail when users receive a share
::
'transferIncomingShares' => false,
Set to true to always transfer incoming shares by default
when running "occ files:transfer-ownership".
Defaults to false, so incoming shares are not transferred if not specifically requested
by a command line argument.
All other configuration options
-------------------------------
@ -1627,12 +1711,22 @@ All other configuration options
'dbdriveroptions' => [
PDO::MYSQL_ATTR_SSL_CA => '/file/path/to/ca_cert.pem',
PDO::MYSQL_ATTR_SSL_KEY => '/file/path/to/mysql-client-key.pem',
PDO::MYSQL_ATTR_SSL_CERT => '/file/path/to/mysql-client-cert.pem',
PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => false,
PDO::MYSQL_ATTR_INIT_COMMAND => 'SET wait_timeout = 28800'
],
Additional driver options for the database connection, eg. to enable SSL
encryption in MySQL or specify a custom wait timeout on a cheap hoster.
When setting up TLS/SSL for encrypting the connections, you need to ensure that
the passed keys and certificates are readable by the PHP process. In addition
PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT might need to be set to false, if the
database servers certificates CN does not match with the hostname used to connect.
The standard behavior here is different from the MySQL/MariaDB CLI client, which
does not verify the server cert except --ssl-verify-server-cert is passed manually.
::
'sqlite.journal_mode' => 'DELETE',
@ -1674,6 +1768,25 @@ https://mariadb.com/kb/en/mariadb/xtradbinnodb-server-system-variables/#innodb_l
http://www.tocker.ca/2013/10/31/benchmarking-innodb-page-compression-performance.html
http://mechanics.flite.com/blog/2014/07/29/using-innodb-large-prefix-to-avoid-error-1071/
::
'mysql.collation' => null,
For search queries in the database, a default collation – depending on the
character set – is chosen. In some cases a different behaviour is desired,
for instances when a accent sensitive search is desired.
MariaDB and MySQL have an overlap in available collations, but also
incompatible ones, also depending on the version of the database server.
This option allows to override the automatic choice. Example:
'mysql.collation' => 'utf8mb4_0900_as_ci',
This setting has no effect on setup or creating tables. In those cases
always utf8[mb4]_bin is being used. This setting is only taken into
consideration in SQL queries that utilize LIKE comparison operators.
::
'supportedDatabases' => [
@ -1702,7 +1815,7 @@ Defaults to the following databases:
Override where Nextcloud stores temporary files. Useful in situations where
the system temporary directory is on a limited space ramdisk or is otherwise
restricted, or if external storages which do not support streaming are in
restricted, or if external storage which do not support streaming are in
use.
The Web server user must have write access to this directory.
@ -1726,33 +1839,33 @@ be found at: https://www.php.net/manual/en/function.password-hash.php
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
::
'hashingThreads' => PASSWORD_ARGON2_DEFAULT_THREADS,
The number of CPU threads to be used by the algorithm for computing a hash.
The value must be an integer, and the minimum value is 1. Rationally it does
not help to provide a number higher than the available threads on the machine.
Values that undershoot the minimum will be ignored in favor of the minimum.
::
'hashingMemoryCost' => PASSWORD_ARGON2_DEFAULT_MEMORY_COST,
The allowed maximum memory in KiB to be used by the algorithm for computing a
hash. The smallest possible value is 8. Values that undershoot the minimum
will be ignored in favor of the default.
The memory in KiB to be used by the algorithm for computing a hash. The value
must be an integer, and the minimum value is 8 times the number of CPU threads.
Values that undershoot the minimum will be ignored in favor of the minimum.
::
'hashingTimeCost' => PASSWORD_ARGON2_DEFAULT_TIME_COST,
The allowed maximum time in seconds that can be used by the algorithm for
computing a hash. The value must be an integer, and the minimum value is 1.
The number of iterations that are used by the algorithm for computing a hash.
Values that undershoot the minimum will be ignored in favor of the default.
::
'hashingThreads' => PASSWORD_ARGON2_DEFAULT_THREADS,
The allowed number of CPU threads that can be used by the algorithm for
computing a hash. The value must be an integer, and the minimum value is 1.
Rationally it does not help to provide a number higher than the available
threads on the machine. Values that undershoot the minimum will be ignored
in favor of the default.
The value must be an integer, and the minimum value is 1. Values that
undershoot the minimum will be ignored in favor of the minimum.
::
@ -1794,10 +1907,15 @@ Defaults to the theming app which is shipped since Nextcloud 9
::
'cipher' => 'AES-256-CFB',
'cipher' => 'AES-256-CTR',
The default cipher for encrypting files. Currently AES-128-CFB and
AES-256-CFB are supported.
The default cipher for encrypting files. Currently supported are:
- AES-256-CTR
- AES-128-CTR
- AES-256-CFB
- AES-128-CFB
Defaults to ``AES-256-CTR``
::
@ -1814,6 +1932,17 @@ clients or other unexpected results.
Defaults to ``2.0.0``
::
'localstorage.allowsymlinks' => false,
Option to allow local storage to contain symlinks.
WARNING: Not recommended. This would make it possible for Nextcloud to access
files outside the data directory and could be considered a security risk.
Defaults to ``false``
::
'quota_include_external_storage' => false,
@ -1841,7 +1970,7 @@ Defaults to ``1800`` (seconds)
Specifies how often the local filesystem (the Nextcloud data/ directory, and
NFS mounts in data/) is checked for changes made outside Nextcloud. This
does not apply to external storages.
does not apply to external storage.
0 -> Never check the filesystem for outside changes, provides a performance
increase when it's certain that no changes are made directly to the

2
admin_manual/configuration_server/email_configuration.rst
View File

@ -43,6 +43,8 @@ connect Nextcloud to a remote SMTP server:
* Login credentials (if required)
.. note:: The ``overwrite.cli.url`` parameter from ``config.php`` will be used for the SMTP EHLO.
.. figure:: ../images/smtp-config-smtp.png
Your changes are saved immediately, and you can click the Send Email button to

BIN
admin_manual/configuration_server/images/admin-right.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.9 KiB

1
admin_manual/configuration_server/index.rst
View File

@ -21,5 +21,6 @@ Nextcloud configuration
automatic_configuration
theming
oauth2
admin_delegation_configuration
.. Intentional disabled antivirus_configuration

6
admin_manual/configuration_server/language_configuration.rst
View File

@ -10,7 +10,7 @@ If this does not work properly or you want to make sure that Nextcloud always
starts with a given language, you can set a **default_language** parameter in the
:file:`config/config.php`.
.. note:: The default_language paramenter is only used, when the browser does not
.. note:: The default_language parameter is only used, when the browser does not
send any language, and the user hasn't configured own language preferences.
::
@ -40,13 +40,13 @@ this value can be set to ``true`` instead of a language code.
Default locale
--------------
The locale is used to define how dates and other formats are displayed. Nextcloud
should automatically pick an appropriated locale based on your current language.
should automatically pick an appropriate locale based on your current language.
Users can modify their locale inside their settings panel.
If that does not work properly or if you want to make sure that Nextcloud always
starts with a given locale, you can set a **default_locale** parameter in the
:file:`config/config.php`.
.. note:: The default_locale paramenter is only used when the user hasn't configured
.. note:: The default_locale parameter is only used when the user hasn't configured
own locale preferences.
::

59
admin_manual/configuration_server/logging_configuration.rst
View File

@ -72,6 +72,63 @@ All log information will be sent to Systemd journal. Requires `php-systemd <http
"log_type" => "systemd",
Log fields explained
--------------------
Example log entries
~~~~~~~~~~~~~~~~~~~
::
{
"reqId":"TBsuA2uE86DiOD0S8f9j",
"level":1,
"time":"April 13, 2021 16:55:37",
"remoteAddr":"192.168.56.1",
"user":"admin",
"app":"admin_audit",
"method":"GET",
"url":"/ocs/v1.php/cloud/users?disabled",
"message":"Login successful: \"admin\"",
"userAgent":"curl/7.68.0",
"version":"21.0.1.1"
}
{
"reqId":"ByeDVLuwkXKMfLpBgvxC",
"level":2,
"time":"April 14, 2021 09:03:29",
"remoteAddr":"192.168.56.1",
"user":"--",
"app":"no app in context",
"method":"POST",
"url":"/login",
"message":"Login failed: asdf (Remote IP: 192.168.56.1)",
"userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.114 Safari/537.36",
"version":"21.0.1.1"
}
Log field breakdown
~~~~~~~~~~~~~~~~~~~
* **0**: DEBUG: All activity; the most detailed logging.
* **reqId** (request id): any log lines related to a single request have the same value
* **level**: logged incident's level, always 1 in audit.log
* **time**: date and time (format and timezone can be configured in config.php)
* **remoteAddr**: the IP address of the user (if applicable – empty for occ commands)
* **user**: acting user's id (if applicable)
* **app**: affected app (always admin_audit in audit.log)
* **method**: HTTP method, for example GET, POST, PROPFIND, etc. – empty on occ calls
* **url**: request path (if applicable – empty on occ calls)
* **message**: event information message
* **userAgent**: user agent (if applicable – empty on occ calls)
* **exception**: Full exception with trace (if applicable)
* **data** additional structured data (if applicable)
* **version**: Nextcloud version at the time of request
Empty value are written as two dashes: "--".
Admin audit log
---------------
@ -92,4 +149,4 @@ If required, the name and path of the audit log file can be customized by using
Find detailed documentation on auditable events for enterprises in our `customer portal <https://portal.nextcloud.com/article/using-the-audit-log-44.html>`_.
.. _PHP date function: http://www.php.net/manual/en/function.date.php
.. _PHP date function: http://www.php.net/manual/en/function.date.php

642
admin_manual/configuration_server/occ_command.rst
View File

File diff suppressed because it is too large Load Diff

34
admin_manual/configuration_server/reverse_proxy_configuration.rst
View File

@ -21,7 +21,6 @@ Set the :file:`trusted_proxies` parameter as an array of:
* IPv4 addresses,
* IPv4 ranges in CIDR notation
* IPv6 addresses
* host to resolve
to define the servers Nextcloud should trust as proxies. This parameter
provides protection against client spoofing, and you should secure those
@ -70,13 +69,23 @@ Thanks to `@ffried <https://github.com/ffried>`_ for apache2 example.
Traefik 1
^^^^^^^^^
Using docker tags:
::
traefik.frontend.redirect.permanent: 'true'
traefik.frontend.redirect.regex: https://(.*)/.well-known/(card|cal)dav
traefik.frontend.redirect.replacement: https://$$1/remote.php/dav/
traefik.frontend.redirect.replacement: https://$1/remote.php/dav/
Thanks to `@pauvos <https://github.com/pauvos>`_ for traefik example.
Using traefik.toml:
::
[frontends.frontend1.redirect]
regex = "https://(.*)/.well-known/(card|cal)dav"
replacement = "https://$1/remote.php/dav/
permanent = true
Thanks to `@pauvos <https://github.com/pauvos>`_ and `@mrtumnus <https://github.com/mrtumnus>`_ for traefik examples.
Traefik 2
^^^^^^^^^
@ -107,6 +116,25 @@ NGINX
return 301 $scheme://$host/remote.php/dav;
}
or
::
rewrite ^/\.well-known/carddav https://$server_name/remote.php/dav/ redirect;
rewrite ^/\.well-known/caldav https://$server_name/remote.php/dav/ redirect;
Caddy
^^^^^
::
subdomain.example.com {
rewrite /.well-known/carddav /remote.php/dav
rewrite /.well-known/caldav /remote.php/dav
reverse_proxy {$NEXTCLOUD_HOST:localhost}
}
Example
-------

88
admin_manual/configuration_user/instruction_set_for_users.rst
View File

@ -5,7 +5,7 @@ Instruction set for users
Add a new user
--------------
Create a new user on the Nextcloud server. Authentication is done by sending a
Create a new user on the Nextcloud server. Authentication is done by sending a
basic HTTP authentication header.
**Syntax: ocs/v1.php/cloud/users**
@ -61,7 +61,7 @@ XML output
Search/get users
----------------
Retrieves a list of users from the Nextcloud server. Authentication is done by
Retrieves a list of users from the Nextcloud server. Authentication is done by
sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users**
@ -104,7 +104,7 @@ XML output
Get data of a single user
-------------------------
Retrieves information about a single user. Authentication is done by sending a
Retrieves information about a single user. Authentication is done by sending a
Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}**
@ -155,9 +155,10 @@ XML output
Edit data of a single user
--------------------------
Edits attributes related to a user. Users are able to edit email, displayname
and password; admins can also edit the quota value. Authentication is done by
sending a Basic HTTP Authorization header.
Edits attributes related to a user. Users are able to edit email, displayname
and password; admins can also edit the quota value. Further restrictions may apply,
check the `List of editable data fields`_ endpoint. Authentication
is done by sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}**
@ -196,7 +197,7 @@ Examples
$ curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -d key="quota" -d value="100MB"
* Updates the quota for the user ``Frank``
XML output
^^^^^^^^^^
@ -211,6 +212,55 @@ XML output
<data/>
</ocs>
.. _editable_field_list:
List of editable data fields
----------------------------
Edits attributes related to a user. Users are able to edit email, displayname
and password; admins can also edit the quota value. Authentication is done by
sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/user/fields**
* HTTP method: GET
Status codes:
* 100 - successful
Examples
^^^^^^^^
::
$ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/user/fields
* Gets the list of fields
XML output
^^^^^^^^^^
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message>OK</message>
</meta>
<data>
<element>displayname</element>
<element>email</element>
<element>phone</element>
<element>address</element>
<element>website</element>
<element>twitter</element>
</data>
</ocs>
Disable a user
--------------
@ -292,7 +342,7 @@ XML output
Delete a user
-------------
Deletes a user from the Nextcloud server. Authentication is done by sending a
Deletes a user from the Nextcloud server. Authentication is done by sending a
Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}**
@ -330,7 +380,7 @@ XML output
Get user's groups
-----------------
Retrieves a list of groups the specified user is a member of. Authentication is
Retrieves a list of groups the specified user is a member of. Authentication is
done by sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}/groups**
@ -372,7 +422,7 @@ XML output
Add user to group
-----------------
Adds the specified user to the specified group. Authentication is done by
Adds the specified user to the specified group. Authentication is done by
sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}/groups**
@ -415,7 +465,7 @@ XML output
Remove user from group
----------------------
Removes the specified user from the specified group. Authentication is done by
Removes the specified user from the specified group. Authentication is done by
sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}/groups**
@ -454,17 +504,17 @@ XML output
</meta>
<data/>
</ocs>
Promote user to subadmin
------------------------
Makes a user the subadmin of a group. Authentication is done by sending a Basic
Makes a user the subadmin of a group. Authentication is done by sending a Basic
HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}/subadmins**
* HTTP method: POST
* POST argument: groupid, string - the group of which to make the user a
* POST argument: groupid, string - the group of which to make the user a
subadmin
Status codes:
@ -500,13 +550,13 @@ XML output
Demote user from subadmin
-------------------------
Removes the subadmin rights for the user specified from the group specified.
Removes the subadmin rights for the user specified from the group specified.
Authentication is done by sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}/subadmins**
* HTTP method: DELETE
* DELETE argument: groupid, string - the group from which to remove the user's
* DELETE argument: groupid, string - the group from which to remove the user's
subadmin rights
Status codes:
@ -538,11 +588,11 @@ XML output
</meta>
<data/>
</ocs>
Get user's subadmin groups
--------------------------
Returns the groups in which the user is a subadmin. Authentication is done by
Returns the groups in which the user is a subadmin. Authentication is done by
sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}/subadmins**
@ -579,7 +629,7 @@ XML output
<data>
<element>testgroup</element>
</data>
</ocs>
</ocs>
Resend the welcome email
------------------------

1
admin_manual/configuration_user/user_auth_ldap.rst
View File

@ -424,6 +424,7 @@ Default password policy DN:
| *cn=default,ou=policies,dc=my-company,dc=com*
.. _LDAP_Special_Attributes:
Special attributes
^^^^^^^^^^^^^^^^^^

5
admin_manual/configuration_user/user_password_policy.rst
View File

@ -6,7 +6,10 @@ A password policy is a set of rules designed to enhance computer security by enc
In the security-section of your administrator-settings you can configure
* a minimal length of a password. Default is 10 characters.
* a minimal length of a password. Default is 8 characters.
* a password history
* a password expiration period
* a lockout policy
* to forbid common passwords like 'password' or 'login'.
* to enforce upper and lower case characters
* to enforce numeric characters

7
admin_manual/gdpr/index.rst
View File

@ -1,9 +1,8 @@
====
GDPR
====
===============
GDPR-compliance
===============
.. toctree::
:maxdepth: 2
cookies

27
admin_manual/groupware/calendar.rst
View File

@ -1,6 +1,6 @@
========
Calendar
========
=================
Calendar / CalDAV
=================
Invitations
-----------
@ -16,7 +16,7 @@ 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:`../configuration_server/occ_command` section DAV commands.
Reminder notifications
----------------------
@ -30,9 +30,9 @@ Make sure the "Send notifications for events" and the "Enable notifications for
Background jobs
~~~~~~~~~~~~~~~
As this can be a expensive task, depending on the number of events, reminders and event sharees and attendees that also needs to happen
often enough so that the notifications are send on time, you can use a dedicated occ command that should be run
more often than the standard cron system::
Running background jobs can be an expensive task when there are a large number of events, reminders, event sharees and attendees. However, this needs to happen
often enough so that the notifications are sent on time. To accomplish this you should use a dedicated ``occ`` command that runs
more often than the standard ``cron`` system::
# crontab -u www-data -e
*/5 * * * * php -f /var/www/nextcloud/occ dav:send-event-reminders
@ -43,22 +43,24 @@ You'll also need to change the sending mode from ``background-job`` to ``occ``::
php occ config:app:set dav sendEventRemindersMode --value occ
If you don't use this dedicated command, the reminders will just be send as soon as possible when the background jobs run.
If you don't use this dedicated command, the reminders will just be sent as soon as possible when the background jobs run.
FreeBusy
--------
When logged-in, Nextcloud can return FreeBusy information for all users of the instance, to know when they are available so that you can schedule an event at the right time.
If you don't wish for users to have this possibility, you can disable FreeBusy for the whole instance with the following setting::
If you don't wish for users to have this capability, you can disable FreeBusy for the whole instance with the following setting::
php occ config:app:set dav disableFreeBusy --value yes
Subscriptions
----------------------
-------------
Refresh rate
~~~~~~~~~~~~
Calendar subscriptions are cached on server and refreshed periodically. The default refresh rate is of one week, unless the subscription itself tells otherwise.
Calendar subscriptions are cached on server and refreshed periodically.
The default refresh rate is one week, unless the subscription itself tells otherwise.
To set up a different default refresh rate, change the ``calendarSubscriptionRefreshRate`` option::
@ -69,6 +71,7 @@ Where the value is a `DateInterval <https://www.php.net/manual/dateinterval.cons
Allow subscriptions on local network
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Because of security issues, Nextcloud forbids subscriptions from local network hosts. If you need to allow this, change the following parameter to::
Because of security issues, Nextcloud forbids subscriptions from local network hosts.
If you need to allow this, change the following parameter to::
php occ config:app:set dav webcalAllowLocalAccess --value yes

BIN
admin_manual/images/user_password_policy_configuration_app.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 25 KiB

10
admin_manual/index.rst
View File

@ -6,7 +6,7 @@ Welcome to the Nextcloud Server Administration Guide. This guide describes
administration tasks for Nextcloud, the flexible open source file synchronization
and sharing solution. Nextcloud includes the Nextcloud server, which runs on
Linux, client applications for Microsoft Windows, macOS and Linux, and mobile
clients for the Android and Apple iOS operating systems.
clients for the Android and iOS operating systems.
Current editions of Nextcloud manuals are always available online at
`docs.nextcloud.com <https://docs.nextcloud.com/>`_.
@ -20,11 +20,11 @@ Videos and blogs
----------------
See the `official Nextcloud channel
<https://www.youtube.com/channel/UCQjN5Fs5QSz1loJqLb5bkew>`_
<https://www.youtube.com/c/Nextcloud>`_
on YouTube for tutorials, overviews, and conference videos.
Visit `Nextcloud Planet <https://nextcloud.com/news/>`_ for news and developer
blogs.
Visit `our blog <https://nextcloud.com/news/>`_ for latest news and to learn more
about what is going on in and around Nextcloud.
Target audience
---------------
@ -38,6 +38,6 @@ respective manuals:
* `Nextcloud Desktop Client`_
.. _`Nextcloud User Manual`: https://docs.nextcloud.com/server/latest/user_manual/en/
.. _`Nextcloud Desktop Client`: https://docs.nextcloud.com/desktop/2.6/
.. _`Nextcloud Desktop Client`: https://docs.nextcloud.com/desktop/3.1/
.. TODO ON RELEASE: Update version number above on release

4
admin_manual/installation/apps_supported.rst
View File

@ -13,7 +13,7 @@ Nextcloud Files
* `Activity <https://github.com/nextcloud/activity>`_
* `Auditing / Logging <https://github.com/nextcloud/server/tree/master/apps/admin_audit>`_
* `Antivirus for files <https://github.com/nextcloud/files_antivirus>`_
* `AppOrder <https://github.com/juliushaertl/apporder>`_
* `Brute-force settings <https://github.com/nextcloud/bruteforcesettings>`_
* `Circles <https://github.com/nextcloud/circles>`_
* `Collaborative Tags <https://github.com/nextcloud/server/tree/master/apps/systemtags>`_
* `Comments <https://github.com/nextcloud/server/tree/master/apps/comments>`_
@ -91,4 +91,4 @@ Global Scale
------------
* `Global Site Selector <https://github.com/nextcloud/globalsiteselector>`_
* `Lookup Server Connector <https://github.com/nextcloud/server/tree/master/apps/lookup_server_connector>`_
* `Lookup Server Connector <https://github.com/nextcloud/server/tree/master/apps/lookup_server_connector>`_

236
admin_manual/installation/example_openbsd.rst Normal file
View File

@ -0,0 +1,236 @@
.. _openbsd_installation_label:
Example installation on OpenBSD
===============================
.. warning::
Nextcloud does not have official OpenBSD or other BSDs support
In this install tutorial we will be deploying Nextcloud on a minimal OpenBSD with our own httpd(8), PHP, PostgreSQL and redis (for -stable or -current are the same steps).
From a base installed OpenBSD system you can just do::
# pkg_add nextcloud
The extra packages::
# pkg_add postgresql-server redis pecl74-redis php-pdo_pgsql
This will take care of your dependencies and give you the options to choose which PHP version do you want.
HTTPD(8)
--------
Create a virtualhost in ``/etc/httpd.conf`` and add the following content to it::
server "domain.tld" {
listen on egress tls port 443
hsts max-age 15768000
tls {
certificate "/etc/ssl/domain.tld_fullchain.pem"
key "/etc/ssl/private/domain.tld_private.pem"
}
# Set max upload size to 513M (in bytes)
connection max request body 537919488
connection max requests 1000
connection request timeout 3600
connection timeout 3600
block drop
# Ensure that no '*.php*' files can be fetched from these directories
location "/nextcloud/config/*" {
block drop
}
location "/nextcloud/data/*" {
block drop
}
# Note that this matches "*.php*" anywhere in the request path.
location "/nextcloud/*.php*" {
root "/nextcloud"
request strip 1
fastcgi socket "/run/php-fpm.sock"
pass
}
location "/nextcloud/apps/*" {
root "/nextcloud"
request strip 1
pass
}
location "/nextcloud/core/*" {
root "/nextcloud"
request strip 1
pass
}
location "/nextcloud" {
block return 301 "$DOCUMENT_URI/index.php"
}
location "/nextcloud/" {
block return 301 "$DOCUMENT_URI/index.php"
}
location "/.well-known/carddav" {
block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
}
location "/.well-known/caldav" {
block return 301 "https://$SERVER_NAME/nextcloud/remote.php/dav"
}
location "/.well-known/webfinger" {
block return 301 "https://$SERVER_NAME/nextcloud/public.php?service=webfinger"
}
location match "/nextcloud/oc[ms]%-provider/*" {
directory index index.php
pass
}
}
Make sure that httpd(8) is enabled and started::
# rcctl enable httpd
# rcctl start httpd
PHP
---
Assuming that you are on OpenBSD -current (or >= 6.8-stable) you could use PHP 7.4 so I will keep this version, but the concept is the same for other version.
The PHP packages will be available since you installed Nextcloud with pkg_add, so you just need to adjust a bit your php.ini.
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
opcache.revalidate_freq=1
opcache.save_comments=1
And increase some limits::
post_max_size = 513M
upload_max_filesize = 513M
We can enable the PHP modules with::
# cd /etc/php-7.4.sample
# for i in *; do ln -sf ../php-7.4.sample/$i ../php-7.4/; done
And then we just enable and start PHP::
# rcctl enable php74_fpm
# rcctl start php74_fpm
Database
--------
As mentioned, we will be using PostgreSQL as our database, and we already installed it, now we need to initialised::
$ su - _postgresql
$ mkdir /var/postgresql/data
$ initdb -D /var/postgresql/data -U postgres -A md5 -E UTF8 -W
...
Enter new superuser password: PASSWORD
Enter it again: PASSWORD
...
Success. You can now start the database server using:
pg_ctl -D /var/postgresql/data -l logfile start
$ pg_ctl -D /var/postgresql/data -l logfile start
server starting
$ exit
We need to check, enable and start postgres::
# rcctl check postgresql
# rcctl enable postgresql
# rcctl start postgresql
You can follow the README on ``/usr/local/share/doc/pkg-readmes/postgresql-server`` to create users and permission.
Redis
-----
We installed redis before, we need to enable it and start it and also add it to the Nextcloud conf::
# rcctl enable redis
# rcctl start redis
# mg /var/www/nextcloud/config/config.php
...
'memcache.local' => '\OC\Memcache\Redis',
'redis' => array(
'host' => 'localhost',
'port' => 6379,
'timeout' => 0.0,
),
...
Cron job
--------
We need to add the Nextcloud cron job to get some tasks done by adding this entry on your cronjob::
*/5 * * * * /usr/bin/ftp -Vo - https://domain.tld/cron.php >/dev/null
Chroot
------
Since in OpenBSD httpd(8) works with a chroot(8) by default, we need to be sure that we have the relevant files into the /var/www jail::
# mkdir -p /var/www/etc/ssl
# install -m 444 -o root -g bin /etc/ssl/cert.pem /etc/ssl/openssl.cnf \
/var/www/etc/ssl/
# cp /etc/resolv.conf /var/www/etc
Nextcloud final steps
---------------------
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)::
https://domain.tld
Now you just need to follow the steps and put in place your DB name, usr and passwords.
Keep in mind that the upgrades for Nextcloud you can do it by running on -current::
# pkg_add -u -Dsnap
And on -stable::
# pkg_add -u
Then you just follow the steps from your browser.
NOTE
----
Remember always to read all the READMES from the OpenBSD packages on::
/usr/local/share/doc/pkg-readmes/
All this information and more is available for you there.

7
admin_manual/installation/example_ubuntu.rst
View File

@ -64,7 +64,7 @@ Now download the archive of the latest Nextcloud version:
* Now you can extract the archive contents. Run the appropriate unpacking
command for your archive type::
tar -xjfv nextcloud-x.y.z.tar.bz2
tar -xjvf nextcloud-x.y.z.tar.bz2
unzip nextcloud-x.y.z.zip
* This unpacks to a single ``nextcloud`` directory. Copy the Nextcloud directory
@ -80,3 +80,8 @@ Now download the archive of the latest Nextcloud version:
On other HTTP servers it is recommended to install Nextcloud outside of the
document root.
Next steps
----------
After installing the prerequisites and extracting the nextcloud directory, you should follow the instructions for Apache configuration at :ref:`apache_configuration_label`. Once Apache is installed, you can optionally follow the :doc:`source_installation` guide from :ref:`pretty_urls_label` until :ref:`other_HTTP_servers_label`

1
admin_manual/installation/index.rst
View File

@ -18,3 +18,4 @@ Installation and server configuration
example_ubuntu
example_centos
example_openbsd

158
admin_manual/installation/nginx-root.conf.sample Normal file
View File

@ -0,0 +1,158 @@
upstream php-handler {
server 127.0.0.1:9000;
#server unix:/var/run/php/php7.4-fpm.sock;
}
server {
listen 80;
listen [::]:80;
server_name cloud.example.com;
# Enforce HTTPS
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name cloud.example.com;
# Use Mozilla's guidelines for SSL/TLS settings
# https://mozilla.github.io/server-side-tls/ssl-config-generator/
ssl_certificate /etc/ssl/nginx/cloud.example.com.crt;
ssl_certificate_key /etc/ssl/nginx/cloud.example.com.key;
# HSTS settings
# WARNING: Only add the preload option once you read about
# the consequences in https://hstspreload.org/. This option
# will add the domain to a hardcoded list that is shipped
# in all major browsers and getting removed from this list
# could take several months.
#add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
# set max upload size
client_max_body_size 512M;
fastcgi_buffers 64 4K;
# Enable gzip but do not remove ETag headers
gzip on;
gzip_vary on;
gzip_comp_level 4;
gzip_min_length 256;
gzip_proxied expired no-cache no-store private no_last_modified no_etag auth;
gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy;
# Pagespeed is not supported by Nextcloud, so if your server is built
# with the `ngx_pagespeed` module, uncomment this line to disable it.
#pagespeed off;
# HTTP response headers borrowed from Nextcloud `.htaccess`
add_header Referrer-Policy "no-referrer" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Download-Options "noopen" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Permitted-Cross-Domain-Policies "none" always;
add_header X-Robots-Tag "none" always;
add_header X-XSS-Protection "1; mode=block" always;
# Remove X-Powered-By, which is an information leak
fastcgi_hide_header X-Powered-By;
# Path to the root of your installation
root /var/www/nextcloud;
# Specify how to handle directories -- specifying `/index.php$request_uri`
# here as the fallback means that Nginx always exhibits the desired behaviour
# when a client requests a path that corresponds to a directory that exists
# on the server. In particular, if that directory contains an index.php file,
# that file is correctly served; if it doesn't, then the request is passed to
# the front-end controller. This consistent behaviour means that we don't need
# to specify custom rules for certain paths (e.g. images and other assets,
# `/updater`, `/ocm-provider`, `/ocs-provider`), and thus
# `try_files $uri $uri/ /index.php$request_uri`
# always provides the desired behaviour.
index index.php index.html /index.php$request_uri;
# Rule borrowed from `.htaccess` to handle Microsoft DAV clients
location = / {
if ( $http_user_agent ~ ^DavClnt ) {
return 302 /remote.php/webdav/$is_args$args;
}
}
location = /robots.txt {
allow all;
log_not_found off;
access_log off;
}
# Make a regex exception for `/.well-known` so that clients can still
# access it despite the existence of the regex rule
# `location ~ /(\.|autotest|...)` which would otherwise handle requests
# for `/.well-known`.
location ^~ /.well-known {
# The rules in this block are an adaptation of the rules
# in `.htaccess` that concern `/.well-known`.
location = /.well-known/carddav { return 301 /remote.php/dav/; }
location = /.well-known/caldav { return 301 /remote.php/dav/; }
location /.well-known/acme-challenge { try_files $uri $uri/ =404; }
location /.well-known/pki-validation { try_files $uri $uri/ =404; }
# Let Nextcloud's API for `/.well-known` URIs handle all other
# requests by passing them to the front-end controller.
return 301 /index.php$request_uri;
}
# Rules borrowed from `.htaccess` to hide certain paths from clients
location ~ ^/(?:build|tests|config|lib|3rdparty|templates|data)(?:$|/) { return 404; }
location ~ ^/(?:\.|autotest|occ|issue|indie|db_|console) { return 404; }
# Ensure this block, which passes PHP files to the PHP process, is above the blocks
# which handle static assets (as seen below). If this block is not declared first,
# then Nginx will encounter an infinite rewriting loop when it prepends `/index.php`
# to the URI, resulting in a HTTP 500 error response.
location ~ \.php(?:$|/) {
# Required for legacy support
rewrite ^/(?!index|remote|public|cron|core\/ajax\/update|status|ocs\/v[12]|updater\/.+|oc[ms]-provider\/.+|.+\/richdocumentscode\/proxy) /index.php$request_uri;
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
set $path_info $fastcgi_path_info;
try_files $fastcgi_script_name =404;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $path_info;
fastcgi_param HTTPS on;
fastcgi_param modHeadersAvailable true; # Avoid sending the security headers twice
fastcgi_param front_controller_active true; # Enable pretty urls
fastcgi_pass php-handler;
fastcgi_intercept_errors on;
fastcgi_request_buffering off;
}
location ~ \.(?:css|js|svg|gif|png|jpg|ico)$ {
try_files $uri /index.php$request_uri;
expires 6M; # Cache-Control policy borrowed from `.htaccess`
access_log off; # Optional: Don't log access to assets
}
location ~ \.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
}
# Rule borrowed from `.htaccess`
location /remote {
return 301 /remote.php$request_uri;
}
location / {
try_files $uri $uri/ /index.php$request_uri;
}
}

158
admin_manual/installation/nginx-subdir.conf.sample Normal file
View File

@ -0,0 +1,158 @@
upstream php-handler {
server 127.0.0.1:9000;
#server unix:/var/run/php/php7.4-fpm.sock;
}
server {
listen 80;
listen [::]:80;
server_name cloud.example.com;
# Enforce HTTPS just for `/nextcloud`
location /nextcloud {
return 301 https://$server_name$request_uri;
}
}
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name cloud.example.com;
# Use Mozilla's guidelines for SSL/TLS settings
# https://mozilla.github.io/server-side-tls/ssl-config-generator/
ssl_certificate /etc/ssl/nginx/cloud.example.com.crt;
ssl_certificate_key /etc/ssl/nginx/cloud.example.com.key;
# HSTS settings
# WARNING: Only add the preload option once you read about
# the consequences in https://hstspreload.org/. This option
# will add the domain to a hardcoded list that is shipped
# in all major browsers and getting removed from this list
# could take several months.
#add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
# Path to the root of the domain
root /var/www;
location = /robots.txt {
allow all;
log_not_found off;
access_log off;
}
location ^~ /.well-known {
# The rules in this block are an adaptation of the rules
# in the Nextcloud `.htaccess` that concern `/.well-known`.
location = /.well-known/carddav { return 301 /nextcloud/remote.php/dav/; }
location = /.well-known/caldav { return 301 /nextcloud/remote.php/dav/; }
location /.well-known/acme-challenge { try_files $uri $uri/ =404; }
location /.well-known/pki-validation { try_files $uri $uri/ =404; }
# Let Nextcloud's API for `/.well-known` URIs handle all other
# requests by passing them to the front-end controller.
return 301 /nextcloud/index.php$request_uri;
}
location ^~ /nextcloud {
# set max upload size
client_max_body_size 512M;
fastcgi_buffers 64 4K;
# Enable gzip but do not remove ETag headers
gzip on;
gzip_vary on;
gzip_comp_level 4;
gzip_min_length 256;
gzip_proxied expired no-cache no-store private no_last_modified no_etag auth;
gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy;
# Pagespeed is not supported by Nextcloud, so if your server is built
# with the `ngx_pagespeed` module, uncomment this line to disable it.
#pagespeed off;
# HTTP response headers borrowed from Nextcloud `.htaccess`
add_header Referrer-Policy "no-referrer" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Download-Options "noopen" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Permitted-Cross-Domain-Policies "none" always;
add_header X-Robots-Tag "none" always;
add_header X-XSS-Protection "1; mode=block" always;
# Remove X-Powered-By, which is an information leak
fastcgi_hide_header X-Powered-By;
# Specify how to handle directories -- specifying `/nextcloud/index.php$request_uri`
# here as the fallback means that Nginx always exhibits the desired behaviour
# when a client requests a path that corresponds to a directory that exists
# on the server. In particular, if that directory contains an index.php file,
# that file is correctly served; if it doesn't, then the request is passed to
# the front-end controller. This consistent behaviour means that we don't need
# to specify custom rules for certain paths (e.g. images and other assets,
# `/updater`, `/ocm-provider`, `/ocs-provider`), and thus
# `try_files $uri $uri/ /nextcloud/index.php$request_uri`
# always provides the desired behaviour.
index index.php index.html /nextcloud/index.php$request_uri;
# Rule borrowed from `.htaccess` to handle Microsoft DAV clients
location = /nextcloud {
if ( $http_user_agent ~ ^DavClnt ) {
return 302 /nextcloud/remote.php/webdav/$is_args$args;
}
}
# Rules borrowed from `.htaccess` to hide certain paths from clients
location ~ ^/nextcloud/(?:build|tests|config|lib|3rdparty|templates|data)(?:$|/) { return 404; }
location ~ ^/nextcloud/(?:\.|autotest|occ|issue|indie|db_|console) { return 404; }
# Ensure this block, which passes PHP files to the PHP process, is above the blocks
# which handle static assets (as seen below). If this block is not declared first,
# then Nginx will encounter an infinite rewriting loop when it prepends
# `/nextcloud/index.php` to the URI, resulting in a HTTP 500 error response.
location ~ \.php(?:$|/) {
# Required for legacy support
rewrite ^/(?!index|remote|public|cron|core\/ajax\/update|status|ocs\/v[12]|updater\/.+|oc[ms]-provider\/.+|.+\/richdocumentscode\/proxy) /nextcloud/index.php$request_uri;
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
set $path_info $fastcgi_path_info;
try_files $fastcgi_script_name =404;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $path_info;
fastcgi_param HTTPS on;
fastcgi_param modHeadersAvailable true; # Avoid sending the security headers twice
fastcgi_param front_controller_active true; # Enable pretty urls
fastcgi_pass php-handler;
fastcgi_intercept_errors on;
fastcgi_request_buffering off;
}
location ~ \.(?:css|js|svg|gif|png|jpg|ico)$ {
try_files $uri /nextcloud/index.php$request_uri;
expires 6M; # Cache-Control policy borrowed from `.htaccess`
access_log off; # Optional: Don't log access to assets
}
location ~ \.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
}
# Rule borrowed from `.htaccess`
location /nextcloud/remote {
return 301 /nextcloud/remote.php$request_uri;
}
location /nextcloud {
try_files $uri $uri/ /nextcloud/index.php$request_uri;
}
}
}

328
admin_manual/installation/nginx.rst
View File

@ -1,10 +1,14 @@
===================
Nginx configuration
NGINX configuration
===================
This page covers example Nginx configurations to use with running a Nextcloud
server. These configurations examples were originally provided by
`@josh4trunks <https://github.com/josh4trunks>`_ and are community-maintained. (Thank you contributors!)
.. warning::
Please note that webservers 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 <https://github.com/josh4trunks>`_
and are exclusively community-maintained. (Thank you contributors!)
- You need to insert the following code into **your Nginx configuration file.**
- Adjust **server_name**, **root**, **ssl_certificate** and
@ -16,169 +20,17 @@ server. These configurations examples were originally provided by
- Some environments might need a ``cgi.fix_pathinfo`` set to ``1`` in their
``php.ini``.
Nextcloud in the webroot of nginx
Nextcloud in the webroot of NGINX
---------------------------------
The following configuration should be used when Nextcloud is placed in the
webroot of your nginx installation. In this example it is
``/var/www/nextcloud`` and it is accessed via ``http(s)://cloud.example.com/``
.. code-block:: nginx
.. literalinclude:: nginx-root.conf.sample
:language: nginx
upstream php-handler {
server 127.0.0.1:9000;
#server unix:/var/run/php/php7.4-fpm.sock;
}
server {
listen 80;
listen [::]:80;
server_name cloud.example.com;
# Enforce HTTPS
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name cloud.example.com;
# Use Mozilla's guidelines for SSL/TLS settings
# https://mozilla.github.io/server-side-tls/ssl-config-generator/
ssl_certificate /etc/ssl/nginx/cloud.example.com.crt;
ssl_certificate_key /etc/ssl/nginx/cloud.example.com.key;
# HSTS settings
# WARNING: Only add the preload option once you read about
# the consequences in https://hstspreload.org/. This option
# will add the domain to a hardcoded list that is shipped
# in all major browsers and getting removed from this list
# could take several months.
#add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
# set max upload size
client_max_body_size 512M;
fastcgi_buffers 64 4K;
# Enable gzip but do not remove ETag headers
gzip on;
gzip_vary on;
gzip_comp_level 4;
gzip_min_length 256;
gzip_proxied expired no-cache no-store private no_last_modified no_etag auth;
gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy;
# Pagespeed is not supported by Nextcloud, so if your server is built
# with the `ngx_pagespeed` module, uncomment this line to disable it.
#pagespeed off;
# HTTP response headers borrowed from Nextcloud `.htaccess`
add_header Referrer-Policy "no-referrer" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Download-Options "noopen" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Permitted-Cross-Domain-Policies "none" always;
add_header X-Robots-Tag "none" always;
add_header X-XSS-Protection "1; mode=block" always;
# Remove X-Powered-By, which is an information leak
fastcgi_hide_header X-Powered-By;
# Path to the root of your installation
root /var/www/nextcloud;
# Specify how to handle directories -- specifying `/index.php$request_uri`
# here as the fallback means that Nginx always exhibits the desired behaviour
# when a client requests a path that corresponds to a directory that exists
# on the server. In particular, if that directory contains an index.php file,
# that file is correctly served; if it doesn't, then the request is passed to
# the front-end controller. This consistent behaviour means that we don't need
# to specify custom rules for certain paths (e.g. images and other assets,
# `/updater`, `/ocm-provider`, `/ocs-provider`), and thus
# `try_files $uri $uri/ /index.php$request_uri`
# always provides the desired behaviour.
index index.php index.html /index.php$request_uri;
# Default Cache-Control policy
expires 1m;
# Rule borrowed from `.htaccess` to handle Microsoft DAV clients
location = / {
if ( $http_user_agent ~ ^DavClnt ) {
return 302 /remote.php/webdav/$is_args$args;
}
}
location = /robots.txt {
allow all;
log_not_found off;
access_log off;
}
# Make a regex exception for `/.well-known` so that clients can still
# access it despite the existence of the regex rule
# `location ~ /(\.|autotest|...)` which would otherwise handle requests
# for `/.well-known`.
location ^~ /.well-known {
# The following 6 rules are borrowed from `.htaccess`
rewrite ^/\.well-known/host-meta\.json /public.php?service=host-meta-json last;
rewrite ^/\.well-known/host-meta /public.php?service=host-meta last;
rewrite ^/\.well-known/webfinger /public.php?service=webfinger last;
rewrite ^/\.well-known/nodeinfo /public.php?service=nodeinfo last;
location = /.well-known/carddav { return 301 /remote.php/dav/; }
location = /.well-known/caldav { return 301 /remote.php/dav/; }
try_files $uri $uri/ =404;
}
# Rules borrowed from `.htaccess` to hide certain paths from clients
location ~ ^/(?:build|tests|config|lib|3rdparty|templates|data)(?:$|/) { return 404; }
location ~ ^/(?:\.|autotest|occ|issue|indie|db_|console) { return 404; }
# Ensure this block, which passes PHP files to the PHP process, is above the blocks
# which handle static assets (as seen below). If this block is not declared first,
# then Nginx will encounter an infinite rewriting loop when it prepends `/index.php`
# to the URI, resulting in a HTTP 500 error response.
location ~ \.php(?:$|/) {
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
set $path_info $fastcgi_path_info;
try_files $fastcgi_script_name =404;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $path_info;
fastcgi_param HTTPS on;
fastcgi_param modHeadersAvailable true; # Avoid sending the security headers twice
fastcgi_param front_controller_active true; # Enable pretty urls
fastcgi_pass php-handler;
fastcgi_intercept_errors on;
fastcgi_request_buffering off;
}
location ~ \.(?:css|js|svg|gif)$ {
try_files $uri /index.php$request_uri;
expires 6M; # Cache-Control policy borrowed from `.htaccess`
access_log off; # Optional: Don't log access to assets
}
location ~ \.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
}
location / {
try_files $uri $uri/ /index.php$request_uri;
}
}
Nextcloud in a subdir of the nginx webroot
Nextcloud in a subdir of the NGINX webroot
------------------------------------------
The following config should be used when Nextcloud is placed within a subdir of
@ -193,160 +45,8 @@ The configuration differs from the "Nextcloud in webroot" configuration above in
- The blocks that handle requests for paths outside of ``/nextcloud`` (i.e. ``/robots.txt`` and ``/.well-known``) are pulled out of the ``location ^~ /nextcloud`` block.
- The block which handles `/.well-known` doesn't need a regex exception, since the rule which prevents users from accessing hidden folders at the root of the Nextcloud installation no longer matches that path.
.. code-block:: nginx
upstream php-handler {
server 127.0.0.1:9000;
#server unix:/var/run/php/php7.4-fpm.sock;
}
server {
listen 80;
listen [::]:80;
server_name cloud.example.com;
# Enforce HTTPS just for `/nextcloud`
location /nextcloud {
return 301 https://$server_name$request_uri;
}
}
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name cloud.example.com;
# Use Mozilla's guidelines for SSL/TLS settings
# https://mozilla.github.io/server-side-tls/ssl-config-generator/
ssl_certificate /etc/ssl/nginx/cloud.example.com.crt;
ssl_certificate_key /etc/ssl/nginx/cloud.example.com.key;
# HSTS settings
# WARNING: Only add the preload option once you read about
# the consequences in https://hstspreload.org/. This option
# will add the domain to a hardcoded list that is shipped
# in all major browsers and getting removed from this list
# could take several months.
#add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
# Path to the root of the domain
root /var/www;
location = /robots.txt {
allow all;
log_not_found off;
access_log off;
}
location /.well-known {
# The following 6 rules are borrowed from `.htaccess`
rewrite ^/\.well-known/host-meta\.json /nextcloud/public.php?service=host-meta-json last;
rewrite ^/\.well-known/host-meta /nextcloud/public.php?service=host-meta last;
rewrite ^/\.well-known/webfinger /nextcloud/public.php?service=webfinger last;
rewrite ^/\.well-known/nodeinfo /nextcloud/public.php?service=nodeinfo last;
location = /.well-known/carddav { return 301 /nextcloud/remote.php/dav/; }
location = /.well-known/caldav { return 301 /nextcloud/remote.php/dav/; }
try_files $uri $uri/ =404;
}
location ^~ /nextcloud {
# set max upload size
client_max_body_size 512M;
fastcgi_buffers 64 4K;
# Enable gzip but do not remove ETag headers
gzip on;
gzip_vary on;
gzip_comp_level 4;
gzip_min_length 256;
gzip_proxied expired no-cache no-store private no_last_modified no_etag auth;
gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy;
# Pagespeed is not supported by Nextcloud, so if your server is built
# with the `ngx_pagespeed` module, uncomment this line to disable it.
#pagespeed off;
# HTTP response headers borrowed from Nextcloud `.htaccess`
add_header Referrer-Policy "no-referrer" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Download-Options "noopen" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Permitted-Cross-Domain-Policies "none" always;
add_header X-Robots-Tag "none" always;
add_header X-XSS-Protection "1; mode=block" always;
# Remove X-Powered-By, which is an information leak
fastcgi_hide_header X-Powered-By;
# Specify how to handle directories -- specifying `/nextcloud/index.php$request_uri`
# here as the fallback means that Nginx always exhibits the desired behaviour
# when a client requests a path that corresponds to a directory that exists
# on the server. In particular, if that directory contains an index.php file,
# that file is correctly served; if it doesn't, then the request is passed to
# the front-end controller. This consistent behaviour means that we don't need
# to specify custom rules for certain paths (e.g. images and other assets,
# `/updater`, `/ocm-provider`, `/ocs-provider`), and thus
# `try_files $uri $uri/ /nextcloud/index.php$request_uri`
# always provides the desired behaviour.
index index.php index.html /nextcloud/index.php$request_uri;
# Default Cache-Control policy
expires 1m;
# Rule borrowed from `.htaccess` to handle Microsoft DAV clients
location = /nextcloud {
if ( $http_user_agent ~ ^DavClnt ) {
return 302 /nextcloud/remote.php/webdav/$is_args$args;
}
}
# Rules borrowed from `.htaccess` to hide certain paths from clients
location ~ ^/nextcloud/(?:build|tests|config|lib|3rdparty|templates|data)(?:$|/) { return 404; }
location ~ ^/nextcloud/(?:\.|autotest|occ|issue|indie|db_|console) { return 404; }
# Ensure this block, which passes PHP files to the PHP process, is above the blocks
# which handle static assets (as seen below). If this block is not declared first,
# then Nginx will encounter an infinite rewriting loop when it prepends
# `/nextcloud/index.php` to the URI, resulting in a HTTP 500 error response.
location ~ \.php(?:$|/) {
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
set $path_info $fastcgi_path_info;
try_files $fastcgi_script_name =404;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $path_info;
fastcgi_param HTTPS on;
fastcgi_param modHeadersAvailable true; # Avoid sending the security headers twice
fastcgi_param front_controller_active true; # Enable pretty urls
fastcgi_pass php-handler;
fastcgi_intercept_errors on;
fastcgi_request_buffering off;
}
location ~ \.(?:css|js|svg|gif)$ {
try_files $uri /nextcloud/index.php$request_uri;
expires 6M; # Cache-Control policy borrowed from `.htaccess`
access_log off; # Optional: Don't log access to assets
}
location ~ \.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
}
location /nextcloud {
try_files $uri $uri/ /nextcloud/index.php$request_uri;
}
}
}
.. literalinclude:: nginx-subdir.conf.sample
:language: nginx
Tips and tricks
---------------

1
admin_manual/installation/selinux_configuration.rst
View File

@ -29,6 +29,7 @@ this execute the following commands as root after uninstalling Nextcloud::
semanage fcontext -d '/var/www/html/nextcloud/apps(/.*)?'
semanage fcontext -d '/var/www/html/nextcloud/.htaccess'
semanage fcontext -d '/var/www/html/nextcloud/.user.ini'
semanage fcontext -d '/var/www/html/nextcloud/3rdparty/aws/aws-sdk-php/src/data/logs(/.*)?'
restorecon -Rv '/var/www/html/nextcloud/'

119
admin_manual/installation/server_tuning.rst
View File

@ -11,14 +11,14 @@ benefits.
Reducing system load
--------------------
High system load will slow down Nextcloud and might also lead to other unwanted
side effects. To reduce load you should first identify the source of the problem.
High system load will slow down Nextcloud and might also lead to other unwanted
side effects. To reduce load you should first identify the source of the problem.
Tools such as htop, iotop, `netdata <https://my-netdata.io>`_ or
`glances <https://nicolargo.github.io/glances/>`_
will help to identify the process or the drive that slows down your system. First
you should make sure that you installed/assigned enough RAM. Swap usage should be
prevented by all means. If you run your database inside a VM, you should not
store it inside a VM image file. Better put it on a dedicated block device to
will help to identify the process or the drive that slows down your system. First
you should make sure that you installed/assigned enough RAM. Swap usage should be
prevented by all means. If you run your database inside a VM, you should not
store it inside a VM image file. Better put it on a dedicated block device to
reduce latency due to multiple abstraction layers.
.. _caching:
@ -26,15 +26,15 @@ reduce latency due to multiple abstraction layers.
Caching
-------
Caching improves performance by storing data, code, and other objects in memory.
Caching improves performance by storing data, code, and other objects in memory.
Memory cache configuration for the Nextcloud server must be installed and configured.
See :doc:`../configuration_server/caching_configuration`.
Using MariaDB/MySQL instead of SQLite
-------------------------------------
MySQL or MariaDB are preferred because of the `performance limitations of
SQLite with highly concurrent applications
MySQL or MariaDB are preferred because of the `performance limitations of
SQLite with highly concurrent applications
<https://www.sqlite.org/whentouse.html>`_, like Nextcloud.
See the section :doc:`../configuration_database/linux_database_configuration` for how to
@ -42,83 +42,62 @@ configure Nextcloud for MySQL or MariaDB. If your installation is already runnin
SQLite then it is possible to convert to MySQL or MariaDB using the steps provided
in :doc:`../configuration_database/db_conversion`.
In smaller installations you might not want to set up a separate cache. However
you can still tune your database. The following example is suited for a database
smaller than 1GB. MySQL will consume up to 1GB of RAM for caching. Please make
sure that your system has sufficient free RAM after the change, so that it does
not start to use your swap partition, when it receives a burst of requests. In
the given example your ``/etc/mysql/conf.d/mysql.cnf`` might contain the
following lines. (beware that this is the block for mysqld not mysql)
.. code:: ini
[mysqld]
innodb_buffer_pool_size=1G
innodb_io_capacity=4000
For more details and help tuning your database, check `this article at MariaDB <https://mariadb.com/kb/en/optimization-and-tuning/>`_.
Using Redis-based transactional file locking
--------------------------------------------
File locking is enabled by default, using the database locking backend. This
File locking is enabled by default, using the database locking backend. This
places a significant load on your database. See the section
:doc:`../configuration_files/files_locking_transactional` for how to
configure Nextcloud to use Redis-based Transactional File Locking.
SSL / encryption app
TLS / encryption app
--------------------
SSL (HTTPS) and file encryption/decryption can be offloaded to a processor's
AES-NI extension. This can both speed up these operations while lowering
processing overhead. This requires a processor with the `AES-NI instruction set
TLS (HTTPS) and file encryption/decryption can be offloaded to a processor's
AES-NI extension. This can both speed up these operations while lowering
processing overhead. This requires a processor with the `AES-NI instruction set
<https://wikipedia.org/wiki/AES_instruction_set>`_.
Here are some examples how to check if your CPU / environment supports the
Here are some examples how to check if your CPU / environment supports the
AES-NI extension:
* For each CPU core present: ``grep flags /proc/cpuinfo`` or as a summary for
all cores: ``grep -m 1 '^flags' /proc/cpuinfo`` If the result contains any
``aes``, the extension is present.
* For each CPU core present: ``grep flags /proc/cpuinfo`` or as a summary for
all cores: ``grep -m 1 '^flags' /proc/cpuinfo`` If the result contains any
``aes``, the extension is present.
* Search eg. on the Intel web if the processor used supports the extension
`Intel Processor Feature Filter
<https://ark.intel.com/MySearch.aspx?AESTech=true>`_ You may set a filter by
* Search eg. on the Intel web if the processor used supports the extension
`Intel Processor Feature Filter
<https://ark.intel.com/MySearch.aspx?AESTech=true>`_ You may set a filter by
``"AES New Instructions"`` to get a reduced result set.
* For versions of openssl >= 1.0.1, AES-NI does not work via an engine and
will not show up in the ``openssl engine`` command. It is active by default
on the supported hardware. You can check the openssl version via ``openssl
version -a``
* If your processor supports AES-NI but it does not show up eg via grep or
coreinfo, it is maybe disabled in the BIOS.
* If your environment runs virtualized, check the virtualization vendor for
support.
Enable HTTP2 for faster loading
-------------------------------
HTTP2 has `huge speed improvements <https://www.troyhunt.com/i-wanna-go-fast-https-massive-speed-advantage/>`_ over HTTP with multiple request. Most `browsers already support HTTP2 over SSL (HTTPS) <https://caniuse.com/#feat=http2>`_. So refer to your server manual for guides on how to use HTTP2.
* For versions of openssl >= 1.0.1, AES-NI does not work via an engine and
will not show up in the ``openssl engine`` command. It is active by default
on the supported hardware. You can check the openssl version via ``openssl
version -a``
* If your processor supports AES-NI but it does not show up eg via grep or
coreinfo, it is maybe disabled in the BIOS.
* If your environment runs virtualized, check the virtualization vendor for
support.
Enable HTTP/2 for faster loading
--------------------------------
HTTP/2 has `huge speed improvements <https://www.troyhunt.com/i-wanna-go-fast-https-massive-speed-advantage/>`_ over HTTP with multiple request. Most `browsers already support HTTP/2 over TLS (HTTPS) <https://caniuse.com/#feat=http2>`_. Refer to your web server manual for guides on how to enable HTTP/2.
Tune PHP-FPM
------------
If you are using a default installation of php-fpm you might have noticed
excessive load times on the web interface or even sync issues. This is due
to the fact that each simultaneous request of an element is handled by a
separate PHP-FPM process. So even on a small installation you should allow
more processes to run. For example on a machine with 4GB of RAM and 1GB of
MySQL cache following values in your ``www.conf`` file should work:
If you are using a default installation of PHP-FPM you might have noticed
excessive load times on the web interface or even sync issues. This is due
to the fact that each simultaneous request of an element is handled by a
separate PHP-FPM process. So even on a small installation you should allow
more processes to run in parallel to handle the requests.
.. code:: ini
pm = dynamic
pm.max_children = 120
pm.start_servers = 12
pm.min_spare_servers = 6
pm.max_spare_servers = 18
Depending on your current PHP version you should find this file e.g. under ``/etc/php/7.2/fpm/pool.d/www.conf``
`This link <https://spot13.com/pmcalculator/>`_ can help you calculate the good values for your system.
Enable PHP OPcache
------------------
@ -127,11 +106,11 @@ The `OPcache <https://php.net/manual/en/intro.opcache.php>`_ improves the perfor
.. code:: ini
opcache.enable=1
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.memory_consumption=128
opcache.save_comments=1
opcache.revalidate_freq=1
opcache.enable = 1
opcache.interned_strings_buffer = 8
opcache.max_accelerated_files = 10000
opcache.memory_consumption = 128
opcache.save_comments = 1
opcache.revalidate_freq = 1
For more details check out the `official documentation <https://php.net/manual/en/opcache.configuration.php>`_ or `this blog post about some recommended settings <https://www.scalingphpbook.com/blog/2014/02/14/best-zend-opcache-settings.html>`_.

29
admin_manual/installation/source_installation.rst
View File

@ -33,10 +33,11 @@ If you get a result, the module is present.
Required:
* PHP (7.2, 7.3 or 7.4)
* PHP (7.3 or 7.4)
* PHP module ctype
* PHP module curl
* PHP module dom
* PHP module filter (only on Mageia and FreeBSD)
* PHP module GD
* PHP module hash (only on FreeBSD)
* PHP module iconv
@ -56,7 +57,7 @@ Database connectors (pick the one for your database:)
* PHP module pdo_sqlite (>= 3, usually not recommended for performance reasons)
* PHP module pdo_mysql (MySQL/MariaDB)
* PHP module pdo_pgsql (requires PostgreSQL >= 9.0)
* PHP module pdo_pgsql (PostgreSQL)
*Recommended* packages:
@ -100,6 +101,10 @@ For command line processing (*optional*):
* PHP module pcntl (enables command interruption by pressing ``ctrl-c``)
For command line updater (*optional*):
* PHP module phar (upgrades Nextcloud by running ``sudo -u www-data php /var/www/nextcloud/updater/updater.phar``)
You don’t need the WebDAV module for your Web server (i.e. Apache’s
``mod_webdav``), as Nextcloud has a built-in WebDAV server of its own,
SabreDAV.
@ -295,18 +300,18 @@ ini file. This can be the case, for example, for the ``date.timezone`` setting.
**php.ini - used by the Web server:**
::
/etc/php/7.2/apache2/php.ini
/etc/php/7.4/apache2/php.ini
or
/etc/php/7.2/fpm/php.ini
/etc/php/7.4/fpm/php.ini
or ...
**php.ini - used by the php-cli and so by Nextcloud CRON jobs:**
::
/etc/php/7.2/cli/php.ini
/etc/php/7.4/cli/php.ini
.. note:: Path names have to be set in respect of the installed PHP
(>= 7.0, 7.1, 7.2 or 7.3) as applicable.
(>= 7.3 or 7.4) as applicable.
.. _php_fpm_tips_label:
@ -326,7 +331,7 @@ Here are some example root paths for these ini/config files:
+-----------------------+-----------------------+
| Debian/Ubuntu/Mint | CentOS/Red Hat/Fedora |
+-----------------------+-----------------------+
| ``/etc/php/7.2/fpm/`` | ``/etc/php-fpm.d/`` |
| ``/etc/php/7.4/fpm/`` | ``/etc/php-fpm.d/`` |
+-----------------------+-----------------------+
In both examples, the ini/config file is called ``www.conf``, and depending on
@ -353,7 +358,7 @@ you must add them.
Alternatively it is possible to use the environment variables of your system by modifying::
/etc/php/7.2/fpm/pool.d/www.conf
/etc/php/7.4/fpm/pool.d/www.conf
and uncommenting the line::
@ -372,7 +377,7 @@ The best way to check your settings is with :ref:`label-phpinfo`.
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 ``php5-fpm`` and your HTTP
``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**
@ -425,10 +430,10 @@ You can find all the available versions `here <https://shop.hanssonit.se/product
For complete instructions and downloads see:
- `Nextcloud VM (Github) <https://github.com/nextcloud/vm/>`_
- `Nextcloud VM (GitHub) <https://github.com/nextcloud/vm/>`_
- `Nextcloud VM (T&M Hansson IT) <https://www.hanssonit.se/nextcloud-vm/>`_
.. note:: You can install the VM on several different operating systems as long as you can mount OVA, VMDK, or VHD/VHDX VM in your hypervisor. If you are using KVM then you need to install the VM from the scripts on Github. You can follow the `instructions in the README <https://github.com/nextcloud/vm#build-your-own-vm-or-install-on-a-vps>`_.
.. note:: You can install the VM on several different operating systems as long as you can mount OVA, VMDK, or VHD/VHDX VM in your hypervisor. If you are using KVM then you need to install the VM from the scripts on GitHub. You can follow the `instructions in the README <https://github.com/nextcloud/vm#build-your-own-vm-or-install-on-a-vps>`_.
.. _snaps_label:
@ -453,7 +458,7 @@ To install the Nextcloud Snap Package, run the following command in a terminal::
Installation via web installer on a VPS or web space
----------------------------------------------------
When you don't have access to the command line, for example at a web hosting or VMPS,
When you don't have access to the command line, for example at a web hosting or VMPS,
an easy option is to use our web installer. This script can be found on our
`server installation page here. <https://nextcloud.com/install/#instructions-server>`_

17
admin_manual/installation/system_requirements.rst
View File

@ -21,17 +21,17 @@ For best performance, stability and functionality we have documented some recomm
| | - openSUSE Leap 42.1+ |
| | - CentOS 8 |
+------------------+-----------------------------------------------------------------------+
| Database | - **MySQL 5.7+ or MariaDB 10.2+** (recommended) |
| Database | - **MySQL 8.0+ or MariaDB 10.2/10.3/10.4/10.5** (recommended) |
| | - Oracle Database 11g (*only as part of an enterprise subscription*) |
| | - PostgreSQL 9.5/9.6/10/11 |
| | - PostgreSQL 9.6/10/11/12/13 |
| | - SQLite (*only recommended for testing and minimal-instances*) |
+------------------+-----------------------------------------------------------------------+
| Webserver | - **Apache 2.4 with** ``mod_php`` **or** ``php-fpm`` (recommended) |
| | - nginx with ``php-fpm`` |
+------------------+-----------------------------------------------------------------------+
| PHP Runtime | - 7.2 |
| | - **7.3** (*recommended*) |
| | - **7.4** (*recommended*) |
| PHP Runtime | - 7.3 |
| | - 7.4 |
| | - **8.0** (*recommended*) |
+------------------+-----------------------------------------------------------------------+
See :doc:`source_installation` for minimum PHP-modules and additional software for installing Nextcloud.
@ -60,7 +60,7 @@ Desktop client
We strongly recommend using the latest version of your operating system to get the full and most stable experience out
of our clients.
* **Windows** 7+
* **Windows** 8.1+
* **macOS** Lion (10.7)+ (64-bit only)
* **Linux** (CentOS 6.5+, Ubuntu 14.04+, Fedora 21+, openSUSE 13, SUSE Linux Enterprise 11 SP3+, Debian 8 (Jessie)+, Red Hat
Enterprise Linux 7)
@ -82,12 +82,11 @@ Web browser
For the best experience with the Nextcloud web interface, we recommend that you use the latest and supported version
of a browser from this list, or one based on those:
- Microsoft **Internet Explorer 11** (latest version)
- Microsoft **Edge**
- Mozilla **Firefox**
- Google **Chrome**/Chromium
- Apple **Safari**
.. note:: If you want to use Nextcloud Talk you should use Mozilla **Firefox** 52+ or Google **Chrome**/Chromium 49+ to have
the full experience with video calls and screensharing. Google Chrome/Chromium requires an additional plugin for
.. note:: If you want to use Nextcloud Talk you should use Mozilla **Firefox** 52+ or Google **Chrome**/Chromium 49+ to have
the full experience with video calls and screensharing. Google Chrome/Chromium requires an additional plugin for
screensharing.

47
admin_manual/issues/applying_patch.rst Normal file
View File

@ -0,0 +1,47 @@
==================
Patching Nextcloud
==================
Applying a patch
----------------
Patching server
^^^^^^^^^^^^^^^
1. Navigate into your Nextcloud server's root directory (contains the ``status.php`` file)
2. Now apply the patch with the following command::
patch -p 1 < /path/to/the/file.patch
.. note::
There can be errors about not found files, especially when you take a patch from GitHub there might be development or test files included in the patch. when the files are in build/ or a tests/ subdirectory it is mostly being
Patching apps
^^^^^^^^^^^^^
1. Navigate to the root of this app (mostly ``apps/[APPID]/``), if you can not find the app there use the ``sudo -u www-data php occ app:getpath APPID`` command to find the path.
2. Now apply the patch with the same command as in `Patching server`_
Reverting a patch
-----------------
1. Navigate to the directory where you applied the patch.
2. Now revert the patch with the ``-R`` option::
patch -R -p 1 < /path/to/the/file.patch
Getting a patch from a GitHub pull request
------------------------------------------
If you found a related pull request on GitHub that solves your issue, or you want to help developers and verify a fix works, you can get a patch for the pull request.
1. Using https://github.com/nextcloud/server/pull/26396 as an example.
2. Append ``.patch`` to the URL: https://github.com/nextcloud/server/pull/26396.patch
3. Download the patch to your server and follow the `Applying a patch`_ steps.
4. In case you are on an older version, you might first need to go the the correct version of the patch.
.. image:: images/getting-a-patch-from-github.png
:alt: backportbot-nextcloud linking to the pull request for an older version.
5. You can find it by looking for a link by the ``backportbot-nextcloud`` or a developer will leave a manual comment about the backport to an older Nextcloud version. For the example above you the pull request for Nextcloud 21 is at https://github.com/nextcloud/server/pull/26406 and the patch at https://github.com/nextcloud/server/pull/26406.patch

157
admin_manual/issues/general_troubleshooting.rst
View File

@ -2,22 +2,22 @@
General troubleshooting
=======================
If you have trouble installing, configuring or maintaining Nextcloud, please
If you have trouble installing, configuring or maintaining Nextcloud, please
refer to our community support channels:
* `The Nextcloud Forums`_
The Nextcloud forums have a `FAQ page`_ where each topic corresponds
to typical mistakes or frequently occurring issues
* The Nextcloud IRC chat channel ``irc://#nextcloud@freenode.net`` on
* The Nextcloud IRC chat channel ``irc://#nextcloud@freenode.net`` on
freenode.net, also accessible via `webchat`_
Please understand that all these channels essentially consist of users like you
helping each other out. Consider helping others out where you can, to contribute
back for the help you get. This is the only way to keep a community like
Please understand that all these channels essentially consist of users like you
helping each other out. Consider helping others out where you can, to contribute
back for the help you get. This is the only way to keep a community like
Nextcloud healthy and sustainable!
If you are using Nextcloud in a business or otherwise large scale deployment,
If you are using Nextcloud in a business or otherwise large scale deployment,
note that Nextcloud GmbH offers commercial support options.
Bugs
@ -28,8 +28,8 @@ If you think you have found a bug in Nextcloud, please:
* Search for a solution (see the options above)
* Double-check your configuration
If you can't find a solution, please use our `bugtracker`_. You can generate a
configuration report with the :ref:`occ config command
If you can't find a solution, please use our `bugtracker`_. You can generate a
configuration report with the :ref:`occ config command
<config_commands_label>`, with passwords automatically obscured.
.. _the Nextcloud Forums: https://help.nextcloud.com
@ -42,7 +42,7 @@ configuration report with the :ref:`occ config command
General troubleshooting
-----------------------
Check the Nextcloud :doc:`../installation/system_requirements`, especially
Check the Nextcloud :doc:`../installation/system_requirements`, especially
supported browser versions.
When you see warnings about ``code integrity``, refer to :doc:`code_signing`.
@ -50,59 +50,59 @@ When you see warnings about ``code integrity``, refer to :doc:`code_signing`.
Disable 3rdparty / non-shipped apps
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It might be possible that 3rd party / non-shipped apps are causing various
different issues. Always disable 3rd party apps before upgrades, and for
It might be possible that 3rd party / non-shipped apps are causing various
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
^^^^^^^^^^^^^^^^^^
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
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.
Some logging - for example JavaScript console logging - needs debugging
enabled. Edit :file:`config/config.php` and change ``'debug' => false,`` to
Some logging - for example JavaScript console logging - needs debugging
enabled. Edit :file:`config/config.php` and change ``'debug' => false,`` to
``'debug' => true,`` Be sure to change it back when you are finished.
For JavaScript issues you will also need to view the javascript console. All
major browsers have developer tools for viewing the console, and you
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
.. note:: The logfile of Nextcloud is located in the data directory
``nextcloud/data/nextcloud.log``.
.. _label-phpinfo:
PHP version and information
^^^^^^^^^^^^^^^^^^^^^^^^^^^
You will need to know your PHP version and configurations. To do this, create a
plain-text file named **phpinfo.php** and place it in your Web root, for
example ``/var/www/html/phpinfo.php``. (Your Web root may be in a different
location; your Linux distribution documentation will tell you where.) This file
You will need to know your PHP version and configurations. To do this, create a
plain-text file named **phpinfo.php** and place it in your Web root, for
example ``/var/www/html/phpinfo.php``. (Your Web root may be in a different
location; your Linux distribution documentation will tell you where.) This file
contains just this line::
<?php phpinfo(); ?>
Open this file in a Web browser by pointing your browser to
Open this file in a Web browser by pointing your browser to
``localhost/phpinfo.php``:
.. figure:: ../images/phpinfo.png
Your PHP version is at the top, and the rest of the page contains abundant
system information such as active modules, active ``.ini`` files, and much more.
When you are finished reviewing your information you must delete
``phpinfo.php``, or move it outside of your Web directory, because it is a
Your PHP version is at the top, and the rest of the page contains abundant
system information such as active modules, active ``.ini`` files, and much more.
When you are finished reviewing your information you must delete
``phpinfo.php``, or move it outside of your Web directory, because it is a
security risk to expose such sensitive data.
Debugging sync issues
^^^^^^^^^^^^^^^^^^^^^
.. warning:: The data directory on the server is exclusive to Nextcloud and must
.. warning:: The data directory on the server is exclusive to Nextcloud and must
not be modified manually.
Disregarding this can lead to unwanted behaviors like:
@ -110,7 +110,7 @@ Disregarding this can lead to unwanted behaviors like:
* Problems with sync clients
* Undetected changes due to caching in the database
If you need to directly upload files from the same server please use a WebDAV
If you need to directly upload files from the same server please use a WebDAV
command line client like ``cadaver`` to upload files to the WebDAV interface at:
``https://example.com/nextcloud/remote.php/dav``
@ -123,20 +123,20 @@ Some common problems / error messages found in your logfiles as described above:
* ``SQLSTATE[HY000] [1040] Too many connections`` -> You need to increase the
connection limit of your database, please refer to the manual of your database
for more information.
* ``SQLSTATE[HY000]: General error: 5 database is locked`` -> You're using
* ``SQLSTATE[HY000]: General error: 5 database is locked`` -> You're using
``SQLite``
which can't handle a lot of parallel requests. Please consider converting to
another database like described in
another database like described in
:doc:`../configuration_database/db_conversion`.
* ``SQLSTATE[HY000]: General error: 2006 MySQL server has gone away`` -> Please
refer to :ref:`db-troubleshooting-label` for more information.
* ``SQLSTATE[HY000] [2002] No such file or directory`` -> There is a problem
accessing your SQLite database file in your data directory
(``data/nextcloud.db``). Please check the permissions of this folder/file or
accessing your SQLite database file in your data directory
(``data/nextcloud.db``). Please check the permissions of this folder/file or
if it exists at all. If you're using MySQL please start your database.
* ``Connection closed / Operation cancelled`` -> This could be caused by wrong
``KeepAlive`` settings within your Apache config. Make sure that
``KeepAlive`` is set to ``On`` and also try to raise the limits of
* ``Connection closed / Operation cancelled`` -> This could be caused by wrong
``KeepAlive`` settings within your Apache config. Make sure that
``KeepAlive`` is set to ``On`` and also try to raise the limits of
``KeepAliveTimeout`` and ``MaxKeepAliveRequests``.
* ``No basic authentication headers were found`` -> This error is shown in your
``data/nextcloud.log`` file. Some Apache modules like ``mod_fastcgi``, ``mod_fcgid``
@ -151,29 +151,29 @@ Troubleshooting Web server and PHP problems
Logfiles
^^^^^^^^
When having issues the first step is to check the logfiles provided by PHP, the
When having issues the first step is to check the logfiles provided by PHP, the
Web server and Nextcloud itself.
.. note:: In the following the paths to the logfiles of a default Debian
installation running Apache2 with mod_php is assumed. On other Web servers,
.. note:: In the following the paths to the logfiles of a default Debian
installation running Apache2 with mod_php is assumed. On other Web servers,
Linux distros or operating systems they can differ.
* The logfile of Apache2 is located in ``/var/log/apache2/error.log``.
* The logfile of PHP can be configured in your ``/etc/php5/apache2/php.ini``.
* The logfile of PHP can be configured in your ``/etc/php/7.4/apache2/php.ini``.
You need to set the directive ``log_errors`` to ``On`` and choose the path
to store the logfile in the ``error_log`` directive. After those changes you
need to restart your Web server.
* The logfile of Nextcloud is located in the data directory
* The logfile of Nextcloud is located in the data directory
``/var/www/nextcloud/data/nextcloud.log``.
Web server and PHP modules
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note:: Lighttpd is not supported with Nextcloud, and some Nextcloud features
.. note:: Lighttpd is not supported with Nextcloud, and some Nextcloud features
may not work at all on Lighttpd.
There are some Web server or PHP modules which are known to cause various
problems like broken up-/downloads. The following shows a draft overview of
There are some Web server or PHP modules which are known to cause various
problems like broken up-/downloads. The following shows a draft overview of
these modules:
1. Apache
@ -183,11 +183,11 @@ these modules:
* mod_security
* mod_reqtimeout
* mod_deflate
* libapache2-mod-php5filter (use libapache2-mod-php5 instead)
* mod_spdy together with libapache2-mod-php5 / mod_php (use fcgi or php-fpm
* libapache2-mod-php*filter (use libapache2-mod-php7.4 instead)
* mod_spdy together with libapache2-mod-php5 / mod_php (use fcgi or php-fpm
instead)
* mod_dav
* mod_xsendfile / X-Sendfile (causing broken downloads if not configured
* mod_xsendfile / X-Sendfile (causing broken downloads if not configured
correctly)
2. NginX
@ -205,25 +205,25 @@ these modules:
Troubleshooting WebDAV
----------------------
Nextcloud uses SabreDAV, and the SabreDAV documentation is comprehensive and
Nextcloud uses SabreDAV, and the SabreDAV documentation is comprehensive and
helpful.
.. note: Lighttpd is not supported on Nextcloud, and Lighttpd WebDAV does not
.. note: Lighttpd is not supported on Nextcloud, and Lighttpd WebDAV does not
work with Nextcloud.
See:
* `SabreDAV FAQ <http://sabre.io/dav/faq/>`_
* `Web servers <http://sabre.io/dav/webservers>`_ (Lists lighttpd as not
* `Web servers <http://sabre.io/dav/webservers>`_ (Lists lighttpd as not
recommended)
* `Working with large files <http://sabre.io/dav/large-files/>`_ (Shows a PHP
* `Working with large files <http://sabre.io/dav/large-files/>`_ (Shows a PHP
bug in older SabreDAV versions and information for mod_security problems)
* `0 byte files <http://sabre.io/dav/0bytes>`_ (Reasons for empty files on the
* `0 byte files <http://sabre.io/dav/0bytes>`_ (Reasons for empty files on the
server)
* `Clients <http://sabre.io/dav/clients/>`_ (A comprehensive list of WebDAV
* `Clients <http://sabre.io/dav/clients/>`_ (A comprehensive list of WebDAV
clients, and possible problems with each one)
* `Finder, OS X's built-in WebDAV client
<http://sabre.io/dav/clients/finder/>`_
* `Finder, OS X's built-in WebDAV client
<http://sabre.io/dav/clients/finder/>`_
(Describes problems with Finder on various Web servers)
There is also a well maintained FAQ thread available at the `ownCloud Forums
@ -244,19 +244,12 @@ URLs:
| ``https://example.com/.well-known/carddav``
| ``https://example.com/.well-known/caldav``
| ``https://example.com/.well-known/webfinger``
|
Those need to be redirecting your clients to the correct endpoints. If Nextcloud
is running at the document root of your Web server the correct URL is:
``https://example.com/remote.php/dav`` for CardDAV and CalDAV and
``https://example.com/public.php?service=webfinger``
and if running in a subfolder like ``nextcloud``:
``https://example.com/nextcloud/remote.php/dav``
``https://example.com/nextcloud/public.php?service=webfinger``
is running at the document root of your Web server the correct URL is
``https://example.com/remote.php/dav`` for CardDAV and CalDAV and if running in a
subfolder like ``nextcloud``, then ``https://example.com/nextcloud/remote.php/dav``.
For the first case the :file:`.htaccess` file shipped with Nextcloud should do
this work for you when you're running Apache. You need to make sure that your
@ -271,16 +264,13 @@ document root of your Web server and add the following lines::
<IfModule mod_rewrite.c>
RewriteEngine on
RewriteRule ^\.well-known/host-meta /nextcloud/public.php?service=host-meta [QSA,L]
RewriteRule ^\.well-known/host-meta\.json /nextcloud/public.php?service=host-meta-json [QSA,L]
RewriteRule ^\.well-known/webfinger /nextcloud/public.php?service=webfinger [QSA,L]
RewriteRule ^\.well-known/carddav /nextcloud/remote.php/dav [R=301,L]
RewriteRule ^\.well-known/caldav /nextcloud/remote.php/dav [R=301,L]
</IfModule>
Make sure to change /nextcloud to the actual subfolder your Nextcloud instance is running in.
If you are running NGINX, make sure ``location = /.well-known/carddav {`` and ``location = /.well-known/caldav {`` are properly configured as described in :doc:`../installation/nginx`, adapt to use a subfolder if necessary.
If you are running NGINX, make sure ``location = /.well-known/carddav {`` and ``location = /.well-known/caldav {`` are properly configured as described in :doc:`../installation/nginx`, adapt to use a subfolder if necessary.
Now change the URL in the client settings to just use:
@ -322,8 +312,8 @@ it is likely caused by one of the following reasons:
Using Pound reverse-proxy/load balancer
As of writing this Pound doesn't support the HTTP/1.1 verb.
Pound is easily `patched
<http://www.apsis.ch/pound/pound_list/archive/2013/2013-08/1377264673000>`_
Pound is easily `patched
<http://www.apsis.ch/pound/pound_list/archive/2013/2013-08/1377264673000>`_
to support HTTP/1.1.
Misconfigured Web server
@ -346,8 +336,8 @@ Unofficially moving the data directory can be done as follows:
7. Restart apache
.. warning
However this is not supported and you risk breaking your database.
However this is not supported and you risk breaking your database.
For a safe moving of data directory, supported by Nextcloud, recommended actions are:
1. Make sure no cron jobs are running
@ -360,6 +350,21 @@ For a safe moving of data directory, supported by Nextcloud, recommended actions
.. warning
Note, you may need to configure your webserver to support symlinks.
Troubleshooting encryption
--------------------------
Problems when downloading or decrypting files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In some rare cases it can happen that encrypted files cannot be downloaded
and return a "500 Internal Server Error". If the Nextcloud log contains an error about
"Bad Signature", then the following command can be used to repair affected files:
| ``occ encryption:fix-encrypted-version userId --path=/path/to/broken/file.txt``
Replace "userId" and the path accordingly.
The command will do a test decryption for all files and automatically repair the ones with a signature error.
Other issues
------------

BIN
admin_manual/issues/images/getting-a-patch-from-github.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

5
admin_manual/issues/index.rst
View File

@ -1,10 +1,11 @@
==========================
Issues and troubleshooting
==========================
==========================
.. toctree::
:maxdepth: 2
general_troubleshooting
applying_patch
code_signing

7
admin_manual/maintenance/backup.rst
View File

@ -43,11 +43,15 @@ Backup database
MySQL/MariaDB
^^^^^^^^^^^^^
MySQL or MariaDB, which is a drop-in MySQL replacement, is the recommended
MySQL or MariaDB, which is a drop-in MySQL replacement, is the recommended
database engine. To backup MySQL/MariaDB::
mysqldump --single-transaction -h [server] -u [username] -p[password] [db_name] > nextcloud-sqlbkp_`date +"%Y%m%d"`.bak
If you use enabled MySQL/MariaDB 4-byte support (:doc:`../configuration_database/mysql_4byte_support`, needed for emoji), you will need to add ``--default-character-set=utf8mb4`` like this::
mysqldump --single-transaction --default-character-set=utf8mb4 -h [server] -u [username] -p[password] [db_name] > nextcloud-sqlbkp_`date +"%Y%m%d"`.bak
SQLite
^^^^^^
::
@ -59,4 +63,3 @@ PostgreSQL
::
PGPASSWORD="password" pg_dump [db_name] -h [server] -U [username] -f nextcloud-sqlbkp_`date +"%Y%m%d"`.bak

27
admin_manual/maintenance/migrating_owncloud.rst
View File

@ -15,7 +15,9 @@ See the table below for a version map, where migrating is easily possible:
+-------------------+------------------------------+
| ownCloud | Nextcloud |
+===================+==============================+
| 10.0.1 or later | 12.0.x (but at least 12.0.1) |
| 10.0.5 or later | 20.0.x (but at least 20.0.5) |
+-------------------+------------------------------+
| 10.0.1 - 10.0.5 | 12.0.x (but at least 12.0.1) |
+-------------------+------------------------------+
| 10.0.0 | 12.0.0 |
+-------------------+------------------------------+
@ -30,12 +32,25 @@ See the table below for a version map, where migrating is easily possible:
.. note:: While we understand, that you want to migrate as soon as possible,
we also don't want to put your data at risk. Since we never know
what ownCloud changes in a future release, we only allow migrations
from versions that where released before our last maintenance release,
from versions that were released before our last maintenance release,
so we can at least perform some basic migration tests, before you
migrate your production instance.
After downloading the correct version of Nextcloud from our
`older releases page <https://nextcloud.com/changelog/>`_,
proceed like described in the :doc:`manual_upgrade` manual.
1. First download the correct version of Nextcloud from our `older releases page <https://nextcloud.com/changelog/>`_,
Afterwards you can use the Nextcloud updater to update your instance to the newest version.
2. Make sure to have do a :doc:`backup<backup>` before migrating.
3. Follow the upgrade instructions described in the :doc:`manual_upgrade` manual.
4. When migrating to Nextcloud 20.0 or later, you will also need to run the following commands after ``occ upgrade``:
* ``occ db:convert-filecache-bigint``
* ``occ db:add-missing-columns``
* ``occ db:add-missing-indices``
* ``occ db:add-missing-primary-keys``
5. If system cron was used, please verify if crontab entry was using the command ``occ system:cron``. If yes, please adjust it to use the ``php`` command instead according to :ref:`the background jobs configuration documentation<system-cron-configuration-label>`
6. Use the :doc:`Nextcloud built-in updater<update>` to update your instance to the newest version.
7. Make sure to also verify the "Security & setup warnings" in the "Overview" section on the settings page.

9
admin_manual/maintenance/update.rst
View File

@ -160,6 +160,11 @@ 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
@ -173,7 +178,7 @@ The steps are basically the same as for the web based updater:
2. Instead of clicking that button you can now invoke the command line based
updater by going into the `updater/` directory in the Nextcloud directory
and executing the `updater.phar` as the web server user. (i.e.
``sudo -u www-data php updater.phar``)
``sudo -u www-data php /var/www/nextcloud/updater/updater.phar``)
.. image:: images/updater-cli-2-start-updater.png
:class: terminal-image
@ -220,7 +225,7 @@ except an error occured during the ``occ upgrade`` or the replacement of the
code.
To execute this, run the command with the ``--no-interaction`` option. (i.e.
``sudo -u www-data php updater.phar --no-interaction``)
``sudo -u www-data php /var/www/nextcloud/updater/updater.phar --no-interaction``)
.. image:: images/updater-cli-8-no-interaction.png
:class: terminal-image

12
admin_manual/maintenance/upgrade.rst
View File

@ -19,10 +19,14 @@ notification at the top of your Nextcloud Web interface. When you click the
notification it brings you here, to this page.
**It is best to keep your Nextcloud server upgraded regularly**, and to install
all point releases and major releases. Major releases are 11, 12, and 13.
Point releases are intermediate releases for each major release. For example,
13.0.4 and 12.0.9 are point releases. **Skipping major releases is not
supported.**
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.
Nextcloud must be upgraded step by step:
* Before you can upgrade to the next major release, Nextcloud upgrades to the latest point release.
* 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
**Upgrading is disruptive**. Your Nextcloud server will be put into maintenance
mode, so your users will be locked out until the upgrade is completed. Large

16
admin_manual/release_schedule.rst
View File

@ -7,14 +7,13 @@ This page gives an overview of the currently supported and released versions as
+--------+-------------------+------------------+
| | release date | end of life |
+========+===================+==================+
| **19** | 2020-06-03 | 2021-06 |
| **22** | 2021-07-06 | 2022-07 |
+--------+-------------------+------------------+
| **18** | 2020-01-16 | 2021-01 |
| **21** | 2021-02-22 | 2022-02 |
+--------+-------------------+------------------+
| **17** | 2019-09-30 | 2020-09 |
| **20** | 2020-10-03 | 2021-10 |
+--------+-------------------+------------------+
Find the detailed schedule for major and maintenance releases at: `GitHub <https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule>`_.
Major releases
@ -35,6 +34,15 @@ Older versions
+----------+----------------+-------------+-------------------------+
| | release date | end of life | latest version |
+==========+================+=============+=========================+
| **19** | 2020-06-03 | 2021-06 | 19.0.13 (2021-07-01) |
+----------+----------------+-------------+-------------------------+
| **18** | 2020-01-16 | 2021-01 | 18.0.14 (2021-01-27) |
+----------+----------------+-------------+-------------------------+
| **17** | 2019-09-30 | 2020-10 | 17.0.10 (2020-10-08) |
+----------+----------------+-------------+-------------------------+
| **18** | 2020-01-16 | 2021-01 | 18.0.14 (2021-01-27) |
+----------+----------------+-------------+-------------------------+
| **17** | 2019-09-30 | 2020-10 | 17.0.10 (2020-10-08) |
+----------+----------------+-------------+-------------------------+
| **16** | 2019-04-25 | 2020-06 | 16.0.11 (2020-06-04) |
+----------+----------------+-------------+-------------------------+

4
conf.py
View File

@ -36,8 +36,8 @@ html_logo = "../_shared_assets/static/logo-white.png"
rst_epilog = '.. |version| replace:: %s' % version
# building the versions list
version_start = 17 # THIS IS THE SUPPORTED VERSION NUMBER
version_stable = 20 # INCREASE THIS NUMBER TO THE LATEST STABLE VERSION NUMBER
version_start = 20 # THIS IS THE SUPPORTED VERSION NUMBER
version_stable = 22 # INCREASE THIS NUMBER TO THE LATEST STABLE VERSION NUMBER
def generateVersionsDocs(current_docs):
versions_doc = []
for v in range(version_start, version_stable + 1):

12
developer_manual/app_development/bootstrap.rst
View File

@ -54,17 +54,23 @@ The class **must** extend ``OCP\AppFramework\App`` and may optionally implement
use OCA\MyApp\Listeners\UserDeletedListener;
use OCA\MyApp\Notifications\Notifier;
use OCP\AppFramework\App;
use OCP\AppFramework\Bootstrap\IBootContext;
use OCP\AppFramework\Bootstrap\IBootstrap;
use OCP\AppFramework\Bootstrap\IRegistrationContext;
use OCP\Notification\IManager;
use OCP\User\Events;
class Application extends App implements IBootstrap {
public function __construct() {
parent::__construct('myapp');
}
public function register(IRegistrationContext $context): void {
// ... registration logic goes here ...
// Register the composer autoloader for packages shipped by this app, if applicable
@include_once __DIR__ . '/../../vendor/autoload.php'
include_once __DIR__ . '/../../vendor/autoload.php';
$context->registerEventListener(
BeforeUserDeletedEvent::class,
@ -76,7 +82,7 @@ The class **must** extend ``OCP\AppFramework\App`` and may optionally implement
// ... boot logic goes here ...
/** @var IManager $manager */
$manager = $context->getAppContainer()->query(IManager::class)
$manager = $context->getAppContainer()->query(IManager::class);
$manager->registerNotifierService(Notifier::class);
}
@ -138,6 +144,6 @@ class and query an instance like
declare(strict_types=1);
// Register the composer autoloader for packages shipped by this app, if applicable
@include_once __DIR__ . '/../vendor/autoload.php'
include_once __DIR__ . '/../vendor/autoload.php';
$app = \OC::$server->query(\OCA\MyApp\AppInfo\Application::class);

19
developer_manual/app_development/dependency_management.rst Normal file
View File

@ -0,0 +1,19 @@
.. _Dependencymanagement:
=====================
Dependency management
=====================
It's possible to build a Nextcloud app with existing software packages.
.. _app-composer:
Composer
--------
You can add 3rd party php packages with `Composer`_. Composer will download the specified packages to a directory of your choise, typically to ``/vendor``. In order to benefit from Composer's autoloader, you'll want to add a ``require_once`` to the ``register`` method of your ``Application`` class in the :ref:`bootstrapping<Bootstrapping>` code of your app.
.. note:: 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 ship the same library. So try to keep the number of libraries to a minimum.
.. _Composer: https://getcomposer.org/

2
developer_manual/app_development/index.rst
View File

@ -10,4 +10,4 @@ App development
bootstrap
info
init
logging
dependency_management

2
developer_manual/app_development/info.rst
View File

@ -1,3 +1,5 @@
.. _app metadata:
============
App metadata
============

40
developer_manual/app_development/init.rst
View File

@ -19,44 +19,16 @@ Navigation entries for apps can be created by adding a navigation section to the
</navigation>
Further pre-app configuration
-----------------------------
The :file:`appinfo/app.php` is the first file that is loaded and executed in Nextcloud. Depending on the purpose of the app it is usually used to setup things that need to be available on every request to the server, like :doc:`backgroundjobs` and :doc:`hooks` registrations. This is how an example :file:`appinfo/app.php` could look like:
.. code-block:: php
<?php
// execute OCA\MyApp\BackgroundJob\Task::run when cron is called
\OC::$server->getJobList()->add('OCA\MyApp\BackgroundJob\Task');
// execute OCA\MyApp\Hooks\User::deleteUser before a user is being deleted
\OCP\Util::connectHook('OC_User', 'pre_deleteUser', 'OCA\MyApp\Hooks\User', 'deleteUser');
Initialization events
---------------------
Often apps do not need to load their JavaScript and CSS on every page. For this
purpose there are several events emitted that an app can act upon.
* `OCA\Files::loadAdditionalScripts` (string): loaded on the files list page
* `OCA\Files_Sharing::loadAdditionalScripts` (string): loaded on the public sharing page
* `OCA\Files_Sharing::loadAdditionalScripts::publicShareAuth` (string): loaded on the public share authentication page
* `OCP\AppFramework\Http\TemplateResponse::EVENT_LOAD_ADDITIONAL_SCRIPTS` (constant): loaded when a template response is finished
* `OCP\AppFramework\Http\TemplateResponse::EVENT_LOAD_ADDITIONAL_SCRIPTS_LOGGEDIN` (constant): loaded when a template response is finished for a logged in user
* ``OCA\Files::loadAdditionalScripts`` (string): loaded on the files list page
* ``OCA\Files_Sharing::loadAdditionalScripts`` (string): loaded on the public sharing page
* ``OCA\Files_Sharing::loadAdditionalScripts::publicShareAuth`` (string): loaded on the public share authentication page
* ``OCP\AppFramework\Http\TemplateResponse::EVENT_LOAD_ADDITIONAL_SCRIPTS`` (constant): loaded when a template response is finished
* ``OCP\AppFramework\Http\TemplateResponse::EVENT_LOAD_ADDITIONAL_SCRIPTS_LOGGEDIN`` (constant): loaded when a template response is finished for a logged in user
.. code-block:: php
<?php
$dispatcher = \OC::$server->getEventDispatcher();
$dispatcher->addListener(
OCP\AppFramework\Http\TemplateResponse::EVENT_LOAD_ADDITIONAL_SCRIPTS,
function() {
\OCP\Util::addScript('myapp', 'script');
\OCP\Util::addStyle('myapp', 'style');
}
);
You can subscribe listeners to these events in the :ref:`bootstrapping code<Bootstrapping>` of the app. See the :ref:`events documentation<Events>` for more details on the event dispatcher and available events.

34
developer_manual/app_development/tutorial.rst
View File

@ -12,9 +12,9 @@ Setup
First the :doc:`development environment <../general/devenv>` needs to be set up. This can be done by either `downloading the zip from the website <https://nextcloud.com/install/>`_ or cloning it directly from GitHub::
git clone git@github.com:nextcloud/server.git --branch $BRANCH
cd server
git submodule update --init
git clone git@github.com:nextcloud/server.git --branch $BRANCH
cd server
git submodule update --init
.. note:: ``$BRANCH`` is the desired Nextcloud branch (e.g. ``stable19`` for Nextcloud 19, ``master`` for the upcoming release)
@ -33,6 +33,16 @@ Now open another terminal window and start the development server::
cd nextcloud
php -S localhost:8080
*Alternative Setups*:
Launch with podman (leaner than docker and allows you to run containers without being root)::
podman run --name=nextcloud --replace=true -p 8080:80 -v /absolute/path/to/apps:/var/www/html/custom_apps docker.io/nextcloud
Launch with docker (not tested)::
sudo docker run --name=nextcloud -p 8080:80 -v /absolute/path/to/apps:/var/www/html/custom_apps nextcloud
Afterwards a skeleton app can be created in the `app store <https://apps.nextcloud.com/developer/apps/generate>`_.
Download the compressed file that contains the generated app and extract it into your ``apps/`` directory. Afterwards the application can be enabled on the `apps page <http://localhost:8080/index.php/settings/apps>`_.
@ -266,12 +276,14 @@ so for example **notestutorial/lib/Migration/Version000000Date20181013124731.php
To create the tables in the database, run the :ref:`migration <migration_console_command>` command::
php ./occ migrations:excute <appId> <versionNumber>
php ./occ migrations:execute <appId> <versionNumber>
Example: sudo -u www-data php ./occ migrations:execute photos 000000Date20201002183800
.. note:: to trigger the table creation/alteration when user updating the app, update the :doc:`version tag <info>` in **notestutorial/appinfo/info.xml** . migration will be executed when user reload page after app upgrade
.. note:: to be able to access the occ migrations commands, please enable the debug flag in config.php
.. code-block:: xml
<?xml version="1.0"?>
@ -307,7 +319,7 @@ Now that the tables are created we want to map the database result to a PHP obje
protected $title;
protected $content;
protected $userId;
public function __construct() {
$this->addType('id','integer');
}
@ -332,12 +344,12 @@ Entities are returned from so-called :doc:`Mappers <storage/database>`. Let's cr
<?php
namespace OCA\NotesTutorial\Db;
use OCP\IDbConnection;
use OCP\IDBConnection;
use OCP\AppFramework\Db\QBMapper;
class NoteMapper extends QBMapper {
public function __construct(IDbConnection $db) {
public function __construct(IDBConnection $db) {
parent::__construct($db, 'notestutorial_notes', Note::class);
}
@ -718,7 +730,7 @@ Because Nextcloud uses :doc:`Dependency Injection <requests/container>` to assem
<?php
namespace OCA\NotesTutorial\Tests\Unit\Controller;
use PHPUnit_Framework_TestCase;
use PHPUnit\Framework\TestCase;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\DataResponse;
@ -726,7 +738,7 @@ Because Nextcloud uses :doc:`Dependency Injection <requests/container>` to assem
use OCA\NotesTutorial\Service\NotFoundException;
class NoteControllerTest extends PHPUnit_Framework_TestCase {
class NoteControllerTest extends TestCase {
protected $controller;
protected $service;
@ -780,13 +792,13 @@ We can and should also create a test for the **NoteService** class:
<?php
namespace OCA\NotesTutorial\Tests\Unit\Service;
use PHPUnit_Framework_TestCase;
use PHPUnit\Framework\TestCase;
use OCP\AppFramework\Db\DoesNotExistException;
use OCA\NotesTutorial\Db\Note;
class NoteServiceTest extends PHPUnit_Framework_TestCase {
class NoteServiceTest extends TestCase {
private $service;
private $mapper;

1
developer_manual/app_publishing_maintenance/index.rst
View File

@ -7,4 +7,5 @@ App publishing and maintenance
code_signing
publishing
release_automation
upgrade-guide

10
developer_manual/app_publishing_maintenance/publishing.rst
View File

@ -18,14 +18,6 @@ Getting an app approved
-----------------------
You can find documentation on getting apps in our app store `here. <https://nextcloudappstore.readthedocs.io/en/latest/developer.html#publishing-apps-on-the-app-store>`_
Using the code checker
^^^^^^^^^^^^^^^^^^^^^^
Before getting the app in the app store, it is best to check your app code with the code checker, and fix the issues found by the code checker.
.. code-block:: bash
./occ app:check-code <app_name>
Losing a rating
^^^^^^^^^^^^^^^
Apps can lose their rating when:
@ -99,4 +91,4 @@ The goal of these rules is simple: help your project be more successful. We also
How to move
^^^^^^^^^^^
To move your repository to our Github organization, just ask any of our contributors, `especially those who are admin. <https://github.com/orgs/nextcloud/people?utf8=%E2%9C%93&query=+role%3Aowner>`_ They will be happy to help!
To move your repository to our GitHub organization, just ask any of our contributors, `especially those who are admin. <https://github.com/orgs/nextcloud/people?utf8=%E2%9C%93&query=+role%3Aowner>`_ They will be happy to help!

203
developer_manual/app_publishing_maintenance/release_automation.rst Normal file
View File

@ -0,0 +1,203 @@
==================
Release Automation
==================
.. sectionauthor:: Benjamin Brahmer <info@b-brahmer.de>
Automation is a great thing, it prevents mistakes and makes your life easier, which gives you more time to work on all those features you wanted to implement.
GitHub Actions
--------------
If your application's repository lives on GitHub, as many Nextcloud applications do, GitHub Actions is a great way to automate the release of your app from the git repository into the Nextcloud App Store.
One easy way to get you started is to use https://github.com/R0Wi/nextcloud-appstore-push-action in your repository together with a few other actions. You can automatically build your app and publish it to the App Store. It supports pre-releases and code signing.
To get started you create a new yaml file in the ``.github/workflows`` directory.
.. code-block:: yaml
name: Build and publish app release
on:
release:
types: [published]
env:
APP_NAME: news
jobs:
build_and_publish:
environment: release
runs-on: ubuntu-latest
name: "Release: build, sign and upload the app"
strategy:
matrix:
php-versions: ['7.4']
nextcloud: ['stable21']
database: ['sqlite']
steps:
- name: Checkout
uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
- name: Setup PHP
uses: shivammathur/setup-php@afefcaf556d98dc7896cca380e181decb609ca44
with:
php-version: ${{ matrix.php-versions }}
extensions: pdo_sqlite,pdo_mysql,pdo_pgsql,gd,zip
coverage: none
- name: Set up server non MySQL
uses: SMillerDev/nextcloud-actions/setup-nextcloud@fae87e29aa7cdf1ea0b8033c67f60e75b10be2cd
with:
cron: false
version: ${{ matrix.nextcloud }}
database-type: ${{ matrix.database }}
- name: Prime app build
run: make
- name: Configure server with app
uses: SMillerDev/nextcloud-actions/setup-nextcloud-app@fae87e29aa7cdf1ea0b8033c67f60e75b10be2cd
with:
app: ${{ env.APP_NAME }}
check-code: false
- name: Create signed release archive
run: |
cd ../server/apps/${{ env.APP_NAME }} && make appstore
env:
app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
app_public_crt: ${{ secrets.APP_PUBLIC_CRT }}
- name: Upload app tarball to release
uses: svenstaro/upload-release-action@483c1e56f95e88835747b1c7c60581215016cbf2
id: attach_to_release
with:
repo_token: ${{ secrets.GITHUB_TOKEN }}
file: ../server/apps/${{ env.APP_NAME }}/build/artifacts/appstore/${{ env.APP_NAME }}.tar.gz
asset_name: ${{ env.APP_NAME }}.tar.gz
tag: ${{ github.ref }}
overwrite: true
- name: Upload app to Nextcloud appstore
uses: R0Wi/nextcloud-appstore-push-action@a011fe619bcf6e77ddebc96f9908e1af4071b9c1
with:
app_name: ${{ env.APP_NAME }}
appstore_token: ${{ secrets.APPSTORE_TOKEN }}
download_url: ${{ steps.attach_to_release.outputs.browser_download_url }}
app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
nightly: ${{ github.event.release.prerelease }}
- name: Delete crt and key from local storage
run: rm -f ~/.nextcloud/certificates/*
Make sure to check the used actions for useful updates, as they are pinned to a specific sha1 to prevent unnoticed harmful changes.
For this workflow to work we need to provide a few variables.
* ``APP_NAME`` set the name of your app, directly in the yaml
Then we have a few secrets make sure to handle them with care.
If your repository lives within the nextcloud organization you need to use an environment.
.. code-block:: yaml
jobs:
build_and_publish:
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.
* ``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
* ``APPSTORE_TOKEN`` you get this from the App Store as a registered developer https://apps.nextcloud.com/account/token
If your app does not live in the Nextcloud organization you may also add the secrets above to the "Secrets" section but be careful everyone with write access to your repository will be able to create releases. Make also sure to delete the environment statement.
If you don't use code signing for your app you can delete the following section in your yaml.
.. code-block:: yaml
env:
app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
app_public_cert: ${{ secrets.APP_PUBLIC_CERT }}
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.
One example you may use is provided by the news app.
.. code-block:: php
#!/usr/bin/env php
<?php
/**
* Nextcloud - News
*
* This file is licensed under the Affero General Public License version 3 or
* later. See the COPYING file.
*
* @author Benjamin Brahmer <info@b-brahmer.de>
* @copyright Benjamin Brahmer 2020
*/
if ($argc < 2) {
echo "This script expects two parameters:\n";
echo "./file_from_env.php ENV_VAR PATH_TO_FILE\n";
exit(1);
}
# Read environment variable
$content = getenv($argv[1]);
if (!$content){
echo "Variable was empty\n";
exit(1);
}
file_put_contents($argv[2], $content);
echo "Done...\n";
It's a very simple php script that takes an environment variable and a filepath and dumps whatever it finds in the variable into the file.
After storing that script somewhere in your repository, you can use it in your Makefile.
.. code-block:: bash
cert_dir=$(HOME)/.nextcloud/certificates
[...]
appstore:
[...]
# export the key and cert to a file
mkdir -p $(cert_dir)
php ./bin/tools/file_from_env.php "app_private_key" "$(cert_dir)/$(app_name).key"
php ./bin/tools/file_from_env.php "app_public_crt" "$(cert_dir)/$(app_name).crt"
[...]
Also make sure that these files are used when signing your app, in the Makefile.
.. code-block:: bash
@if [ -f $(cert_dir)/$(app_name).key ]; then \
echo "Signing app files…"; \
php ../../occ integrity:sign-app \
--privateKey=$(cert_dir)/$(app_name).key\
--certificate=$(cert_dir)/$(app_name).crt\
--path=$(appstore_sign_dir)/$(app_name); \
echo "Signing app files ... done"; \
fi
And that's basically everything you need to do, you can use the key and cert while you sign the app.
The process
~~~~~~~~~~~
1. Create a new release via GitHub, put whatever information you usually put.
2. Decide if this should be a normal or a pre-release, pre-releases will be uploaded as nightly version to the App Store.
3. When you are done, publish the release and wait a few minutes, you will see a request to approve the release, in Actions or your notifications.
4. If everything worked you find a ``appname.tar.gz`` as an attachment of the release.
5. Check the App Store for your newly released version, congratulations on your first automatically released app.

201
developer_manual/app_publishing_maintenance/upgrade-guide.rst
View File

@ -6,10 +6,189 @@ Once you've created and published the first version of your app, you will want t
This document will cover the most important changes in Nextcloud, as well as some guides on how to upgrade existing apps.
Upgrading to Nextcloud 22
-------------------------
.. note:: Critical changes were collected `on GitHub <https://github.com/nextcloud/server/issues/26407>`__. See the original ticket for links to the pull requests and tickets.
General
^^^^^^^
Migration commands
******************
The occ commands in the ``migration:*`` namespace are now only available in :ref:`debug mode<debug-mode>`.
See `the pull request on GitHub <https://github.com/nextcloud/server/pull/27113>`__ for more information. If you thought you needed them, feel free to ping the author or a reviewer of the PR to solve the problem correctly. Running migrations directly mostly breaks the database status and is therefore only meant for debugging faulty migrations.
Log format
**********
The JSON log format no longer contains full exception in the message field, but a separate exception entry is added and the existing message will only contain the exception message text. This might need adjustments by administrators when logs are extracted to external sources.
Front-end changes
^^^^^^^^^^^^^^^^^
Scss variable and compilation deprecation
*****************************************
Nextcloud is slowly phasing out scss variables and the compilation of app style sheets. It's recommended that apps use their own compilation (e.g. through Webpack) to transform scss and similar to plain css. The ability of Nextcloud compiling scss for apps will be removed in the future. Subscribe to `GitHub ticket 9940 <https://github.com/nextcloud/server/issues/9940>`__ to get updates on how to best approach this. Right now some scss variables can be replaced with css variables. Other mechanisms like the icon generation still depend on the scss compilation by Nextcloud.
Node.js upgrade
***************
Most Nextcloud apps and Nextcloud itself is now built with Node v14 LTS instead of v12. We recommend updating the configuration of your app accordingly.
IE11 removal
************
Internet Explorer 11 was phased out over the past few releases and starting with Nextcloud 22 the front-end code isn't transpiled for IE11 any longer. You may also drop IE11 from your app as core components will possibly fail with this browser anyway.
Deprecated global variables
***************************
* ``DOMPurify``: ship your own.
Back-end changes
^^^^^^^^^^^^^^^^
Removed support for database.xml
********************************
The support for an app's ``appinfo/database.xml`` has been removed.
PSR events
**********
In order to bring Nextcloud APIs closer to :ref:`psr` the base event class no longer extends the old Symfony event class but only ``\Psr\EventDispatcher\StoppableEventInterface``. From an app's perspective this change is transparent.
PSR container
*************
The :ref:`PSR 11 container interface <psr11>` was updated from version 1.0 to 1.1.
LDAP factory availability
*************************
``\OCP\LDAP\ILDAPProviderFactory`` received a new method ``isAvailable`` so apps can check if LDAP is configured and used before any attributes are fetched or similar.
Boolean database columns
************************
Since Oracle can not store booleans in a non-nullable boolean column Nextcloud doesn't support non-null boolean columns anymore. Apps have to migrate their schema to nullable boolean columns.
HTTP 401 for invalid username/password
**************************************
When invalid username/password is sent to a Nextcloud API, Nextcloud will now respond with a HTTP 401 status instead of 403.
Removed APIs
************
* ``\OC\Memcache\Factory::create``
* ``\OCP\User``
* ``\OCP\Util::isIe``
Deprecated APIs
***************
* ``\OCP\Log\ILogFactory::getCustomLogger``: use ``\OCP\Log\ILogFactory::getCustomPsrLogger`` to get a customized :ref:`PSR3 <psr3>` logger
* Event ``\OCP\IDBConnection::ADD_MISSING_INDEXES`` and the corresponding constant ``\OCP\IDBConnection::ADD_MISSING_INDEXES_EVENT``: internal event
* Event ``\OCP\IDBConnection::CHECK_MISSING_INDEXES`` and the corresponding constant ``\OCP\IDBConnection::CHECK_MISSING_INDEXES_EVENT``: internal event
* Event ``\OCP\IDBConnection::ADD_MISSING_PRIMARY_KEYS`` and the corresponding constant ``\OCP\IDBConnection::ADD_MISSING_PRIMARY_KEYS_EVENT``: internal event
* Event ``\OCP\IDBConnection::CHECK_MISSING_PRIMARY_KEYS`` and the corresponding constant ``\OCP\IDBConnection::CHECK_MISSING_PRIMARY_KEYS_EVENT``: internal event
* Event ``\OCP\IDBConnection::ADD_MISSING_COLUMNS_EVENT`` and the corresponding constant ``\OCP\IDBConnection::ADD_MISSING_COLUMNS``: internal event
* Event ``\OCP\IDBConnection::CHECK_MISSING_COLUMNS`` and the corresponding constant ``\OCP\IDBConnection::CHECK_MISSING_COLUMNS``: internal event
Upgrading to Nextcloud 21
-------------------------
.. note:: Critical changes were collected `on GitHub <https://github.com/nextcloud/server/issues/23210>`__. See the original ticket for links to the pull requests and tickets.
General
^^^^^^^
The biggest change in Nextcloud 21 is the initial support for PHP 8 and the corresponding updates of many core dependencies, which could have direct and indirect consequences for apps.
PHP 8 support
*************
Nextcloud 21 is the first major release that is compatible with the new PHP 8.0. As a consequence, some previously working syntax can cause problems when an app is deployed with PHP newer than 7.4. The full changelog can be found `on the php.net website <https://www.php.net/ChangeLog-8.php>`__. There is also a document for all breaking changes `on GitHub <https://github.com/php/php-src/blob/PHP-8.0/UPGRADING#L20>`__.
To check compatibility automatically we recommend adding or updating the :ref:`app-ci` of your app so that linters, tests and static analysis can warn you about any problems before the app is shipped to users.
Updated core libraries
**********************
If apps use only official public APIs of Nextcloud, the update of core libraries should have little to no effect on apps. However, there are some edge cases where an app still has a code dependency to a library shipped with Nextcloud, e.g. when those 3rdparty classes or functions are used, and therefore app developers are recommended to check their code for any incompatibility. Moreover it's recommended to check compatibility with sophisticated tools, as documented at the :ref:`static analysis<app-static-analysis>` section.
``doctrine/dbal``
=================
The Doctrine Database Abstraction Layer powers Nextcloud's database connection and query builder. In Nextcloud 21, this dependency was updated from 2.x to 3.0. As a consequence, some types that were previously exported through the Nextcloud OCP API are removed or changed by this update. For backwards-compatibility, there is now a tiny compatibility layer between the original Doctrine API and what apps use via the Nextcloud API.
Optimistically speaking, the database connection and the query builder should mostly work like in Nextcloud 20 or older. The main differences are that prepared statements and query results are not handled by the removed Doctrine ``Statement`` but two new Nextcloud types ``IPreparedStatement`` and ``IResult``. You don't have to worry about these types unless you pass around the result of a query to class/method/function with type hints. In this rare case, please adjust the type hints accordingly for the new type if you only support Nextcloud 21 in your apps or remove the type hint temporarily for multi-version Nextcloud support.
Some (minor) breaking changes were inevitable. Here's the summary
* Many of the database connection methods have now a documented exception that can be thrown: ``\OCP\DB\Exception``. This also acts as a replacement for the removed ``\Doctrine\DBAL\DBALException``.
* ``$queryBuilder->execute()->fetch()`` only has one argument now (there were three previously)
* ``$queryBuilder->execute()->fetchColumn()`` has no more arguments and got also deprecated. Use ``fetchOne`` instead
* ``$queryBuilder->execute()->bindParam()`` was removed because conceptually it does not make sense to bind a parameter *after* executing a query. Use ``bindParam`` on the ``IPeparedStatement`` instead.
* ``$queryBuilder->execute()->bindValue()`` was removed because conceptually it does not make sense to bind a value *after* executing a query. Use ``bindValue`` on the ``IPeparedStatement`` instead.
* ``$queryBuilder->execute()->columnCount()`` was removed
* ``$queryBuilder->execute()->errorCode()`` was removed from Doctrine
* ``$queryBuilder->execute()->errorInfo()`` was removed from Doctrine
* ``$queryBuilder->execute()->setFetchMode()`` was removed from Doctrine
* ``$connection->prepare()->execute()`` previously returned ``false`` under some error conditions, it now always gives you an ``IResult`` or throws a ``\OCP\DB\Exception``.
* ``\Doctrine\DBAL\Types\Type::*`` type constants were moved, which some apps used for column type constants in apps. Use the new ``\OCP\DB\Types::*`` as a replacement.
The details of this change can also be seen in the `pull request on GitHub <https://github.com/nextcloud/server/pull/24948>`__ and in the upstream `dbal 3.0.xx upgrade document <https://github.com/doctrine/dbal/blob/3.0.x/UPGRADE.md>`__.
``guzzlehttp/guzzle``
=====================
The HTTP client library behind the Nextcloud HTTP client was updated for PHP 8 compatibility. The Nextcloud abstraction remained untouched and will work like before. If you used Guzzle directly, make sure you don't use the fluent API on requests or responses.
``psr/log``
===========
The :ref:`psr3` package was updated to v1.1. The ``log`` method can now theoretically throw an ``\Psr\Log\InvalidArgumentException``, though Nextcloud does not make use of this at the moment. It's recommended to check any usage of the method nevertheless and add error handling if appropriate.
``sabre/*``
===========
The Sabre packages received a minor update. Only apps that provide DAV functionality should be effected, if any.
App code checker deprecation
****************************
The app code checker (``occ app:check-code myapp``) is obsolete due to :ref:`static analysis<app-static-analysis>`. For Nextcloud 21 it will act as NOOP, meaning that you can still call the command but it will never fail. This allows you to still use it on CI if you test against 21, 20 and older releases. But prepare the switch to static analysis if you haven't already. Please also note that the app code checker hadn't received many updates recently, hence the number of issues it can detect is low.
PSR-0 deprecation
*****************
The original `PSR-0` standard was deprecated in 2014 and therefore the support for it in Nextcloud will also end soon. Hence we recommend migrating your class file names to `PSR-4`.
.. _`PSR-0`: https://www.php-fig.org/psr/psr-0/
.. _`PSR-4`: https://www.php-fig.org/psr/psr-4/
Last version with database.xml support and migration
****************************************************
Nextcloud 21 is the last major release that supports an app's ``appinfo/database.xml`` to define the database schema. This is your last chance to automatically convert this deprecated file into the new migration classes using ``occ migrations:generate-from-schema``.
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<web-host-metadata>` in Nextcloud 21.
Upgrading to Nextcloud 20
-------------------------
.. note:: Critical changes were collected `on Github <https://github.com/nextcloud/server/issues/20953>`_. See the original ticket for links to the pull requests and tickets.
.. note:: Critical changes were collected `on GitHub <https://github.com/nextcloud/server/issues/20953>`__. See the original ticket for links to the pull requests and tickets.
Front-end changes
^^^^^^^^^^^^^^^^^
@ -27,7 +206,7 @@ jQuery was updated to v2.2. The most notable change is that ``$(document).ready(
Search
******
The unified search replaces the traditional search input, hence ``OCA.Search`` became a noop. For backwards compatibility, the code will not raise any errors now, but it does not have any functionality.
The :ref:`unified search<unified-search>` replaces the traditional search input, hence ``OCA.Search`` became a noop. For backwards compatibility, the code will not raise any errors now, but it does not have any functionality.
Removed globals
***************
@ -234,7 +413,7 @@ Removed from public namespace
Upgrading to Nextcloud 19
-------------------------
.. note:: Critical changes were collected `on Github <https://github.com/nextcloud/server/issues/18479>`_. See the original ticket for links to the pull requests and tickets.
.. note:: Critical changes were collected `on GitHub <https://github.com/nextcloud/server/issues/18479>`__. See the original ticket for links to the pull requests and tickets.
Front-end changes
^^^^^^^^^^^^^^^^^
@ -280,7 +459,7 @@ Back-end changes
Symfony update
**************
Symfony was updated to `v4.4 <https://github.com/symfony/symfony/blob/4.4/CHANGELOG-4.4.md>`_. The most important change for apps is to return an int value from CLI commands. Returning null (explicitly or implicitly) won't be allowed in future versions of Symfony.
Symfony was updated to `v4.4 <https://github.com/symfony/symfony/blob/4.4/CHANGELOG-4.4.md>`__. The most important change for apps is to return an int value from CLI commands. Returning null (explicitly or implicitly) won't be allowed in future versions of Symfony.
Deprecation of injection of named services
******************************************
@ -325,7 +504,7 @@ Changed APIs
Upgrading to Nextcloud 18
-------------------------
.. note:: Critical changes were collected `on Github <https://github.com/nextcloud/server/issues/17131>`_. See the original ticket for links to the pull requests and tickets.
.. note:: Critical changes were collected `on GitHub <https://github.com/nextcloud/server/issues/17131>`__. See the original ticket for links to the pull requests and tickets.
Front-end changes
^^^^^^^^^^^^^^^^^
@ -378,7 +557,7 @@ Behavioral changes
Upgrading to Nextcloud 17
-------------------------
.. note:: Critical changes were collected `on Github <https://github.com/nextcloud/server/issues/15339>`_. See the original ticket for links to the pull requests and tickets.
.. note:: Critical changes were collected `on GitHub <https://github.com/nextcloud/server/issues/15339>`__. See the original ticket for links to the pull requests and tickets.
Front-end changes
^^^^^^^^^^^^^^^^^
@ -433,14 +612,14 @@ Deprecations
Behavioral changes
^^^^^^^^^^^^^^^^^^
* LDAP: default value for ``ldapGroupMemberAssocAttr`` changed from ``uniqueMember`` to unset. On scripted setups, it has to be set if LDAP groups should be used within Nextcloud.
* LDAP: default value for ``ldapGroupMemberAssocAttr`` changed from ``uniqueMember`` to unset. On scripted setups, it has to be set if LDAP groups should be used within Nextcloud.
* Provisioning API: creating users will return the assigned user ID as dataset, as in ``['id' => $userid]``.
Upgrading to Nextcloud 16
-------------------------
.. note:: Critical changes were collected `on Github <https://github.com/nextcloud/server/issues/12915>`_. See the original ticket for links to the pull requests and tickets.
.. note:: Critical changes were collected `on GitHub <https://github.com/nextcloud/server/issues/12915>`__. See the original ticket for links to the pull requests and tickets.
Front-end changes
^^^^^^^^^^^^^^^^^
@ -490,7 +669,7 @@ Removed APIs
Upgrading to Nextcloud 15
-------------------------
.. note:: Critical changes were collected `on Github <https://github.com/nextcloud/server/issues/15339>`_. See the original ticket for links to the pull requests and tickets.
.. note:: Critical changes were collected `on GitHub <https://github.com/nextcloud/server/issues/15339>`__. See the original ticket for links to the pull requests and tickets.
Front-end changes
^^^^^^^^^^^^^^^^^
@ -533,7 +712,7 @@ Removed APIs
Upgrading to Nextcloud 14
-------------------------
.. note:: Critical changes were collected `on Github <https://github.com/nextcloud/server/issues/7827>`_. See the original ticket for links to the pull requests and tickets.
.. note:: Critical changes were collected `on GitHub <https://github.com/nextcloud/server/issues/7827>`__. See the original ticket for links to the pull requests and tickets.
General
^^^^^^^
@ -633,7 +812,7 @@ Added APIs
Changed APIs
************
* OCS API `getGroup` method replaced by `getGroupUsers` #8904
* OCS API `getGroup` method replaced by `getGroupUsers` #8904
Internal changes

2
developer_manual/basics/backgroundjobs.rst
View File

@ -56,7 +56,7 @@ As you can see our dependency injection also works just fine for background jobs
The ITimeFactory always needs to be passed to the parent constructor. Since it is
required to be set.
In this case it is a background job that runs every hour. And we take the ``uid`` arguemnt
In this case it is a background job that runs every hour. And we take the ``uid`` argument
to pass on to the service to run the background job.
The ``run`` function is the main thing you need to implement and where all the

6
developer_manual/basics/controllers.rst
View File

@ -465,7 +465,7 @@ Public page templates
^^^^^^^^^^^^^^^^^^^^^
For public pages, that are rendered to users who are not logged in to the
Nextcloud instance, a :any:`PublicTemplateResponse <OCP\\AppFramework\\Http\\Template\\PublicTemplateResponse>` should be used, to load 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.
@ -498,9 +498,9 @@ 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 :any:`SimpleMenuAction <OCP\\AppFramework\\Http\\Template\\SimpleMenuAction>` will be a link with an icon added to the menu. App
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 :any:`IMenuAction <OCP\\AppFramework\\Http\\Template\\IMenuAction>` interface.
class implementing the ``OCP\\AppFramework\\Http\\Template\\IMenuAction`` interface.

18
developer_manual/basics/events.rst
View File

@ -1,3 +1,5 @@
.. _Events:
======
Events
======
@ -528,14 +530,14 @@ WARNING: Using this API incorrectly may make the instance more insecure. Do thin
*Available in Nextcloud 18 and later.*
``\OCP\Security\FeaturePolicy\AddFeaturePolicyEvent``
****************************************************
*****************************************************
*Available in Nextcloud 17 and later.*
Event that allows to register a feature policy header to a request.
``\OCP\Share\Events\ShareCreatedEvent``
*******************************************
***************************************
*Available in Nextcloud 18 and later.*
@ -641,24 +643,24 @@ Emitted before a user is logged out.
Emitted when a user has been logged out successfully.
``\OCP\WorkflowEngine\LoadSettingsScriptsEvent``
***************************************
************************************************
*Available in Nextcloud 20 and later.*
Emitted when the workflow engine settings page is loaded.
``\OCP\WorkflowEngine\RegisterChecksEvent``
***************************************
*******************************************
*Available in Nextcloud 18 and later.*
``\OCP\WorkflowEngine\RegisterEntitiesEvent``
***************************************
*********************************************
*Available in Nextcloud 18 and later.*
``\OCP\WorkflowEngine\RegisterOperationsEvent``
***************************************
***********************************************
*Available in Nextcloud 18 and later.*
@ -774,7 +776,7 @@ The following hooks are available:
Session
```````
Injectable from the ServerContainer by calling the method **getUserSession()**.
Injectable from the ServerContainer by calling the method **getUserSession()**.
Hooks available in scope **\\OC\\User**:
@ -825,7 +827,7 @@ Injectable from the ServerContainer by calling the method **getRootFolder()**, *
To enable these events for your app you should add the following to your `info.xml` file:
.. code-block:: xml
<types>
<filesystem/>
</types>

15
developer_manual/basics/front-end/js.rst
View File

@ -109,7 +109,7 @@ and a JS part (that fetches and parses the state).
Providing the initial state with PHP
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Providing state in PHP is done via the ``\OCP\IInitialStateService``. This service
Providing state in PHP is done via the ``OCP\AppFramework\Services\IInitialState``. This service
has two methods you can use to provide the initial state.
* ``provideInitialState(string $appName, string $key, $data)``:
@ -130,6 +130,19 @@ Obtaining the initial state in JavaScript
To obtain the initial state in your JavaScript you have to only call one
function
- Vue way with `@nextcloud/initial-state <https://github.com/nextcloud/nextcloud-initial-state>`_:
.. code-block:: js
import { loadState } from '@nextcloud/initial-state'
const val = loadState('myapp', 'user_preference')
// Provide a fallback value to return when the state is not found
const valWithFallback = loadState('myapp', 'user_preference', 'no_preference')
- Legacy way:
.. code-block:: js
const state = OCP.InitialState.loadState('MyApp', 'MyState');

2
developer_manual/basics/front-end/l10n.rst
View File

@ -119,7 +119,7 @@ There are global functions **t()** and **n()** available for translating strings
.. code-block:: js
t('myapp', 'Hello World!');
t('myapp', '{name} is available. Get {linkstart}more information{linkend}}', {name: 'Nextcloud 16', linkstart: '<a href="...">', linkend: '</a>'});
t('myapp', '{name} is available. Get {linkstart}more information{linkend}', {name: 'Nextcloud 16', linkstart: '<a href="...">', linkend: '</a>'});
n('myapp', 'Import %n calendar into {collection}', 'Import %n calendars into {collection}', selectionLength, {collection: 'Nextcloud'});

3
developer_manual/basics/index.rst
View File

@ -14,4 +14,5 @@ Basic concepts
front-end/index
backgroundjobs
logging
storage/index
storage/index
testing

10
developer_manual/basics/request_lifecycle.rst
View File

@ -2,12 +2,6 @@
Request lifecycle
=================
.. toctree::
:maxdepth: 1
container
api
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>, Morris Jobke <hey@morrisjobke.de>
A typical HTTP request consists of the following:
@ -28,11 +22,11 @@ In the beginning, all requests are sent to Nextcloud's :file:`index.php` which i
* Filesystem
* Logging
The type of the app is determined by inspecting the app's :doc:`configuration file <../info>` (:file:`appinfo/info.xml`). Loading apps means that the :doc:`main file <../init>` (:file:`appinfo/app.php`) of each installed app is being loaded and executed. That means that if you want to execute code before a specific app is being run, you can place code in your app's :doc:`../init` file.
The type of the app is determined by inspecting the app's :doc:`configuration file <../info>` (:file:`appinfo/info.xml`). Loading apps means that the :doc:`main file <../app_development/init>` (:file:`appinfo/app.php`) of each installed app is being loaded and executed. That means that if you want to execute code before a specific app is being run, you can place code in your app's :doc:`../app_development/init` file.
Afterwards the following steps are performed:
* Try to authenticate the user
* Load and execute all the remaining apps' :doc:`../init` files
* Load and execute all the remaining apps' :doc:`../app_development/init` files
* Load and run all the routes in the apps' :file:`appinfo/routes.php`
* Execute the router

27
developer_manual/basics/storage/database.rst
View File

@ -45,6 +45,33 @@ Inside your database layer class you can now start running queries like:
}
Transactions
------------
Database operations can be run in a transaction to commit or roll back a group of changes in an atomic fashion.
.. code-block:: php
<?php
$this->db->startTransaction();
try {
// DB operations
$this->db->commit();
} catch (\Throwable $e) {
// Optional: handle the error
// Important: roll back (or commit) your changes when an error
// happens, so this transaction ends
$this->db->rollBack();
throw $e;
}
.. warning:: Omitting the error handling for transactions will lead to unexpected behavior as any database operations that come after your error will still run in your transaction and due to the lack of a commit PDO will automatically roll-back all changes at the end of the script.
Mappers
-------

4
developer_manual/basics/storage/filesystem.rst
View File

@ -20,7 +20,7 @@ All methods return a Folder object on which files and folders can be accessed, o
<?php
namespace OCA\MyApp\Storage;
use OCP\Files\IRootFolder
use OCP\Files\IRootFolder;
class AuthorStorage {
@ -64,7 +64,7 @@ Files and folders can also be accessed by id, by calling the **getById** method
<?php
namespace OCA\MyApp\Storage;
use OCP\Files\IRootFolder
use OCP\Files\IRootFolder;
class AuthorStorage {

1
developer_manual/basics/storage/index.rst
View File

@ -6,7 +6,6 @@ Storage and database
:maxdepth: 2
migrations
schema
database
configuration
filesystem

28
developer_manual/basics/storage/migrations.rst
View File

@ -70,14 +70,14 @@ With this step the new column gets created:
.. code-block:: php
public function changeSchema(IOutput $output, \Closure $schemaClosure, array $options) {
/** @var Schema $schema */
/** @var ISchemaWrapper $schema */
$schema = $schemaClosure();
$table = $schema->getTable('twofactor_backupcodes');
$table->addColumn('user_id', Type::STRING, [
$table->addColumn('user_id', \OCP\DB\Types::STRING, [
'notnull' => true,
'length' => 64,
'length' => 64,
]);
return $schema;
@ -109,7 +109,7 @@ With this the old column gets removed.
.. code-block:: php
public function changeSchema(IOutput $output, \Closure $schemaClosure, array $options) {
/** @var Schema $schema */
/** @var ISchemaWrapper $schema */
$schema = $schemaClosure();
$table = $schema->getTable('twofactor_backupcodes');
@ -118,30 +118,13 @@ With this the old column gets removed.
return $schema;
}
Migrate from database.xml
-------------------------
To migrate your app from a `database.xml` file to migrations run:
.. code-block:: bash
php ./occ migrations:generate-from-schema <app_id> <version>
This will create a new file under `lib/Migration` that results in the
same database table(s) as your database.xml file.
For version you should use your app versions. So if you app is at version
1.2.3 use 010203.
Don't forget to remove your `database.xml` file.
.. _migration_console_command:
Console commands
----------------
There are some console commands, which should help developers to create or deal
with migrations, which are sometimes only available if you are running your
with migrations, which are only available if you are running your
Nextcloud in debug mode:
* `migrations:execute`: Executes a single migration version manually.
@ -154,6 +137,5 @@ Nextcloud in debug mode:
in another branch. Since you can’t change this retroactive, we recommend to
leave enough space in between and therefore map the numbers to 3 digits:
`1.0.x => 1000`, `2.34.x => 2034`, etc.
* `migrations:generate-from-schema`: Create a migration from the old `database.xml`.
* `migrations:migrate`: Execute a migration to a specified or the latest available version.
* `migrations:status`: View the status of a set of migrations.

56
developer_manual/basics/storage/schema.rst
View File

@ -1,56 +0,0 @@
============================
Database schema (deprecated)
============================
.. warning:: Using the database.xml schema file is deprecated.
You should migrate to using :ref:`Database Migrations <app_db_migrations>`.
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
Nextcloud uses a database abstraction layer on top of either PDO, depending on the availability of PDO on the server.
The database schema is inside :file:`appinfo/database.xml` in MDB2's `XML scheme notation <http://www.wiltonhotel.com/_ext/pear/docs/MDB2/docs/xml_schema_documentation.html>`_ where the placeholders \*dbprefix* (\*PREFIX* in your SQL) and \*dbname* can be used for the configured database table prefix and database name.
An example database XML file would look like this:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8" ?>
<database>
<name>*dbname*</name>
<create>true</create>
<overwrite>false</overwrite>
<charset>utf8</charset>
<table>
<name>*dbprefix*yourapp_items</name>
<declaration>
<field>
<name>id</name>
<type>integer</type>
<default>0</default>
<notnull>true</notnull>
<autoincrement>1</autoincrement>
<length>4</length>
</field>
<field>
<name>user</name>
<type>text</type>
<notnull>true</notnull>
<length>64</length>
</field>
<field>
<name>name</name>
<type>text</type>
<notnull>true</notnull>
<length>100</length>
</field>
<field>
<name>path</name>
<type>clob</type>
<notnull>true</notnull>
</field>
</declaration>
</table>
</database>
To update the tables used by the app, simply adjust the database.xml file and increase the app version number in :file:`appinfo/info.xml` to trigger an update.

2
developer_manual/client_apis/OCS/index.rst
View File

@ -9,4 +9,4 @@ OCS API
ocs-api-overview
ocs-share-api
ocs-sharee-api
ocs-status-api

152
developer_manual/client_apis/OCS/ocs-status-api.rst Normal file
View File

@ -0,0 +1,152 @@
==============
OCS Status API
==============
The OCS Status API allows you to access and modify status API from outside over pre-defined OCS calls.
The base URL for all calls to the share API is: *<nextcloud_base_url>/ocs/v2.php/apps/user_status/api/v1/user_status*
All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``.
User Status - Status Manipulation
---------------------------------
Fetch your own status
^^^^^^^^^^^^^^^^^^^^^
* Required capability: ``user_status``
* Method: ``GET``
* Endpoint: ``/``
* Response:
- Status code:
+ ``200 OK``
+ ``404 Not Found`` If the user does not have a status set
Set your own status
^^^^^^^^^^^^^^^^^^^
* Required capability: ``user_status``
* Method: ``PUT``
* Endpoint: ``/status``
* Data:
field | type | Description | Allowed values
------|------|-------------|---------------|
``statusType`` | string | New status for the authenticated user | ``online``, ``away``, ``dnd``, ``invisible``, ``offline`` |
* Response:
- Status code:
+ ``200 OK``
+ ``400 Bad Request`` If the sent status-type is not valid
Set a custom message (predefined)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Required capability: ``user_status``
* Method: ``PUT``
* Endpoint: ``/message/predefined``
* Data:
field | type | Description
------|------|------------
``messageId`` | string | Message-Id of the predefined message
``clearAt`` | int | Unix Timestamp representing the time to clear the status
* Response:
- Status code:
+ ``200 OK``
+ ``400 Bad Request`` If the sent messageId does not exist
+ ``400 Bad Request`` If the Unix timestamp is in the past
Set a custom message (user-defined)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Required capability: ``user_status``, ``supports_emoji`` for ``statusIcon`` support
* Method: ``PUT``
* Endpoint: ``/message/custom``
* Data:
field | type | Description
------|------|------------
``statusIcon`` | string/null | The icon picked by the user (must be an emoji, at most one)
``message`` | string | The custom message picked by the user
``clearAt`` | int | Unix Timestamp representing the time to clear the status
* Response:
- Status code:
+ ``200 OK``
+ ``400 Bad Request`` If the `statusIcon` is not a an emoji or more than one emoji
+ ``400 Bad Request`` If the `message` is too long
+ ``400 Bad Request`` If the Unix timestamp is in the past
Clear message
^^^^^^^^^^^^^
* Required capability: ``user_status``
* Method: ``DELETE``
* Endpoint: ``/message``
* Response:
- Status code:
+ ``200 OK``
User Status - Predefined statuses
---------------------------------
Base endpoint ics: ``/ocs/v2.php/apps/user_status/api/v1/predefined_statuses``
Fetch the list of predefined statuses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Required capability: ``user_status``
* Method: ``GET``
* Endpoint: ``/``
* Response:
- Status code:
+ ``200 OK``
User Status - Retrieve statuses
-------------------------------
Base endpoint ics: ``/ocs/v2.php/apps/user_status/api/v1/statuses``
Fetch a list of all set user-statuses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Required capability: ``user_status``
* Method: ``GET``
* Endpoint: ``/``
* Data:
field | type | Description
------|------|------------
``limit`` | int | Limit for pagination
``offset`` | int | Offset for pagination
* Response:
- Status code:
+ ``200 OK``
Fetch a specific user's status
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Required capability: ``user_status``
* Method: ``GET``
* Endpoint: ``/{userId}``
* Response:
- Status code:
+ ``200 OK``
+ ``404 Not Found`` If the user does not have a status set
Files Sharing
^^^^^^^^^^^^^
The user-status is also exposed via the following Files Sharing APIs:
* ``GET /ocs/v2.php/apps/files_sharing/api/v1/sharees``
* ``GET /ocs/v2.php/apps/files_sharing/api/v1/sharees_recommended``
* ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares``
* ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares/inherited``
* ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares/pending``
* ``GET /ocs/v2.php/apps/files_sharing/api/v1/shares/{id}``
* ``POST /ocs/v2.php/apps/files_sharing//api/v1/shares``
* ``PUT /ocs/v2.php/apps/files_sharing/api/v1/shares/{id}``

10
developer_manual/client_apis/WebDAV/comments.rst
View File

@ -1,9 +1,12 @@
## Comments
########
Comments
########
Comments have a PHP API within OCP and also via WebDAV. Basic documentation below.
### Endpoint
Endpoint
^^^^^^^^
The Comments resource has an endpoint:
@ -27,7 +30,8 @@ The `CommentID` endpoint accepts:
For a list of properties, see:
`https://github.com/nextcloud/server/blob/master/apps/dav/lib/Comments/CommentNode.php#L108`
### Examples of usage
Examples
********
REPORT request:

1
developer_manual/client_apis/WebDAV/index.rst
View File

@ -5,6 +5,7 @@ Webdav
======
.. toctree::
:maxdepth: 2
basic
search

6
developer_manual/client_apis/activity-api.rst
View File

@ -1 +1,5 @@
Find the documentation in the Activities repo here: `https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md`
============
Activity API
============
Find the documentation in the `Activity app repo <https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md>`__.

4
developer_manual/client_apis/index.rst
View File

@ -12,7 +12,7 @@ Clients and Client APIs
OCS/index
LoginFlow/index
RemoteWipe/index
ocs-share-api
ocs-sharee-api
OCS/ocs-share-api
OCS/ocs-sharee-api
activity-api

1
developer_manual/core/index.rst
View File

@ -9,7 +9,6 @@ Please make sure you have set up a :ref:`devenv`.
.. toctree::
:maxdepth: 2
translation
unit-testing
externalapi
../how_to/index

22
developer_manual/core/unit-testing.rst
View File

@ -8,27 +8,9 @@ PHP unit testing
Getting PHPUnit
^^^^^^^^^^^^^^^
Nextcloud uses PHPUnit >= 4.8 for unit testing.
Nextcloud uses PHPUnit >= 8.5 for unit testing.
To install it, either get it via your package manager::
sudo apt-get install phpunit
or install it manually::
wget https://phar.phpunit.de/phpunit.phar
chmod +x phpunit.phar
sudo mv phpunit.phar /usr/local/bin/phpunit
After the installation the **phpunit** command is available::
phpunit --version
And you can update it using::
phpunit --self-update
You can find more information in the PHPUnit documentation: https://phpunit.de/manual/current/en/installation.html
PHPUnit documentation: https://phpunit.de/documentation.html
Writing PHP unit tests
^^^^^^^^^^^^^^^^^^^^^^

295
developer_manual/design/atomiccomponents.rst Normal file
View File

@ -0,0 +1,295 @@
Atomic components
=================
.. _Buttons:
Buttons
-------
Buttons are used to initiate actions in your app. This may be a primary action, or it may be used to confirm an action in a dialog, or simply be used for any major action in your app.
There are generally different types of buttons for different purposes:
.. image:: ../images/button-primary-secondary.png
:alt: Primary button "Move" and secondary button "Copy" in Files
* Primary buttons are used to indicate the main action ("Start call" button in Talk, "Move" in Files). The primary buttons are stylized in Nextcloud blue by default or the theming color when themed. These should only be used sparingly and ideally only for 1 visible action at a time.
* Secondary buttons are used for actions that have lesser weight than the primary action ("Today" button in Calendar, "Copy" in Files)
.. image:: ../images/button-tertiary.png
:alt: Tertiary button "Mark as read" in desktop tray menu
* Tertiary buttons, which are the buttons without a background, can be used for other actions in your app which are important, but not the main focus. These buttons are usually combined with a primary or secondary button. For example, "Mark as read" is a tertiary button used alongside a secondary button
.. image:: ../images/button-icon-only.png
:alt: Mute, video, screenshare and 3-dot buttons in Talk video call
* The icon-only buttons can be used if the action is frequently used and the icon is easily recognizable, and therefore does not require any text to support it (mute/video/screenshare actions in Talk, and the 3-dot menu icon)
.. image:: ../images/button-success.png
:alt: Success button "Join call" in Talk
* Success buttons are used for a positive action ("Join call" button in Talk)
.. image:: ../images/button-danger.png
:alt: Danger button "Remove email" in Mail
* Danger buttons are used to signify a potentially dangerous or negative action ("Remove account" button in the confirmation dialog when you want to remove an account in Mail, or "Delete conversation" in Talk conversation settings)
.. _Action menu:
Action menu
-----------
.. image:: ../images/action-menu.png
:alt: Files action menu
The action menu contains commonly used actions associated with an item. Each entry in the action menu has some text accompanied by a suitable icon. In some cases, the action menu may also contain:
.. image:: ../images/action-menu-checkbox.png
:alt: Checkbox in action menu in Mail
* checkboxes to quickly toggle a state, like in Mail
.. image:: ../images/action-menu-radio-button.gif
:alt: Radio button in action menu in Talk
* radio buttons to select from a few options, like chat notifications in Talk
.. image:: ../images/action-menu-new-item.gif
:alt: Add new mailbox in Mail action menu
* new entry elements to quickly add items, like add a new mailbox in Mail
.. image:: ../images/action-menu-second-level.gif
:alt: Second level of actions in action menu to set due date reminders in Deck
* a second level of actions, like due date reminders in Deck
Some commonly used actions in the action menu are favoriting, renaming, downloading and deleting. Delete should always be at the last position as to not be confused with other actions.
It is important to keep the action menu simple and its length at a minimum. Too many entries in the action menu can lead to confusion and people not finding what they are looking for.
.. image:: ../images/action-menu-icon.png
:alt: Action menu with a paperclipicon for attachments in Talk
In most cases the action menu is accessed through a 3-dot menu. In certain cases, it is better to use a specific icon instead of the generic 3-dot icon. For example in Talk a paperclip icon is used for accessing the action menu for attaching an item, and a heading icon is used in Text formatting bar for heading level selection.
`Action menu Vue component <https://nextcloud-vue-components.netlify.app/#/Components/Actions>`_.
For Android and iOS, the action menu is generally opened as a bottom sheet.
.. _Input fields:
Input fields
------------
.. _Text input:
Text input
^^^^^^^^^^
.. image:: ../images/talk-text-input.png
:alt: Talk text input
.. image:: ../images/text-input-label.png
:alt: Text input with label in settings
Text inputs are usually used for free-form inputs. Make sure that the label for a text input field is simple and clear. It may also be a good idea to use placeholder text in the field.
.. _Dropdowns:
Dropdowns
^^^^^^^^^
.. image:: ../images/dropdown-find-as-you-type.gif
:alt: Dropdown menu in settings
Dropdowns allow the user to select one or more items from a list. Dropdowns can have predefined options from which the user can select one or more items, as seen in Contacts for selecting the type of a phone number. If there are not too many entries, you may also think about using a set of :ref:`checkboxes and radio buttons` instead.
Although not always necessary, it is generally a good idea to have a default item already selected, especially when a dropdown menu is a key element which will be used a lot. This can be decided by a number of factors such as most selected item for that user, most recently selected item, etc. For example, when you add a new phone number in Contacts, the type "Home" is automatically set in the dropdown.
Another variation of the dropdown allows the user to find their preferred option by typing it in, like in Mail where the "To" field in the composer allows you to type an email address, and as you type it shows a dropdown with the results matching the input. This kind of dropdown is useful for when there are many options and the user would already know what they are looking for. It can also be a good idea to allow new inputs if there are no matches.
`Dropdown Vue component <https://nextcloud-vue-components.netlify.app/#/Components/Multiselect>`_.
.. _Checkboxes and radio buttons:
Checkboxes and radio buttons
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: ../images/checkboxes-settings.png
:alt: Checkbox in Talk settings
.. image:: ../images/radiobuttons-settings.png
:alt: Radio buttons in Mail settings
Checkboxes and radio buttons are very common input methods. They are most commonly used in the :ref:`action menu`, :ref:`sidebar` and :ref:`settings`.
They should have a concise label, especially if they are inside an action menu. If more explanation is needed, you can also add a subline.
`Checkbox and radio button Vue components <https://nextcloud-vue-components.netlify.app/#/Components/CheckboxRadioSwitch>`_.
Pickers
-------
.. _Datetime picker:
Datetime picker
^^^^^^^^^^^^^^^
.. image:: ../images/files-date-picker.png
:alt: Files date picker
A user can quickly select dates, times and date ranges using the datetime picker. Use good default dates relevant to the task at hand. For example, in the case of setting an expiration date, unless the server has something enforced as default, 1 week is a good default.
`Datetime picker Vue component <https://nextcloud-vue-components.netlify.app/#/Components/Pickers?id=datetimepicker>`_.
.. _Color picker:
Color picker
^^^^^^^^^^^^
.. image:: ../images/colour-picker.gif
:alt: Deck color picker
For certain elements of your UI you might want to allow people to set colors. This can easily be achieved using a color picker with some predefined colors. Be cautious about using different colors in the UI. In most Nextcloud apps like Deck and Calendar, user defined colors for UI elements are used sparingly and shown as a circle next to the element they refer to.
`Color picker Vue component <https://nextcloud-vue-components.netlify.app/#/Components/Pickers?id=colorpicker>`_.
In addition to these 2 pickers, there is also the `emoji picker <https://nextcloud-vue-components.netlify.app/#/Components/Pickers?id=emojipicker>`_ and the `timezone picker <https://nextcloud-vue-components.netlify.app/#/Components/Pickers?id=timezonepicker>`_ which can be also be used in your app.
.. _Tags:
Tags
----
.. image:: ../images/mail-tags.png
:alt: Mail tags
Tags are used by users to manage their items. They can be colored for easy identification, but make sure to use subtle colors if colored tags are a main part of the UI, as seen in Mail.
.. _Modal:
Modal
-----
.. image:: ../images/deck-card-modal.png
:alt: Deck card modal
A modal is an element on top of the main UI, and interaction with the main element is disabled.
The modal is used when there is a specific task or information that the user needs to focus on. Modals are a good idea if the showing some information on the main UI would clutter the UI too much, and the information does not necessarily depend on the UI. Modals are also used for confirmation when performing dangerous tasks such as permanent deletion.
Examples of modals are:
* Settings modal found in Talk and Mail
* the modal view for a card in Deck
* Move or copy dialog in Files
* the file picker in Mail and Talk
`Modal Vue component <https://nextcloud-vue-components.netlify.app/#/Components/Modal>`_.
On Android and iOS, content which is in a modal would usually be shown as a full-screen overlay, like for example composing a new mail in `iOS Mail <https://developer.apple.com/documentation/messageui/mfmailcomposeviewcontroller>`_.
.. _Avatar:
Avatar
------
.. image:: ../images/avatar-talk.gif
:alt: Avatars in Talk
An avatar is used when referring to any user and displays their photo or initials. The avatar component also shows a menu for that user when clicked.
When using an avatar it is usually accompanied by the name of the user as well, and sometimes it can also show the status of the user, although not always necessary. Statuses can be useful when the user is interacting with another user and is expecting a response, for example when @mentioning someone else in Talk, or in any sharing view.
When multiple people are working on or are assigned to the same element, like in Text, Office, a Deck card, or in the Files list for sharing, they are shown as overlapped.
`Avatar Vue component <https://nextcloud-vue-components.netlify.app/#/Components/Avatar>`_.
.. _Progress bars and meters:
Progress bars and meters
------------------------
.. image:: ../images/progress-bar.png
:alt: Desktop syncing progress bar
Progress bars shows progress for a potentially lengthy process such as uploading, downloading, or syncing. When using a progress bar it can also be a good idea to have a text-based indication of the progress, such as percentage or time remaining, and make sure to provide feedback when the process has been completed.
.. image:: ../images/meter-settings.png
:alt: Meter in Files for storage quota
The progress bar component is also sometimes used as a meter to visualize data as seen in the settings for Files to show the quota.
`Progess bar Vue component <https://nextcloud-vue-components.netlify.app/#/Components/ProgressBar>`_.
.. _User bubbles:
User bubbles
------------
.. image:: ../images/talk-user-bubble.png
:alt: Talk user bubble
When referring to a user inline in your app, a user bubble element can be used. In Talk and Comments, user bubbles are used in the content when someone mentions a user. In Mail, it is used in the header for the recipients of the message.
`User bubble Vue component <https://nextcloud-vue-components.netlify.app/#/Components/UserBubble>`_.
.. _Tooltips:
Tooltips
--------
.. image:: ../images/tooltip.png
:alt: Tooltip in Files
Tooltips are small elements which appear on hover and contain information about the element. Although not necessary for every action or item on the screen, tooltips are great for providing extra information or when an element is too small for the text contained in it.
Using many tooltips is not advised, and if your app does this, possibly consider instead using text labels for icons, reducing the number of actions, or if the info in the tooltip is needed at all.
`The tooltip Vue component can be found here as a directive <https://nextcloud-vue-components.netlify.app/#/Directives>`_.
.. _Empty content:
Empty content
-------------
.. image:: ../images/empty-content.png
:alt: Bookmarks empty content
The empty content state provides feedback that a view is empty, e.g. a new folder. This is to differentiate it from the state of loading, or having loaded and showing data.
Make sure that empty content views only show when the view is really empty, and not while it is loading – otherwise people will be shocked as to where their data is gone. The wording on the empty content view should be friendly and helping people out of the situation, for example in the Bookmarks app.
`Empty content component <https://nextcloud-vue-components.netlify.app/#/Components/EmptyContent>`_.
.. _Skeleton screens:
Skeleton screens
----------------
.. image:: ../images/skeleton-screen-talk.png
:alt: Talk skeleton screen
:scale: 50%
While the app is loading, it is best to show a skeleton view of the apps probable contents as loading feedback. A good example for this is Talk on web as well as Files and Talk on Android.

182
developer_manual/design/foundations.rst Normal file
View File

@ -0,0 +1,182 @@
===========
Foundations
===========
There are several design elements that are common to all Nextcloud apps. If you are developing for a platform that has its own design specifications, for example Android, it would be a good idea to keep those in mind while designing your app.
Color
-----
Primary color
^^^^^^^^^^^^^
.. figure:: ../images/colour-primary.svg
#0082C9
While this is the primary color associated with Nextcloud and can be used to draw attention to an element, it is best to limit the usage of this to primary actions and other important elements.
.. note::
The primary color can be customized by admins through theming, but the default experience will be Nextcloud blue. If the primary color is themed to something very light like a shade of yellow, the text or header icons will be inverted to dark automatically.
Background color
^^^^^^^^^^^^^^^^
.. list-table::
* - .. figure:: ../images/colour-main-background.svg
Background for light theme: #FFFFFF
- .. figure:: ../images/colour-dark-theme-main-backgroud.svg
Background for dark theme: #181818
Nextcloud apps have a light and a dark theme, with appropriately chosen colors for all elements.
* On web: ``var(--color-main-background)``
* Android: uses default Material Design colors
* iOS: `systemBackground <https://developer.apple.com/documentation/uikit/uicolor/3173140-systembackground>`_
* Desktop: default Qt guidelines
Text color
^^^^^^^^^^
.. list-table::
* - .. figure:: ../images/colour-main-text.svg
Text in light theme: #222222
- .. figure:: ../images/colour-dark-theme-main-text.svg
Text in dark theme: #D8D8D8
This is the main color for the text in light theme, and in dark theme.
* On web: ``var(--color-main-text)``
* Android: uses default Material Design color "high emphasis"
* iOS: `label <https://developer.apple.com/documentation/uikit/uicolor/3173131-label>`_ (in UITextView, leave the default textColor)
* Desktop: default Qt guidelines
.. list-table::
* - .. figure:: ../images/colour-text-maxcontrast.svg
Secondary text in light theme: #767676
- .. figure:: ../images/colour-dark-theme-text-maxcontrast.svg
Secondary text in dark theme: #8C8C8C
In addition, a softer color is used for secondary text like sublines, timestamps, and similar.
* On web:``var(--color-text-maxcontrast)``
* Android: uses default Material Design color "medium emphasis"
* iOS: `secondaryLabel <https://developer.apple.com/documentation/uikit/uicolor/3173136-secondarylabel>`_
* Desktop: `default Qt guidelines <https://doc.qt.io/qt-5/qpalette.html#ColorRole-enum>`_
Status and indicators
^^^^^^^^^^^^^^^^^^^^^
.. list-table::
* - .. figure:: ../images/colour-success.svg
Success: #46BA61
- .. figure:: ../images/colour-error.svg
Error: #E9322D
- .. figure:: ../images/colour-warning.svg
Warning: #ECA700
Interface elements associated with a status like success, error, or warning may also be colored to communicate the action better.
While interface elements like buttons are colored differently depending on their action, the color of the text in that element is almost always either of the main text colors, that is light or dark.
* On web:
* Success colour: ``var(--color-success)``
* Warning colour: ``var(--color-warning)``
* Error colour: ``var(--color-error)``
* Android: Material Design guidelines
* iOS: `Apple HIG colors <https://developer.apple.com/design/human-interface-guidelines/ios/visual-design/color/>`_
* success: systemGreen
* error: systemRed
* Desktop: `default Qt guidelines <https://doc.qt.io/qt-5/qpalette.html#ColorRole-enum>`_
Typography
----------
To ensure compatibility with different platforms, Nextcloud apps always use the native system font.
For legibility, make sure that the text in your content uses:
* **Bold** for emphasis
* A line height between 130% and 150%
* The default tracking of the font
* No *italics* or UPPER CASE as these text styles are less legible
The text sizes for the different platforms are:
* Web: 15px for main text and sublines, **20px bold** for headings
* Android: 14sp for main text, 16sp for headings
* iOS: values from `Dynamic Type Sizes, for size Large (Default) <https://developer.apple.com/design/human-interface-guidelines/ios/visual-design/typography#dynamic-type-sizes>`_
* Desktop: `default Qt guidelines <https://doc.qt.io/qt-5/qpalette.html#ColorRole-enum>`_
Icons
-----
.. image:: ../images/material-icons.png
:alt: Material icons
Icons can be used to communicate the intent of an action, or to provide visual interest to the screen. We use monochrome icons on all platforms: `Material Design icons (20 px default filled) <https://fonts.google.com/icons>`_ for web, Android, Windows and Linux, and `SF Symbols (default weight, scale and variant) <https://developer.apple.com/sf-symbols/>`_ for iOS and macOS.
This is except for the icon of the app itself, which can be a custom icon.
Make sure to:
* Not overuse icons
* When possible, use text together with icons so it’s clear what they refer to
* For special cases like warnings, combine the icon with color to enhance its visibility
Naming
------
To be immediately understandable, we choose app names which are generic and easily translatable. Additionally, they are short and easily fit in the top navigation without being cut off.
Files, Contacts, Calendar, and Mail do not need further explanation, which is why we recommend to choose a self-explanatory app name.
Further good examples of this: Notes, Bookmarks, Maps, Forms, Tasks, Music.
Wording
-------
The wording and language in your app sets the tone and approachability of your app.
* Nextcloud should always be written out, and only with a capital N. Not "NextCloud" or "Nc".
* Be friendly and approachable, not condescending.
* Use understandable language, not technical jargon. For example, "link" is much better than "URL", and explaining errors is better than showing error codes.
* Don’t write in ALL CAPS, as it is not as readable and comes off as shouting and aggressive. Also use Sentence case and not Capital Case, with the exception of product names like Nextcloud Talk, Nextcloud Hub, etc.
* We are a community, so better write "We are happy to announce" instead of "I am happy to announce".
* If your app content is empty, it can be helpful to add an engaging message. "Add or import your first bookmark!" is much nicer than "No bookmarks yet".
* Try to avoid using "my" or "your" like in "My files" or "Your files", instead using "All files". For longer sentences where it cannot be avoided, use "your", never "my".
* For any "Delete" action, give context to what it will delete, like "Delete conversation" or "Delete user" so that it is clear specifically for this destructive action.
* Keep language short and concise, and keep in mind that it should be easily translatable.
* Make sure to spellcheck anything you write.

21
developer_manual/design/index.rst
View File

@ -1,13 +1,12 @@
=================
Design guidelines
=================
===========================
Nextcloud design guidelines
===========================
.. toctree::
.. toctree::
:maxdepth: 2
navigation
content
list
popovermenu
html
css
icons
introduction
foundations
layout
layoutcomponents
atomiccomponents

25
developer_manual/design/introduction.rst Normal file
View File

@ -0,0 +1,25 @@
.. _navigation:
.. _newbutton:
============
Introduction
============
Nextcloud design and brand standards are used to maintain the identity of Nextcloud apps. If you're a developer who wants to create or contribute to a Nextcloud app, following this guide will make sure your app looks like it belongs to the Nextcloud family.
Each Nextcloud app is unique and different, but there are a couple of standards that are used in everything. All Nextcloud apps are built keeping some basic principles in mind.
* Software should be quick and easy to use. Show only the most important elements. Secondary elements can be showed on hover or via an "Advanced" function.
* Nextcloud apps are built for everybody. Use a friendly tone with simple sentences. Make sure your app is responsive and runs on all browsers and devices.
* Accessibility: Make sure to regularly test accessibility, for example with `Lighthouse <https://developers.google.com/web/tools/lighthouse>`_\ , `WAVE <https://wave.webaim.org/>`_\ , and `Google Accessibility Scanner <https://play.google.com/store/apps/details?id=com.google.android.apps.accessibility.auditor>`_. Aim for WCAG Level AA. You can learn more about accessibility standards in the `W3 website <https://www.w3.org/WAI/standards-guidelines/wcag/glance/>`_
* Software should work. Only put features into master when they are complete. It is better to not have a feature instead of having one that works poorly.
* Software should get out of the way. Do things automatically instead of offering configuration options. When people ask for a setting, find out what the root of the problem is and fix that instead. Also read `Choosing our Preferences <http://ometer.com/preferences.html>`_.
* People’s data is sacred. Provide undo for most operations and optionally a confirmation for bigger more complex operations, but be careful about confirmations `as they might be dismissed <http://www.alistapart.com/articles/neveruseawarning/>`_.
* The state of the application should be clear. If something loads, provide feedback. Reactions should be quick, ideally under 100ms as per `response time limits <https://www.nngroup.com/articles/response-times-3-important-limits/>`_\.
* The state of the application should be clear. If something loads, provide feedback.
* Regularly reset your installation to see what the first-run experience is like, and improve it.
* Ideally do `usability testing <http://jancborchardt.net/usability-in-free-software>`_ to know how people use the software. Testing with 5 users is enough to identify most of your problems.
For further UX principles, read `Alex Faaborg from Mozilla <http://uxmag.com/articles/quantifying-usability>`_\ , and the `GNOME Human Interface Guidelines <https://developer.gnome.org/hig/stable/design-principles.html.en>`_

72
developer_manual/design/layout.rst Normal file
View File

@ -0,0 +1,72 @@
Layout
======
These layout guidelines mainly focus on our web interface. On Android and iOS we closely follow the platform guidelines, namely `Material Design <https://material.io/design>`_\ , and `Apple Human Interface Guidelines <https://developer.apple.com/design/human-interface-guidelines/>`_.
While deciding how you want your app to look, there are a number of factors to consider:
* Consistency with other Nextcloud apps
* Responsiveness for different browsers, browser sizes and devices
* Typical interface patterns in other similar apps in the market
The `content Vue component <https://nextcloud-vue-components.netlify.app/#/Components/App%20containers?id=content>`_ wraps your entire app. While the arrangement of components in your app is dependent on what your app does, most Nextcloud apps typically have 3 levels of hierarchy. Some commonly used layouts are:
* Navigation → content → sidebar (and a couple of variations of it, e.g. without the sidebar)
* Navigation → list → content
Navigation → Content → Sidebar
------------------------------
.. image:: ../images/files-layout.png
:alt: Files layout
This layout is used in Files, Calendar, Deck, and Tasks.
This layout has the :ref:`Navigation` on the left, the :ref:`Content` in the middle, and a :ref:`Sidebar` on the right. The main content depends on the navigation, and the sidebar which is closed by default contains details of an item in the main content.
For example, in the Files app, the files in the main content varies based on what is selected in the navigation. The sidebar would open when the user wants to see the details of a file.
On mobile, the content is shown by default. The navigation and sidebar are expandable using icons on the sides.
Special case: no sidebar
^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: ../images/activity-layout.png
:alt: Activity layout
Typically, a sidebar is used to show more information about an item. Sometimes this is not necessary as in the case of Activities. Then, the layout will have only a navigation and the main content.
Special case: list in navigation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. image:: ../images/talk-layout.png
:alt: Talk layout
Another variation of this layout is where the :ref:`List` of entries take up the left space instead of navigation, as seen in Talk. It shows the list of chats on the left, and the main content contains the messages in a chat, while opening the right sidebar shows the details of a chat like the description and participants. Talk also collapses the left list and right sidebar during a video call, so that the entire screen is taken up by just the call.
Navigation → List → Content
---------------------------
.. image:: ../images/mail-layout.png
:alt: Mail layout
This layout is used in Mail and Contacts.
In this layout, the 3 levels of hierarchy are shown by default. On the left there is the :ref:`Navigation`, right next to it is a :ref:`List` of entries for the navigation chosen, and the main content is for the entry selected in the list.
A good example of this layout is in the Mail app. The left navigation section contains the different inboxes and categories. The list then shows the emails of the selected inbox or folder and the main content shows the contents of the email which is currently open.
On mobile, the list is shown by default. The navigation is expandable using an icon in the top left, and the content can be opened by selecting an entry from the list. Navigation back up from a content can be done via a "Back" arrow action in the top left, in place of the navigation icon.

183
developer_manual/design/layoutcomponents.rst Normal file
View File

@ -0,0 +1,183 @@
Layout components
=================
All Nextcloud apps are built using individual reusable components for consistency and efficiency. Currently, these components are written in Vue and can be found at the `nextcloud-vue repository on Github <https://github.com/nextcloud/nextcloud-vue/>`_ with the documentation available at `the Nextcloud Vue components style guide <https://nextcloud-vue-components.netlify.app/>`_.
.. _Navigation:
Navigation
----------
.. image:: ../images/contacts-navigation.png
:alt: Contacts navigation
The left navigation provides a way for users to move around different sections of your app.
`Vue component for the app navigation <https://nextcloud-vue-components.netlify.app/#/Components/App%20containers/AppNavigation?id=appnavigation-1>`_.
The navigation consists of 4 main elements:
* Main action button
* Navigation entries
* New item element (optional)
* Settings menu (optional)
Main action button
^^^^^^^^^^^^^^^^^^
.. image:: ../images/mail-primary-action-button.png
:alt: Mail primary action button.png
For most apps, the first element in the navigation is the main action button. For example:
* Mail has a "New message" button to compose a new mail
* Contacts has a "New contact" button
* in Talk, you can create a new conversation
* in Calendar there is a "New event" button
* Forms has a "New form" action
Navigation entries
^^^^^^^^^^^^^^^^^^
.. image:: ../images/mail-navigation-entries.png
:alt: Mail navigation entries
The different sections of your app would be organized by different navigation entries. For example, the Files app contains different categories of files in its navigation, and the Contacts app contains different groups and circles. When creating your navigation, make sure that the entries in this section:
* are easy to understand
* are frequently used
* are organized
* do not change positions frequently
Top-level navigation entries ideally have a suitable icon left next to them. Optionally they may also have:
* a 3 dot action menu (seen in Mail)
* a counter (seen in Contacts and Mail)
A sublevel of navigation is possible, but can lead to entries being hard to discover. It is only advised if there is actually a hierarchy like for folders in Mail or News.
`Navigation entries Vue component <https://nextcloud-vue-components.netlify.app/#/Components/App%20containers/AppNavigation?id=appnavigationitem>`_.
New item element
^^^^^^^^^^^^^^^^
.. image:: ../images/new-item-element.gif
:alt: Add new item element
Users can easily create a new item with a suitable name by using the new item element. This element can be used in the navigation, as in the case of Deck, or in the content. Other apps which use this:
* "Create a new group" in Contacts
* "Add mailbox" in Mail
* "New calendar" in Calendar
`New item Vue component <https://nextcloud-vue-components.netlify.app/#/Components/App%20containers/AppNavigation?id=appnavigationnewitem>`_.
.. _Settings:
Settings
^^^^^^^^
.. image:: ../images/talk-settings-modal.png
:alt: Talk settings modal
The user-specific settings for your app may be shown in a settings modal, which can be accessed through a settings entry at the bottom of the navigation. Try to keep the settings to a minimum, as too many configurable options can be a burden to the user. If no settings are needed for the app, that is great and the settings modal can be omitted. Within the modal, categorizing your settings can sometimes offer a better experience if you have a lot of settings. If this is required, the categories are placed in the left of the settings modal.
You can also include a "Help" as an entry in the settings of your app and provide some simple information about your app and how to use it. Some apps like Talk and Mail also include keyboard shortcuts.
`Settings Vue component <https://nextcloud-vue-components.netlify.app/#/Components/App%20containers/AppNavigation?id=appnavigationsettings>`_.
Also see: :ref:`Modal`
.. _List:
List item
----------
.. image:: ../images/list-item.gif
:alt: Talk list
List items can be used to display a collection of elements from which one can be selected. List items are seen in the left list of chats in Talk, as well as the list of messages in Mail and the list of contacts in Contacts. List items usually have an avatar or a descriptive icon, a main line and optionally a subline. A list item may also contain:
* an :ref:`Action menu` which has commonly used actions for that type of item
* a counter bubble: Talk for example uses an unread messages counter
`List item Vue component <https://nextcloud-vue-components.netlify.app/#/Components/List%20items>`_.
.. _Content:
Content
-------
The content section of your app takes up the most screen space, and is the core of what your app does. The content of every app is unique, but do make sure that it follows some basic rules like responsiveness, accessibility, and support in different languages so that it can be used by everyone. The layout of your content depends on what your app does, as the content of almost every Nextcloud app looks different. The `appContent Vue component <https://nextcloud-vue-components.netlify.app/#/Components/App%20containers?id=appcontent>`_ should be used for the content of your app.
Views
^^^^^
Some apps offer different views on their content so people can pick a preference which should be remembered automatically. It is important to consider which should be the default one and whether to have different views at all, since most people do not change the default.
* Files (web, Android & iOS), Bookmarks: List view or grid view
* Calendar: Month view, week view, day view, list view / agenda
* Talk (web, Android & iOS): Speaker view and grid view in a call
The content is also the section where you can quickly explain to people how to get started with your app, for example using an :ref:`Empty content` atomic component.
Sizing
^^^^^^
For text-based apps like chat, mails, and other paragraphs of text, the width of the content should not go over a certain width to facilitate readability. In Nextcloud Text for example the width is limited to 650px and we do it similarly in Mail and Talk, even if the screen size is larger.
For every clickable element in your interface, make sure it has a minimum clickable area of at least 44px by 44px (48px for Android). Anything smaller than this will make your app inaccessible and difficult for users to use your app on mobile as they might miss while trying to tap on the element.
Spacing between elements in your app should be in multiples of 4px.
.. _Sidebar:
Sidebar
-------
Details of a particular entry in your content, as well as some actions associated with it, are shown in the right sidebar. In apps where the sidebar is used, it only opens when required. The sidebar is never used in the 3-column layout (Navigation + list + content). It contains the main information and sometimes a preview of the selected item, as well as a maximum of 3 possible tabs.
`Sidebar Vue component <https://nextcloud-vue-components.netlify.app/#/Components/App%20containers?id=appsidebar>`_.
Commonly used tabs in the sidebar are:
Details
^^^^^^^
.. image:: ../images/sidebar-details.png
:alt: Details tab in Calendar sidebar
The details tab contains information about the entry it refers to, which is often editable using various input fields. The details included here will depend upon your app. For example, the details tab in the sidebar of the Calendar app contains information about the selected event, like location, description, and status. Also see :ref:`Input fields` in the atomic components section for more details about the various input fields that can be used here.
Activity
^^^^^^^^
Major changes done to the selected item, as well as comments left by users, are shown in the activity tab. These details are shown by latest activity up top.
If your app includes comment support, the "Write comment" input box should be placed here so it is nicely integrated.
If there is the possibility to restore earlier versions, this can be integrated using a 3-dot action menu on any past activity.
Sharing
^^^^^^^
.. image:: ../images/sidebar-sharing.png
:alt: Proposed sharing tab in the sidebar
The sharing tab allows users to share the selected item with others in different ways. An item can be shared with specific users or groups on the instance by simply selecting whom you want to share with. Another very simple way of sharing is through a share link, which can optionally also be configured using the "Advanced settings" option.

2
developer_manual/digging_deeper/classloader.rst
View File

@ -5,7 +5,7 @@ Classloader
===========
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
The classloader is provided by Nextcloud and loads all your classes automatically. The only thing left to include by yourself are 3rdparty libraries. Those should be loaded in :file:`lib/AppInfo/Application.php`.
The classloader is provided by Nextcloud and loads all your classes automatically. See :ref:`the composer section<app-composer>` if you want to include and autoload 3rd party libraries.
PSR-4 autoloading
-----------------

56
developer_manual/digging_deeper/continuous_integration.rst
View File

@ -1,3 +1,5 @@
.. _app-ci:
======================
Continuous Integration
======================
@ -11,6 +13,58 @@ We highly recommend setting up automated tests for your app, so that every chang
* Unit testing: run unit tests for front-end and back-end where individual classes and components are tested in isolation
* Integration testing: test components when they are combined
You can find a list of available github workflow templates in our `nextcloud template repository <https://github.com/nextcloud/.github>`_.
Linting
-------
info.xml
^^^^^^^^
You can validate the ``info.xml`` :ref:`app metadata<app metadata>` file of an app with a simple github action:
.. code-block:: yaml
name: Lint
on: pull_request
jobs:
xml-linters:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@master
- name: Download schema
run: wget https://apps.nextcloud.com/schema/apps/info.xsd
- name: Lint info.xml
uses: ChristophWurst/xmllint-action@v1
with:
xml-file: ./appinfo/info.xml
xml-schema-file: ./info.xsd
php
^^^
A lint of all php source files can find syntax errors that could crash the application in production. You can find the github actions in our `nextcloud template repository <https://github.com/nextcloud/.github>`_.
You will also require the following lint script in your ``composer.json``:
.. code-block:: json
{
"scripts": {
"lint": "find . -name \\*.php -not -path './vendor/*' -print0 | xargs -0 -n1 php -l"
}
}
php-cs
^^^^^^
We encourage the usage of php-cs linting. You can find some documentation on how to set this up in the
`nextcloud coding-standard repository <https://github.com/nextcloud/coding-standard>`_ as well as the
relevant github actions in our `nextcloud template repository <https://github.com/nextcloud/.github>`_.
.. _app-static-analysis:
Static analysis
---------------
@ -62,7 +116,7 @@ Static analysis
.. Note:: The definition supresses usages of the global and static class ``OC`` like ``\OC::$server``, which is discouraged but still found in some apps. The doctrine supression is currently necessary as the database mappers and schema abstractions leak some of the 3rd party libraries of Nextcloud that are not known to Psalm.
You can put this process into a Github Action that is run for every pull request.
You can put this process into a GitHub Action that is run for every pull request.
.. code-block:: yaml

58
developer_manual/digging_deeper/dashboard.rst
View File

@ -85,13 +85,13 @@ of the `load` method and will be called when the dashboard is loaded.
* Execute widget bootstrap code like loading scripts and providing initial state
*/
public function load(): void {
$initialStateService->provideInitialState('myapp', 'myData', []);
$this->initialStateService->provideInitialState('myapp', 'myData', []);
\OCP\Util::addScript('myapp', 'dashboard');
}
}
The class needs to be registered during the :ref:`app bootstrap<Bootstrapping>`.
The `MyAppWidget` class needs to be registered during the :ref:`app bootstrap<Bootstrapping>`.
.. code-block:: php
@ -176,3 +176,57 @@ as plain JavaScript:
})
})
Dashboard API for clients
---------------------------------------
+++++++++++++++++
Implement the API
+++++++++++++++++
If you want your widget content to be accessible with the dashboard API for Nextcloud clients,
it must implement the `OCP\\Dashboard\\IAPIWidget` interface rather than `OCP\\Dashboard\\IWidget`.
This interface contains an extra `getItems` method which returns an array of `OCP\\Dashboard\Model\\WidgetItem` objects.
.. code-block:: php
/**
* @inheritDoc
*/
public function getItems(string $userId, ?string $since = null, int $limit = 7): array {
return $this->myService->getWidgetItems($userId, $since, $limit);
}
`OCP\\Dashboard\Model\\WidgetItem` contains the item information. Its constructor is:
.. code-block:: php
public function __construct(string $title = '',
string $subtitle = '',
string $link = '',
string $iconUrl = '',
string $sinceId = '');
* title: The main widget text content
* subtitle: The secondary text content
* link: A link to the target resource
* iconUrl: URL to a square icon (svg or jpg/png of at least 44x44px)
* sinceId: Item ID or timestamp. The client will then send the latest known sinceId in next dashboard API request.
+++++++++++
Use the API
+++++++++++
From the client point of view, the dashboard widget items can then be obtained with this kind of request:
.. code-block:: bash
curl -u user:passwd http://my.nc/ocs/v2.php/apps/dashboard/api/v1/widget-items \
-H Content-Type:application/json \
-X GET \
-d '{"sinceIds":{"myappwidgetid":"2021-03-22T15:01:10Z","my_other_appwidgetid":"333"}}'
If your client periodically gets widget items content with this API,
include the latest `sinceId` for each widget to avoid getting the items you already have.

2
developer_manual/digging_deeper/debugging.rst
View File

@ -2,6 +2,8 @@
Debugging
=========
.. _debug-mode:
Debug mode
----------

49
developer_manual/digging_deeper/flow.rst
View File

@ -2,8 +2,53 @@
Nextcloud Flow
==============
Nextcloud Flow is the workflow engine of Nextcloud. It offers flexible, user-defined event-based task automation. Apps can register events or triggers which can start a flow, as well as actions which get executed once a trigger is hit and the constraints are satisfied.
Nextcloud Flow is a user-defined event-based workflow engine.
Applications can expose entities with specific events on the one hand, and operations that act on these events on the other hand. A user defines a workflow rule that is triggered by a certain event which will then execute the operation based on user defined checks.
An example flow might be converting Word documents into PDF when they are added to one folder, then move that Word document to another folder once it's finished. This workflow would deal with the file entity's create event and act on that file.
At 36c3 blizzz gave a talk explaining Flow and `how to write actions and triggers. <https://mirror.eu.oneandone.net/projects/media.ccc.de/congress/2019/h264-sd/36c3-oio-174-eng-Building_Nextcloud_Flow_sd.mp4>`_ You can `find the slides of their talk here. <https://nextcloud.com/wp-content/themes/next/assets/files/Building_nextcloud_flow.pdf>`_
Contributions to this documentation are, as always, very welcome!
Entities
========
If you want to expose events via Nextcloud Flow, you need to define an entity, which is a class implementing ``OCP\WorkflowEngine\IEntity``.
The entity class will expose a name for the User interface via ``getName()`` and an icon URL ``getIcon()``.
The ``getEvents()`` method returns an array of all events that this entity can undergo, which will be selectable for the user in the flow interface.
For all events that happen on the nextcloud instance (see :ref:`Events` for all known built-in events), ``prepareRuleMatcher()`` will be called, so it can check whether this event is one of the ones that the entity makes available in flow.
If that is the case, the entity can assign itself to the rule matcher.
Similarly, ``isLegitimatedForUserId()`` will check whether the passed user is allowed to see the current event (which requires that you store the event that was passed to ``prepareRuleMatcher()``).
Operations
==========
Operations are actions that users can configure to happen when specific events occur.
An operation is a class implementing ISpecificOperation, IOperation or IComplexOperation. Specific operations can only act on one specific entity (e.g. a file), while normal operations can oact on all events. Complex operations do not listen on events but setup their own listener(s).
Configuration Component
=======================
The configuration component is what your user sees when they add your flow and go to configure its rules.
For the configuration component, We create a new JavaScript bundle ::
import ConvertToPdf from './ConvertToPdf' // A Vue component
OCA.WorkflowEngine.registerOperator({
id: 'OCA\\WorkflowPDFConverter\\Operation',
operation: 'keep;preserve',
options: ConvertToPdf,
color: '#dc5047'
})
In the ``RegisterOperationsEvent`` listener we need to registere the above JS bundle.
The ``OCA.WorkflowEngine.registerOperator`` function tells Nextcloud about your operation, along with the color, and the component that contains configuration specific to your flow.

2
developer_manual/digging_deeper/index.rst
View File

@ -21,7 +21,7 @@ Digging deeper
rest_apis
search
settings
testing
two-factor-provider
users
dashboard
web_host_metadata

4
developer_manual/digging_deeper/javascript-apis.rst
View File

@ -17,10 +17,10 @@ Usage
The idea is that apps install these packages via `npm` and bundle the code with tools like `Babel <https://babeljs.io/>`_, `Webpack <https://webpack.js.org/>`_ or `Parcel <https://parceljs.org/>`_. This ensures that an app runs the exact same code independent of the Nextcloud version and also reduces the chances of running into conflicts with other apps.
For more details on the design considerations see `the discussion on Github <https://github.com/nextcloud/server/issues/15932>`_.
For more details on the design considerations see `the discussion on GitHub <https://github.com/nextcloud/server/issues/15932>`_.
.. note:: We highly recommend keeping packages up-to-date as they provide fixes and security patches. For apps with code hosted on Github we recommend the use of `Dependabot <https://dependabot.com/>`_.
.. note:: We highly recommend keeping packages up-to-date as they provide fixes and security patches. For apps with code hosted on GitHub we recommend the use of `Dependabot <https://dependabot.com/>`_.
Compatibility

11
developer_manual/digging_deeper/npm.rst
View File

@ -81,22 +81,25 @@ npm run lint (optional)
-----------------------
Nextcloud apps that use linting tools for consistent code formatting typically add a ``lint`` script to their
``package.json``:
``package.json`` and install the appropriate `eslint config <https://www.npmjs.com/package/@nextcloud/eslint-config>`_:
.. code-block:: json
{
"scripts": {
"lint": "eslint --ext .js,.vue src"
"lint": "eslint --ext .js,.vue src",
"lint:fix": "eslint --ext .js,.vue src --fix"
}
}
If style linting is a separate script, ``stylelint`` shall be used as conventional script name:
If style linting is a separate script, ``stylelint`` shall be used as conventional script name.
You can find the standard nextcloud `stylelint config <https://www.npmjs.com/package/@nextcloud/stylelint-config>`_ on npm too.
.. code-block:: json
{
"scripts": {
"stylelint": "stylelint src"
"stylelint": "stylelint src",
"stylelint:fix": "stylelint src --fix"
}
}

18
developer_manual/digging_deeper/psr.rst
View File

@ -1,3 +1,5 @@
.. _PSR:
===
PSR
===
@ -6,6 +8,13 @@ PSR
On this page you find information about the implemented `php standards recommendations <https://www.php-fig.org/psr/>`_ in Nextcloud.
.. _psr0:
PSR-0: Autoloading
------------------
This standard has been deprecated and will be removed from Nextcloud. Please see the :ref:`PSR-4 section<psr4>` instead.
.. _psr3:
PSR-3: Logger Interface
@ -13,6 +22,13 @@ PSR-3: Logger Interface
As of Nextcloud 19, the dependency injection container can inject an instance of a ``\Psr\Log\LoggerInterface``. This is merely a wrapper of the existing (and strongly typed) ``\OCP\ILogger``. Apps may still use the Nextcloud logger, but the `PSR-3`_ implementation shall easy the integration of 3rd party libraries that require the `PSR-3`_ logger.
.. _psr4:
PSR-4: Autoloading
------------------
The `PSR-4` standard describes how class files should be named, so Nextcloud can automatically load them. See the :ref:`classloader docs<appclassloader>` for details.
.. _psr11:
PSR-11: Container Interface
@ -20,5 +36,7 @@ PSR-11: Container Interface
As of Nextcloud 20, the dependency injection container follows the `PSR-11`_ container interface, so you may start type-hinting ``\Psr\Container\ContainerInterface`` whenever you want an instance of a container and use ``has($id)`` to check for existance and ``get($id)`` to retrieve an instance of a service. See the :ref:`dependency injection docs <dependency-injection>` for details.
.. _`PSR-0`: https://www.php-fig.org/psr/psr-0/
.. _`PSR-3`: https://www.php-fig.org/psr/psr-3/
.. _`PSR-4`: https://www.php-fig.org/psr/psr-4/
.. _`PSR-11`: https://www.php-fig.org/psr/psr-11/

Some files were not shown because too many files have changed in this diff Show More