owncloud / docs-client-desktop

ownCloud Desktop Client Documentation

Desktop App Documentation

Table of Contents

• Building the Desktop Docs
• General Notes
• Generating the Documentation
• Target Branch and Backporting
• Branching Workflow
• Create a New Version Branch for the Desktop App

Building the Desktop Docs

The Desktop App documentation is not built independently. Instead, it is built together with the main documentation. However, you can build a local copy of the desktop client documentation to preview changes you are making.

Whenever a Pull Request of this repo gets merged, it automatically triggers a full docs build.

General Notes

To make life easier, most of the content written in docs applies also here. For ease of reading, the most important steps are documented here too. For more information see the link provided. Only a few topics of this repo are unique like the branching.

Generating the Documentation

See the Generating the Documentation in the docs repo for more details as it applies to all documentation repositories.

Target Branch and Backporting

See the following section as the same rules and notes apply.

Branching Workflow

Please refer to the Branching Workflow for the Desktop App for more information.

Create a New Version Branch for the Desktop App

Please refer to Create a New Version Branch for the Desktop App for more information.

docs-client-desktop's Issues

[QA] Control WinVFS with Attrib.exe

Does this "just work"?
https://techcommunity.microsoft.com/t5/microsoft-onedrive-blog/onedrive-files-on-demand-for-the-enterprise/ba-p/117234

How to achieve clean installation with AppImage

Didn't have a previous version installed, but the client remembered my account.
So how to achieve a clean installation with AppImage?

I didn't find anything in the documentation (maybe I oversaw it...)

[QA] WinVFS with Win Storage Sense

• https://support.microsoft.com/en-us/office/use-onedrive-and-storage-%3Cmark%3Esense%3C/mark%3E-in-windows-10-to-manage-disk-space-de5faa9a-6108-4be1-87a6-d90688d08a48
• https://www.tenforums.com/tutorials/112382-automatically-make-onedrive-files-demand-online-only-windows-10-a.html

`owncloudcmd` documentation incorrect.

Fron: https://doc.owncloud.com/desktop/next/advanced_usage/command_line_client.html

-h	Sync hidden files,do not ignore them.

-h is actually Displays help on commandline options.

Meanwhile there doesn't appear to be an option to sync hidden files using commandline options:

$ owncloudcmd -h
gui.platform: adding plugin directory "/opt/ownCloud/ownCloud/bin/../lib/x86_64-linux-gnu/plugins"
Usage: owncloudcmd [options] source_dir server_url remote_folder
owncloudcmd version 3.0.0.9215- - command line client tool

Options:
  -s, --silten                      Don't be so verbose.
  --httpproxy <http://server:port>  Specify a http proxy to use.
  --trust                           Trust the SSL certification
  --exclude <file>                  Path to an exclude list [file]
  --unsyncedfolders <file>          File containing the list of unsynced remote
                                    folders (selective sync)
  --server <url>                    Use [url] as the location of the server.
                                    OCIS only (server location and spaces url
                                    can differ)
  -u, --user <name>                 Use [name] as the login name
  -p, --password <password>         Use [pass] as password
  -n                                Use netrc (5) for login
  --non-interactive                 Do not block execution with interaction
  --max-sync-retries <n>            Retries maximum n times (default to 3)
  --uplimit <n>                     Limit the upload speed of files to n KB/s
  --downlimit <n>                   Limit the download speed of files to n KB/s
  --logdebug                        More verbose logging
  -h, --help                        Displays help on commandline options.
  --help-all                        Displays help including Qt specific
                                    options.
  -v, --version                     Displays version information.

Arguments:
  source_dir                        The source dir
  server_url                        The url to the server
  remote_folder                     A remote folder

There's also that typo in the actual help within the program (--silten) which probably deserves it's own ticket.

Update doc about running Squish tests with oCIS

We can now run Squish tests against the oCIS server. And that needs some configuration to be set. Update the testing doc about those changes.

Document that hidden files are .files

To be added at: https://doc.owncloud.com/desktop/2.11/navigating.html#advanced

@tbsbdr fyi

Documentation about Syncing of "problematic" filenames

We need to document the systems behavior with filenames containing forbidden chars, spaces at the end, four byte emoticons and stuff.

@carlaschroder this is just a reminder so far, I am happy to come up with a first draft if you point me where that should be added in the doc.

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Since 2.8 the client should automatically print to the windows terminal, no workaround needed

Since 2.8 we atache to the terminal if possible.
That way we should see the log without the need for the workaround described in: https://github.com/owncloud/docs-client-desktop/blame/1c76993f8e48dbf495a202f0d2a6638d2f149d99/modules/ROOT/pages/appendices/troubleshooting.adoc#L112

Not using the workaround should also fix some encoding issues of the log file which can occur when using the workaround.

Document the desktop clients query intervals and the impacts

We need to document when and why the client is querying the backend.

There are regular intervals like 1 or 2h where the client automatically does this, which could lead to request spikes on the server when there are many concurrent clients connected.

@TheOneRing @butonic

@EParzefall fyi

[Troubleshooting] Add information about Crash Report and ID

Crash reports available for:

• Win
• Mac (x64 only, see owncloud/client#10163)
• Linux Pakete ? @fmoc
• Linux AppImage ? @fmoc

Add here:
https://doc.owncloud.com/desktop/appendices/troubleshooting.html

Add documentation that Windows VFS requires files ownership

When using Windows Virtual files, the user must own those, on a filesystem level.

See owncloud/client#10382

Poll interval from capabilities

See owncloud/client#8777

Add cmake option for building the client to disable auto updater

References: owncloud/client#9814 (CMake: Implement WITH_AUTO_UPDATER)

Distros might not want to have our auto updater enabled, add option to disable it.

Some more build options available that need documentation, see the referenced PR.

@TheOneRing @dragotin fyi

Pattern in ignored files is applied to folders as well

Server: 10.2.0
macOS: 10.14.5
Client: 2.6.0-daily20190613 (build 11917)

Steps to recreate:

1. Go to General tab
2. Click on Edit Ignored Files
3. Add a new pattern
4. Rename/create a folder with that pattern in name

Actual result: Folder is being ignored
Expected result: File pattern is not applied to a folder. Or the wording is changes so it is obvious that the rules will be applied to both files and folders

[GUI squish test] Browser installation command missing for ocis setup

In this section https://doc.owncloud.com/desktop/3.1/appendices/guitest.html#extra-steps-for-infinite-scale,
browser installation command missing

npx playwright install chromium

NTFS is mandatory with Windows, FAT (or derivates) are not working properly

Referencing: owncloud/client#8913 (Moving files causes delete and re-upload with second Folder Sync Connection)

Document that you have to use NTFS and not any FAT variant on Windows, which is especially true for external connected drives (like via USB)

Background:

In the FAT file system, the file ID is generated from the first cluster of the containing directory and the byte offset within the directory of the entry for the file. Some defragmentation products change this byte offset. (Windows in-box defragmentation does not.) Thus, a FAT file ID can change over time. Renaming a file in the FAT file system can also change the file ID, but only if the new file name is longer than the old one.
https://docs.microsoft.com/en-us/windows/win32/api/fileapi/ns-fileapi-by_handle_file_information

Backport to 2.7 and 2.8 necessary

@TheOneRing @Darkexy fyi

[oCIS] Open File in WebOffice

owncloud/client#9724

Add a small note that folder/file sizes may show different numbers over the clients

Decimal/Binary and Blocksize dependent

@tbsbdr

[Desktop] [VFS] Document native WinVFS for admins (Storage Sense)

Topic was part of #50, but wasn't covered in #80

• Control WinVFS behaviour with Storage Sense (another Win feature we use, for users and admins)
  • https://support.microsoft.com/en-us/office/use-onedrive-and-storage-sense-in-windows-10-to-manage-disk-space-de5faa9a-6108-4be1-87a6-d90688d08a48
  • https://support.microsoft.com/en-us/windows/manage-drive-space-with-storage-sense-654f6ada-7bfc-45e5-966b-e24aded96ad5
  • https://www.tenforums.com/tutorials/112382-automatically-make-onedrive-files-demand-online-only-windows-10-a.html
  • https://docs.microsoft.com/en-us/windows/client-management/mdm/policy-csp-storage#storage-configstoragesensecloudcontentdehydrationthreshold
  • https://techcommunity.microsoft.com/t5/microsoft-onedrive-blog/onedrive-files-on-demand-for-the-enterprise/ba-p/117234 (also discussed in https://github.com/owncloud/client/issues/8587)

[FAQ] Explain cleanup of error messages

owncloud/client#10343

[AppImage] Extend Linux Automatic Updating Section

Starting with 3.0+, AppImages come with AutoUpdate feature. This section should be extended:
https://doc.owncloud.com/desktop/3.0/automatic_updater.html#linux

@fmoc can help if you have questions

Document Differences of Quota

Referencing: owncloud/docs#4185 ([desktop] Document Differences of Quota)

WHAT Needs to be Documented?

There is a difference between the quota that the desktop client displays and the value that the web interface shows.

The explanation for that is that the Client calculation also includes used data that doesn’t count against users own storage. (received shares, external storages etc).

That value is also added to the limit.

WHERE Does This Need To Be Documented (Link)?

It could be a nice entry in the clients FAQ Why does the quota value differ between...?

WHY Should This Change Be Made?

Have a more informative documentation.

Not sure about the other clients, might also be beneficial.

@dragotin fyi

Continuous-Integration / Drone

This repo needs a CI same as in docs.

@phil-davis Help wanted and needed

@EParzefall FYI

Note 1: that atm there is no starlark file present as we have in docs. This must be created from scratch. The existing Makefile is for historical reasons only, comes from the client repo and will be removed when we have a working starlark file.

Note 2: the basic definition files of this repo should be the same as in docs, adopted to desktop but may need additional adjustments when setting up CI or a starlark file.

[Spaces] Document Spaces for 3.0+

ownCloud 3.0+ Desktop app supports oCIS Spaces:

• Pre-3.0 accounts can't be migrated to 3.0+ Spaces accounts. Needs new account setup
• oC10 accounts can't be migrated to oCIS Spaces accounts. Needs new account setup
• Default: All existing/active Spaces get added at initial account setup
• Default: Personal, Shares and Spaces are placed in a parent folder, that gets linked from file manager sidebars (owncloud/client#9821, owncloud/client#9838)
• New Spaces don't get added automatically (planned feature)
• 3.0+ with Spaces doesn't have the option to sync subfolders (planned feature)
• Spaced deleted or disabled on the server doesn't get deleted (owncloud/client#10285, owncloud/client#10257 , owncloud/client#9700)
• Spaces renamed on the server doesn't change locally. Only content inside changes (owncloud/client#10284)

[DOC] describe when items are not syncronized (not synchronized tab)

As of client 2.6

Doc change by adding a section in Using the Synchronization Client describing the
not synchronized tab of the client and its impacts/reasons/causes.

At the moment, there is no description at all available where users can read about.

Referencing: owncloud/client#7588

@settermjd @michaelstingl @ogoffart

Doc: Document current build instructions based on https://github.com/owncloud/ownbuild/

We currently mention craft in the build instruction https://doc.owncloud.com/desktop/2.8/building.html#windows-development-build-with-kde-craft

We also describe how to manually build on mac os.
All this can be achieved with https://github.com/owncloud/ownbuild/ .
In addition to making things way easier the user would also experience our "SDK" and thus the same experience as the official client.

[oCIS] Open files in online office suite

Client repo:

• owncloud/client#9724
• owncloud/client#9941

System requirements

• Desktop Sync Client version 3.0+
• oCIS backend with App Provider configured:
  https://owncloud.dev/services/app-registry/apps/#app-provider-capability

You can test-drive with our public demo instance:
https://ocis.ocis-wopi.latest.owncloud.works/

@mmattel FYI

Document Windows LongPath opt in

• owncloud/client#10136

[Desktop] Explain Quota in FAQ

WHAT Needs to be Documented?

first number:

• data used in my quota
• plus data used in external storages
• plus data used in other users shares

Second number:

• my quota
• plus data used in external storages
• plus data used in other users shares

WHERE Does This Need To Be Documented (Link)?

https://doc.owncloud.com/desktop/faq.html

WHY Should This Change Be Made?

We sometimes get this question on various channels.

(Optional) What Type Of Content Change Is This?

• New Content Addition
• Old Content Deprecation
• Existing Content Simplification
• Bug Fix to Existing Content

(Optional) Which Manual Does This Relate To?

• Admin Manual
• Developer Manual
• User Manual
• Android
• iOS
• Branded Clients
• Desktop Client
• Other

Activity > Not Synced: document new select-all and copy feature

Location:
https://doc.owncloud.com/desktop/2.9/navigating.html#activity-window

New feature:
Since 2.9, you can select a single line and copy it to clipboard, and select-all (Strg+a) and copy it to clipboard.

Pictures for Desktop Client Update View on Windows + Linux vs macOS

WHAT Needs to be Documented?

screenshots of "Desktop Client Update View" on Windows + Linux vs macOS need to be taken and added to what we already have.

WHERE Does This Need To Be Documented (Link)?

https://doc.owncloud.com/desktop/next/automatic_updater.html#basic-workflow

WHY Should This Change Be Made?

because it's a better tool for showing people instead of making them read 3 lines of text.

(Optional) What Type Of Content Change Is This?

• New Content Addition
• Old Content Deprecation
• Existing Content Simplification
• Bug Fix to Existing Content

(Optional) Which Manual Does This Relate To?

• Admin Manual
• Developer Manual
• User Manual
• Android
• iOS
• Branded Clients
• Desktop Client
• Other

---

Windows:

---

mac:

---

GitHub Issue with explanation:
owncloud/client#10414

[Linux AppImage] Document installation and use of AppImages

General

AppImage is a different way to install Linux applications - not several files (packages) in several places but one file (ending .AppImage) containing the application and all necessary dependency and libraries. There is only a single application AppImage which runs on all (modern) Linux platforms.

There are known issues for these platforms with the 2.10.1 AppImage:

• doesn't run on CentOS 7 -> owncloud/client#9195
• issue with libfuse on Ubuntu 22.04 -> https://docs.appimage.org/user-guide/troubleshooting/fuse.html

How To Use AppImages in Linux
-> https://docs.appimage.org/user-guide (official appimage doc)
-> https://itsfoss.com/use-appimage-linux/

Install and run an AppImage

-> https://docs.appimage.org/introduction/quickstart.html#ref-quickstart

• download xyz.AppImage from https://owncloud.com/desktop-app/ Linux (and move it to $HOME/Applications or $HOME/bin)
• make it executable in file browser or on command line (chmod +x xyz.AppImage)
• run the AppImage by double click or on command line with ./xyz.AppImage -s (start on command line with '-s' option: the client settings window is shown)
• to remove the AppImage from your system simply delete the xyz.AppImage file.

Note: to see systray client icons on Debian 11 apt install gnome-shell-extension-appindicator and enable 'Ubuntu appindicators' in "Tweaks/Extensions"

System integration

Install AppImageLauncher -> https://docs.appimage.org/user-guide/run-appimages.html#appimagelauncher

• download the appropriate package, see https://github.com/TheAssassin/AppImageLauncher/#system-wide-installation from https://github.com/TheAssassin/AppImageLauncher/releases/
• install with a graphical install tool (right click and choose the installer); if not possible see https://github.com/TheAssassin/AppImageLauncher/wiki/Install-on-Ubuntu-or-Debian
• double click on xyz.AppImage (downloaded to $HOME/Downloads) to start the AppImageLauncher and let it do the integration
• starting the client is possible now from Show Applications resp. Application Launcher
• removing the AppImage is also possible here on right click

Note: the 'rpm' package isn't signed (yet). Install e.g. on openSUSE using zypper install appimagelauncher-xxx.rpm and ignore that signature verification failed.

Limitations

• file browser integration, means overlay icons and context menu, is not included in the AppImage
  -> install the file browser extension packages manually as system packages, e.g. owncloud-client-nautilus (from linux repos at https://download.owncloud.com/desktop/ownCloud/stable/latest/linux/download/)
• autostart doesn't work
• no automatic update, new version is suggested for manual update

up to here for 2.10.1

---

For 3.0.0 release

• runs on CentOS 7
• autostart (start on Login) works
• automatic update enabled
• knows issues for some platforms, see owncloud/client#9631

[QA] new features in desktop client 2.10.2

Probably owncloud/client#9881

We need to ping the client team for details.
I assume it is user facing due to this change:

[Desktop] [VFS] Document native WinVFS

WHAT Needs to be Documented?

• Desktop client uses a native Win10 system feature to integrate in Win Explorer.
• Nothing oC invented, we only use it. And we want to use it the most native way. Features & behaviour should follow the original MS OneDrive implementation.
  • MS user docs: https://support.microsoft.com/en-us/office/save-disk-space-with-onedrive-files-on-demand-for-windows-10-0e6860d3-d9f3-4971-b321-7092438fb38e
  • MS dev docs: https://docs.microsoft.com/en-us/windows/win32/api/_cloudapi/
  • MS dev examples: https://github.com/MicrosoftDocs/win32/blob/docs/desktop-src/cfApi/build-a-cloud-file-sync-engine.md
• Apple iCloud on Win10 uses the same Win feature
  • Apple user docs: https://support.apple.com/guide/icloud/pin-files-and-folders-mm17d7e476fc/1.0/icloud/1.0
• Other vendors followed our approach, here's an example.
• System Requirements: https://doc.owncloud.com/desktop/installing.html#system-requirements
• Limitations:
  • Desktop client prevents VFS configuration on non-NTFS drive (Win limitation, nothing we can do)
  • Desktop client prevents VFS configuration on drives root (D:\\ ⚠️ ; D:\\ownCloud✅ , Win limitation, nothing we can do)
• Control WinVFS behaviour with Storage Sense (another Win feature we use, for users and admins)
  • https://support.microsoft.com/en-us/office/use-onedrive-and-storage-sense-in-windows-10-to-manage-disk-space-de5faa9a-6108-4be1-87a6-d90688d08a48
  • https://support.microsoft.com/en-us/windows/manage-drive-space-with-storage-sense-654f6ada-7bfc-45e5-966b-e24aded96ad5
  • https://www.tenforums.com/tutorials/112382-automatically-make-onedrive-files-demand-online-only-windows-10-a.html
  • https://docs.microsoft.com/en-us/windows/client-management/mdm/policy-csp-storage#storage-configstoragesensecloudcontentdehydrationthreshold
  • https://techcommunity.microsoft.com/t5/microsoft-onedrive-blog/onedrive-files-on-demand-for-the-enterprise/ba-p/117234 (also discussed in https://github.com/owncloud/client/issues/8587)

WHERE Does This Need To Be Documented (Link)?

https://doc.owncloud.com/desktop/navigating.html

WHY Should This Change Be Made?

WinFVS is enabled as default on Win10 in 2.7+

(Optional) What Type Of Content Change Is This?

• New Content Addition
• Old Content Deprecation
• Existing Content Simplification
• Bug Fix to Existing Content

(Optional) Which Manual Does This Relate To?

• Admin Manual
• Developer Manual
• User Manual
• Android
• iOS
• Branded Clients
• Desktop Client
• Other

@mmattel @EParzefall we discussed in context of May-planning.

[AppImage] HowTo install file browser extension packages manually

This isn't enough explanation for me:

The file browser integration, which means overlay icons and the context menu, is not included in the AppImage. You need to install file browser extension packages manually.

(from https://doc.owncloud.com/desktop/2.11/installing.html#appimage)

@fmoc could you post the instructions?

[FAQ] Explain error message about Multiple account are sharing the folder

There are 2 new error messages in the 2.9 client:

Multiple account are sharing the folder H:/.
This configuration is know to lead to dataloss and is no longer supported.
Please consider removing this folder from the account and adding it again.

and

We should add a new section to the FAQ, similar to the section we have about unsupported sever versions:
https://doc.owncloud.com/desktop/faq.html

Add a small note that folder/file sizes may show different numbers over the clients

Decimal/Binary and Blocksize dependent

@tbsbdr

Update AppImage limitations list

The 3.0 docs contain an outdated list of limitations. 3.0 AppImages now support self-updating. Autostart has been fixed, too.

Update AppImage related documentation before 2.11 release

Some of the docs will become outdated with the upcoming 2.11 release and need to be changed:

• we now build the AppImage on CentOS 7, thus there is no compatibility problem with common older distributions any more

While reading through the docs, I noticed another bug in the docs:

sudo chmod +x ownCloud-2.10.1.7187.AppImage

The sudo bit is not required. AppImages generally do not require root access for regular use.

[Troubleshooting] Document new 3.0 logging screen

Changes need here:
https://doc.owncloud.com/desktop/appendices/troubleshooting.html#log-files

Inconsistent behavior when there is a sync issue

I'm referring to the following issue:
https://github.com/owncloud/enterprise/issues/5426

Specifically the following comment sheds some light into the dark:
https://github.com/owncloud/enterprise/issues/5426#issuecomment-1308694173

I think this should be documented somewhere, however I am not sure where.
Perhaps on "Using the Desktop App" or alternatively in the appendices section.

We should just add a couple sentences along the lines of this (feel free to improve them):

Known issues

If the client is showing a sync error, it is obligatory to make sure to resolve them immediately.
The error handling of such an issue is different between files and folders which can easily lead to a user inadvertently deleting files.

The customer originally reporting the issue is describing such an error loss scenario in detail in the following comment:
https://github.com/owncloud/enterprise/issues/5426#issuecomment-1306829300

Document "Force Sync Now" Button

The Documentation does not describe the behaviour (or even the existence) of the Button "Force Sync Now"/"Synchronisation jetzt erzwingen"

The Documentation that needs to be created, needs to anwer these questions:

• What is the use case for this button (When should the user press it?)
• What is the expected behaviour of this button?
• What is the expected behaviour after a (resolved) conflict?

Document additional installation dependency for nautilus extension on CentOS

On CentOS, the Python extensions for nautilus (GNOME) and its forks nemo (Cinnamon) and caja (MATE) are available only in the third-party EPEL archives, which need to be installed separately before our packages can be installed. To do so, the user needs to install the epel-release package, e.g., by running yum install epel-release. Our installation docs need mention this, since we cannot automate the process in our packaging. The consensus among the RedHat-based distros appears to be to just document the additional dependency.

See also: owncloud/client#9126

Screenshots for the desktop client FAQs

Related pull request: #123

This issue is about providing screenshots to replace files in .../docs-client-desktop/modules/ROOT/assets/images/faq.

(1) multiple-accounts-sharing-folder.png

(2) folder-used-in-sync-connection1.png

(3) folder-used-in-sync-connection2.png

(4) folder-used-by-different-client.png

(5) folder-managed-by-another-sync-client.png

[VFS] Managing the availability isn't possible any longer from dot menu

The section Manage VFS from ownCloud https://doc.owncloud.com/desktop/2.10/vfs.html#manage-vfs-from-owncloud is outdated (from 2.10.0 on). The menu entry 'Availability' was removed from the client dot menu.

'Free up space' or 'Always keep on this device' can be done in Explorer -> Manage VFS from Windows Explorer https://doc.owncloud.com/desktop/2.10/vfs.html#manage-vfs-from-windows-explorer .
The text here should also mention that the operation is possible on folders which allows to do it at once for all files inside the folder.

Backport to 2.10 is needed.

[Wizard] Document new Wizard in 3.0+

• Features from old wizard now in the global settings (owncloud/client#10266)
• App password link removed (owncloud/client#10055)

[owncloudcmd] Add examples (oC10, oCIS, Spaces)

Command Line Client would be more useful with some examples:

• Typical oC10
• oCIS Personal Space
• oCIS Share Space
• oCIS other Space

Where to find the correct parameters?

---

Prerequisite:

• Run oCIS in Basic Auth
  https://doc.owncloud.com/ocis/next/deployment/services/s-list/auth-basic.html
  (not recommended! ⚠️)

oCIS improvements:

• users should be able to find the WebDAV URL in the web UI: owncloud/web#9714
• App passwords: owncloud/ocis#197

Client improvements:

• owncloud/client#10256

[oCIS] [Sharing] Desktop 3.0 opens web UI for Sharing when connected to oCIS

Dev issue:

• owncloud/client#10206

https://doc.owncloud.com/desktop/next/using.html#sharing-from-your-desktop

When connected to ocis, there is no share dialog anymore. Web UI gets opened instead

The 3.0 cmd client no longer accepts legacy urls in the form of https://demo.owncloud.com/remote.php/webdav/

The url must be similar to

• https://demo.owncloud.com/
• https://demo.owncloud.com/remote.php/dav/files/admin/Documents
• https://demo.owncloud.com/remote.php/dav/files/admin/

Description of log files is outdated

https://doc.owncloud.com/desktop/2.9/appendices/troubleshooting.html#log-files

• (1) The screenshot is from 2.5 or what ever.
• (2) We no longer require | Write-Host on Windows