Migrating Desktop documentation to the admin section

admin_manual/contents.rst

@@ -22,6 +22,7 @@ Table of contents
     ai/index
     webhook_listeners/index
     windmill_workflows/index
+    desktop/index
     configuration_database/index
     configuration_mimetypes/index
     maintenance/index

admin_manual/desktop/accountcommand.rst

@@ -0,0 +1,20 @@
+==========================
+Command-line Account Setup
+==========================
+
+If you want to automate an Account Setup Wizard to allow the user skip entering server URL and local sync folder path in UI, you can use command-line parameters.
+When you specify both, the desktop client's Account Setup Wizard will jump straight to opening a browser for account authentication/connection without the need of entering any of the connection details.
+The local sync folder will also be selected to the one you specify instead of using default path (/home/Nextcloud)
+
+The following parameters are supported:
+
+``--overridelocaldir``
+   specify a local dir to be used in the account setup wizard (e.g.: /home/nextcloud-sync-folder)
+
+``--overrideserverurl``
+        specify a server URL to use for the force override to be used in the account setup wizard (e.g.: https://cloud.example.com)
+
+Examples:
+
+- ``C:\Program Files\Nextcloud\nextcloud.exe" --overridelocaldir "D:/work/nextcloud-sync-folder" --overrideserverurl https://cloud.example.com``
+- For Linux and mac the same example as above will work but ``nextcloud.exe path`` and ``--overridelocaldir`` value should get changed to platform specific format (e.g. ``no .exe extension`` and ``/home/<user folder>`` format)

admin_manual/desktop/commandline.rst

@@ -0,0 +1,141 @@
+===================
+Command Line Client
+===================
+
+The Nextcloud Client packages contain a command line client, ``nextcloudcmd``, that can 
+be used to synchronize Nextcloud files to client machines.
+
+``nextcloudcmd`` performs a single *sync run* and then exits the synchronization 
+process. In this manner, ``nextcloudcmd`` processes the differences between 
+client and server directories and propagates the files to bring both 
+repositories to the same state. Contrary to the GUI-based client, 
+``nextcloudcmd`` does not repeat synchronizations on its own. It also does not 
+monitor for file system changes.
+
+
+Install ``nextcloudcmd``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+CentOS
+
+::
+
+    $ sudo yum -y install epel-release
+    $ sudo yum -y install nextcloud-client
+
+Ubuntu
+
+::
+
+    $ sudo add-apt-repository ppa:nextcloud-devs/client
+    $ sudo apt update
+    $ sudo apt install nextcloud-client
+
+Debian
+
+::
+
+    $ sudo apt install nextcloud-desktop-cmd
+
+
+Refer to the link
+
+- https://nextcloud.com/install/#install-clients
+- https://launchpad.net/~nextcloud-devs/+archive/ubuntu/client
+- https://pkgs.alpinelinux.org/packages?name=nextcloud-client
+- https://help.nextcloud.com/t/linux-packages-status/10216
+
+
+To invoke ``nextcloudcmd``, you must provide the local and the remote repository 
+URL using the following command::
+
+  nextcloudcmd [OPTIONS...] sourcedir nextcloudurl
+
+where ``sourcedir`` is the local directory and ``nextcloudurl`` is
+the server URL.
+
+Other command line switches supported by ``nextcloudcmd`` include the following:
+
+``--path``
+       Overrides default remote root folder to a specific subfolder on the server(e.g.: /Documents would sync the Documents subfolder on the server)
+
+``--user``, ``-u`` `<user>`
+       Use ``user`` as the login name.
+
+``--password``, ``-p`` `<password>`
+       Use `password` as the password.
+
+``-n``
+       Use`netrc(5)` for login.
+
+``--non-interactive``
+       Do not prompt for questions.
+
+``--silent``, ``--s``
+       Inhibits verbose log output.
+
+``--trust``
+       Trust any SSL certificate, including invalid ones.
+
+``--httpproxy``  `http://[user@pass:]<server>:<port>`
+      Uses `server` as HTTP proxy.
+
+``--exclude`` `<file>`
+      Exclude list file
+
+``--unsyncedfolders`` `<file>`
+      File containing the list of unsynced folders (selective sync)
+
+``--max-sync-retries`` `<n>`
+      Retries maximum n times (defaults to 3)
+
+``-h``
+      Sync hidden files,do not ignore them
+
+
+Credential Handling
+~~~~~~~~~~~~~~~~~~~
+
+``nextcloudcmd`` requires the user to specify the username and password using the standard URL pattern, e.g., 
+
+::
+
+  $ nextcloudcmd /home/user/my_sync_folder https://carla:secret@server/nextcloud
+
+To synchronize the Nextcloud directory ``Music`` to the local directory
+``media/music``, through a proxy listening on port ``8080``, and on a gateway
+machine using IP address ``192.168.178.1``, the command line would be::
+
+  $ nextcloudcmd --httpproxy http://192.168.178.1:8080 --path /Music \
+                $HOME/media/music \
+                https://server/nextcloud
+
+``nextcloudcmd`` will prompt for the user name and password, unless they have
+been specified on the command line or ``-n`` has been passed.
+
+Exclude List
+~~~~~~~~~~~~
+
+``nextcloudcmd`` requires access to an exclude list file. It must either be
+installed along with ``nextcloudcmd`` and thus be available in a system location,
+be placed next to the binary as ``sync-exclude.lst`` or be explicitly specified
+with the ``--exclude`` switch.
+
+The required file content is one exclude item per line where wildcards are allowed, e.g.: 
+::
+
+    ~*.tmp
+    ._*
+    ]Thumbs.db
+    ]photothumb.db
+    System Volume Information
+
+Example
+~~~~~~~~~~~~
+
+- Synchronize a local directory to the specified directory of the nextcloud server
+
+::
+
+    $ nextcloudcmd --path /<Directory_that_has_been_created> /home/user/<my_sync_folder> \
+    https://<username>:<secret>@<server_address>

admin_manual/desktop/configfile.rst

@@ -0,0 +1,88 @@
+==================
+Configuration File
+==================
+
+The Nextcloud Client reads a configuration file.  You can locate this configuration file as follows:
+
+On Linux distributions:
+        ``$HOME/.config/Nextcloud/nextcloud.cfg``
+
+On Microsoft Windows systems:
+        ``%APPDATA%\Nextcloud\nextcloud.cfg``
+
+On macOS systems:
+        ``$HOME/Library/Preferences/Nextcloud/nextcloud.cfg``
+
+
+The configuration file contains settings using the Microsoft Windows .ini file
+format. You can overwrite changes using the Nextcloud configuration dialog.
+
+.. note:: Use caution when making changes to the Nextcloud Client configuration
+   file.  Incorrect settings can produce unintended results.
+
+Some interesting values that can be set on the configuration file are:
+
++----------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``[Nextcloud]`` section                                                                                                                                  |
++=================================+===============+========================================================================================================+
+| Variable                        | Default       | Meaning                                                                                                |
++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+
+| ``remotePollInterval``          | ``30000``     | Specifies the poll time for the remote repository in milliseconds.                                     |
++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+
+| ``forceSyncInterval``           | ``7200000``   | The duration of no activity after which a synchronization run shall be triggered automatically.        |
++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+
+| ``fullLocalDiscoveryInterval``  | ``3600000``   | The interval after which the next synchronization will perform a full local discovery.                 |
++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+
+| ``notificationRefreshInterval`` | ``300000``    | Specifies the default interval of checking for new server notifications in milliseconds.               |
++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+
+
+
++----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``[General]`` section                                                                                                                                                |
++==================================+==========================+========================================================================================================+
+| Variable                         | Default                  | Meaning                                                                                                |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+| ``chunkSize``                    | ``10000000`` (10 MB)     | Specifies the chunk size of uploaded files in bytes.                                                   |
+|                                  |                          | The client will dynamically adjust this size within the maximum and minimum bounds (see below).        |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+| ``forceLoginV2``                 | ``false``                | If the client should force the new login flow, even though some circumstances might need the old flow. |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+| ``minChunkSize``                 | ``5000000`` (5 MB)       | Specifies the minimum chunk size of uploaded files in bytes.                                           |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+| ``maxChunkSize``                 | ``5000000000`` (5000 MB) | Specifies the maximum chunk size of uploaded files in bytes.                                           |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+| ``targetChunkUploadDuration``    | ``60000`` (1 minute)     | Target duration in milliseconds for chunk uploads.                                                     |
+|                                  |                          | The client adjusts the chunk size until each chunk upload takes approximately this long.               |
+|                                  |                          | Set to 0 to disable dynamic chunk sizing.                                                              |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+| ``promptDeleteAllFiles``         | ``false``                | If a UI prompt should ask for confirmation if it was detected that all files and folders were deleted. |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+| ``timeout``                      | ``300``                  | The timeout for network connections in seconds.                                                        |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+| ``moveToTrash``                  | ``false``                | If non-locally deleted files should be moved to trash instead of deleting them completely.             |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+| ``showExperimentalOptions``      | ``false``                | Whether to show experimental options that are still undergoing testing in the user interface.          |
+|                                  |                          | Turning this on does not enable experimental behavior on its own. It does enable user interface        |
+|                                  |                          | options that can be used to opt in to experimental features.                                           |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+| ``showMainDialogAsNormalWindow`` | ``false``                | Whether the main dialog should be shown as a normal window even if tray icons are available.           |
++----------------------------------+--------------------------+--------------------------------------------------------------------------------------------------------+
+
+
++----------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``[Proxy]`` section                                                                                                                                      |
++=================================+===============+========================================================================================================+
+| Variable                        | Default       | Meaning                                                                                                |
++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+
+| ``host``                        | ``127.0.0.1`` | The address of the proxy server.                                                                       |
++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+
+| ``port``                        | ``8080``      | The port were the proxy is listening.                                                                  |
++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+
+| ``type``                        | ``2``         | ``0`` for System Proxy.                                                                                |
++                                 +               +--------------------------------------------------------------------------------------------------------+
+|                                 |               | ``1`` for SOCKS5 Proxy.                                                                                |
++                                 +               +--------------------------------------------------------------------------------------------------------+
+|                                 |               | ``2`` for No Proxy.                                                                                    |
++                                 +               +--------------------------------------------------------------------------------------------------------+
+|                                 |               | ``3`` for HTTP(S) Proxy.                                                                               |
++---------------------------------+---------------+--------------------------------------------------------------------------------------------------------+

admin_manual/desktop/envvars.rst

@@ -0,0 +1,24 @@
+=====================
+Environment Variables
+=====================
+
+The behavior of the client can also be controlled using environment variables. The value of the environment variables overrides the values in the configuration file.
+
+The environment variables are:
+
+- `OWNCLOUD_CHUNK_SIZE` (default: 5242880; 5 MiB) – Specifies the chunk size of uploaded files in bytes. Increasing this value may help with synchronization problems in certain configurations.  
+- `OWNCLOUD_TIMEOUT` (default: 300 s) – The timeout for network connections in seconds.
+- `OWNCLOUD_CRITICAL_FREE_SPACE_BYTES` (default: 50\*1000\*1000 bytes) - The minimum disk space needed for operation. A fatal error is raised if less free space is available. 
+- `OWNCLOUD_FREE_SPACE_BYTES` (default: 250\*1000\*1000 bytes) - Downloads that would reduce the free space below this value are skipped. More information available under the "Low Disk Space" section. 
+- `OWNCLOUD_MAX_PARALLEL` (default: 6) - Maximum number of parallel jobs. 
+- `OWNCLOUD_BLACKLIST_TIME_MIN` (default: 25 s) - Minimum timeout for blacklisted files.
+- `OWNCLOUD_BLACKLIST_TIME_MAX` (default: 24\*60\*60 s; one day) - Maximum timeout for blacklisted files.
+
+Low Disk Space
+^^^^^^^^^^^^^^
+
+When disk space is low the Nextcloud Client will be unable to synchronize all files. This section describes its behavior in a low disk space situation as well as the options that influence it.
+
+1. Synchronization of a folder aborts entirely if the remaining disk space falls below 50 MB. This threshold can be adjusted with the ``OWNCLOUD_CRITICAL_FREE_SPACE_BYTES`` environment variable.
+
+2. Downloads that would reduce the free disk space below 250 MB will be skipped or aborted. The download will be retried regularly and other synchronization is unaffected. This threshold can be adjusted with the ``OWNCLOUD_FREE_SPACE_BYTES`` environment variable.

admin_manual/desktop/index.rst

@@ -0,0 +1,30 @@
+===============
+Desktop Clients
+===============
+
+Available for Windows, macOS, and various Linux distributions, the Nextcloud
+Desktop Sync client enables you to:
+
+- Specify one or more directories on your computer that you want to synchronize
+  to the Nextcloud server.
+- Always have the latest files synchronized, wherever they are located.
+
+Your files are always automatically synchronized between your Nextcloud server, computer and mobile device.
+
+You can find the old documentation here:
+* `Nextcloud Desktop Client`_
+
+.. _`Nextcloud Desktop Client`: https://docs.nextcloud.com/desktop/latest/
+
+
+.. toctree::
+   :maxdepth: 1
+
+   options
+   massdeployment
+   configfile
+   envvars
+   commandline
+   accountcommand
+   troubleshooting
+