nextcloud/documentation

📘 Nextcloud documentation

Nextcloud Documentation

Documentation is published on https://docs.nextcloud.com. To edit it yourself, you need to tinker a bit with Git and Sphinx. See the Style Guide for formatting and style conventions.

Manuals

This repository hosts three manuals:

• Users' Manual
• Administration Manual
• Developers Manual

Please work in the appropriate branch: stable-branches are for the respective release (e.g. 14.0 or 15.0), master is the latest version.

Please wrap lines at 80 characters.

Note

configuration_server/config_sample_php_parameters.rst is auto-generated from the core config.sample.php file; changes to this file must be made in core https://github.com/nextcloud/server/tree/master/config

Spelling and Capitalization Conventions

As this grows it may be moved to its own page.

• Nextcloud App Store
• synchronize
• Web (Web page, Web site)

License

All documentation in this repository is licensed under the Creative Commons Attribution 3.0 Unported license (CC BY 3.0).

Style

Source files are written using the Sphinx Documentation Generator. The syntax follows the reStructuredText style, and can also be edited from GitHub.

Structure

Of course, think about structure. Keep in mind that we try NOT to move or rename pages once they are created! Lots of external sources link to our documentation, including the indexing by search engines of course. So once you create a page with a certain name, it has to stay in that location and with that name. Think of it as API stability - we have to ensure things stay as they are as much as possible. Renaming or moving is only allowed in exceptional circumstances and only when a redirect is put in place.

Editing

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 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 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.

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 commits, to certify adherence to the Developer Certificate of Origin, 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 <[email protected]>

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, which if you have privacy enabled will be [email protected]

Translations

Help translate the documentation.

For developers that want to ease the translation process, please read this documentation.

Building

Nightly Automated Build Steps

1. Fetch sources
2. git clone https://github.com/nextcloud/documentation.git
3. cd documentation
4. git checkout <branch name>
5. Install
6. npm install svgexport -g --unsafe-perm=true
7. pip3 install -r requirements.txt
8. make all

Building HTML

Using pipenv

1. Install pipenv - https://pipenv.readthedocs.io/en/latest/
2. Change into the environment: pipenv shell
3. Install the dependencies pip install -r requirements.txt
4. Now you can use make ... to build all the stuff - for example make html to build the HTML flavor of all manuals The build assets will be put into the individual documentation subdirectories like developer_manual/_build/html/com

To change into this environment you need to run pipenv shell to launch the shell and to exit you can use either exit or Ctrl + D.

Using venv

1. Install python3-venv
2. Only once: Create a venv (typically inside this repository): python -m venv venv
3. Activate the environment (inside this repository): source venv/bin/activate
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 The build assets will be put into the individual documentation subdirectories like developer_manual/_build/html/com

Autobuilding

When editing the documentation installing sphinx-autobuild though pip can be helpful. This will watch file changes and automatically reload the html preview:

1. Install pip install sphinx-autobuild
2. When building the developer documentation make sure to execute make openapi-spec in the repository root
3. Enter the documentation section cd user_manual
4. Watch for file changes make SPHINXBUILD=sphinx-autobuild html
5. Open http://127.0.0.1:8000 in the browser and start editing

Building PDF

1. Follow instructions for "Building HTML" above
2. Install latexmk and texlive-latex-extra - https://pipenv.readthedocs.io/en/latest/
3. Create a Python environment (typically inside this repository): pipenv --python 3.9
4. Change into the environment: pipenv shell
5. Install the dependencies pip install -r requirements.txt
6. Now you can use make ... to build all the stuff - for example make pdf to build the PDF flavor of all manuals

Using the VSCode DevContainer

This repository contains a full-featured VSCode DevContainer. You can use it in your local development environment or via GitHub Codespaces. Just open the container an use one of the commands from above to build the project. For example make to build the full documentaion, make html to build the HTML documentaion or make pdf to build the PDF documentation. You can also use make SPHINXBUILD=sphinx-autobuild html in combination with port forwarding to watch file changes and automatically reload the html preview.

Icons

To compile and update the icons list in the designer manual, you will also need

1. inkscape
2. sass
3. unzip
4. wget

documentation's Issues

AppData documentation

• see nextcloud/server#1306

cc @rullzer @LukasReschke

Nginx example config should not have line breaks

https://github.com/nextcloud/documentation/blob/master/admin_manual/installation/nginx_nextcloud_9x.rst

Should not have linebreaks.

location ~
^/nextcloud/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|
updater/.+|ocs-provider/.+|core/templates/40[34])\.php(?:$|/) {

10 docs are not listed on the front page

https://docs.nextcloud.com/

We are lacking Release Notes

Currently our documention pages on Release Notes say "tbd":

https://docs.nextcloud.com/server/9/admin_manual/release_notes.html
https://docs.nextcloud.com/server/10/admin_manual/release_notes.html

Basically, what I think should/could be done, or rather is a starting point, is to go throw the PRs of server and app branches, is sum app essential changes that happened in between.

Incorrect spelling

In the beginning of your description for APPS->roundcube you have "Embedd"...should be "Embed".

I've just downloaded the Nextcloud package and just beginning to look through it. I have this thing about spotting typos...they tend to jump out at me.

I do some side work as an editor/proofreader for Twin Dreams Publishing and sometimes it's a force of habit spotting typos.

Update Android documentation

Not sure which one is the right one to use in this case, but looking at:
https://docs.nextcloud.org/server/9/developer_manual/android_library/index.html

I would like to fix several things here:

• Remove the CLA paragraphs
• rename "junior job" to "starter issue" plus the underlying hyperlink
• change all links to Nc

Same applies for https://docs.nextcloud.org/server/9/developer_manual/android_library/library_installation.html

• change links to Nc
• add chapter describing the jitpack alternative on how to include the Nc lib as in

add

compile 'com.github.nextcloud:android-library:-SNAPSHOT'

to your build.gradle to get the latest head or refer to any fixed version you might want to use specifically.

Order of pages wrong?

Hi

A user has a problem with the documentation (https://help.nextcloud.com/t/installation-wizard-but-how/2059) and I confirm it's a bit weird.

So we have this page which explains the installation wizard https://docs.nextcloud.com/server/9/admin_manual/installation/installation_wizard.html , but like the user says, there is nothing about the installation of Nextlcoud before this page. (Like downloading the tarball, extracting etc). I think this is caused because the Preferred Linux Installation Method page was removed. (Since we don't provide packages).
Thus the prefered way of installing Nextcloud is actually (for now) the manual installation https://docs.nextcloud.com/server/9/admin_manual/installation/source_installation.html .

Shouldn't this page (about the manual installation) be moved before the installation wizard, and before the pages about installation apps? Maybe this page should be renamed too?

To be clear with the order of the pages I mean the order they are presented on this page: https://docs.nextcloud.com/server/9/admin_manual/installation/index.html

Help in Users Menu for Contacts and Calendar not working

Opening documentation Wiki on Github in the NC results into a blank screen.

Opening in a new tab can find also nothing.

»Federation Shares« usage in docs instead of »Federated share«

Check https://docs.nextcloud.com/server/10/user_manual/files/federated_cloud_sharing.html

@schiessle @jospoortvliet shouldn’t it be »Using Federated Shares« instead of »Using Federation Shares«? We should keep the wording consistent.

Add missing SELinux policies

The current set of policies is incomplete and we should add the missing ones, such as rename and an example for fusefs, which is used by GlusterFS

#============= httpd_t ==============

#!!!! This avc can be allowed using the boolean 'httpd_use_fusefs'
allow httpd_t fusefs_t:dir rmdir;

#!!!! This avc is allowed in the current policy
allow httpd_t fusefs_t:dir { read write create add_name remove_name };

#!!!! This avc can be allowed using the boolean 'httpd_use_fusefs'
allow httpd_t fusefs_t:file rename;

#!!!! This avc is allowed in the current policy
allow httpd_t fusefs_t:file { setattr read lock create write getattr unlink open append };

#!!!! This avc is allowed in the current policy
allow httpd_t httpd_sys_content_t:dir { write add_name };

#!!!! This avc is allowed in the current policy
allow httpd_t httpd_sys_content_t:file { write create setattr };

Documentation for Calendar and Contacts

We should have an documentation for Calendar and Contacts. Therefore, we need some stuff. Feel free to add something 😁

• Contacts
  • Overview (#126)
  • Add / Modify / Delete and Share Adressbooks
  • Add / Modify and Delete Contacts (Pictures, Adress, Groups, ...)
  • CardDAV Backend Connect (Clients)
• Calendar
  • Overview
  • Add / Modify / Delete and Share Calendars
  • Add / Modify / Delete Events (Name, Participants, Reminders, ...)
  • CalDAV Backend Connect (Clients)

cc @hagengraf

Update list of supported apps

admin_manual/installation/apps_supported.rst

nginx example configs: minor suggestions/ideas

Reported by @voidzero in nextcloud/server#1552

Broken link to "development tool"

The link to "development tool" in section "Check out the code" on https://docs.nextcloud.com/server/10/developer_manual/general/devenv.html points to https://github.com/nextcloud/ncdev which results in a 404 from GitHub.

NextCloud Logo Missing in Documentation

Hi,

on all NextCloud Version 10 PDF documents the OwnCloud Logo is still there and not the NextCloud logo !

regards, hitam4450

Replace owncloud with nextcloud

since nextcloud already released, time to replacing all owncloud string to nextcloud?

I've do that but on my own fork.

Configure Drone for testing documentation builds

Create client documentation pages

Hi. After installing the Nextcloud desktop client on my Mac I was curious if I could find some more information about the bandwidth throttle.

It turns out, that the Help link (right-click on the desktop client icon > Help) links to webpage https://docs.nextcloud.com/desktop/2.2/, which returns a 404 – File not found error. Seems to be some legacy from the fork, as https://doc.owncloud.org/desktop/2.2/ is accessible.

Add the contributor guidelines to a page independent from the server version

Typically the contributor guidelines don't change from version to version. Therefore it would be good to have a URL which doesn't change for every release. For example in the CONTRIBUTE.md we point to https://docs.nextcloud.org/server/10/developer_manual/ which doesn't exists yet.

@jospoortvliet is it possible to have this kind of pages on a non changing URL? Maybe also @LukasReschke

Documentation for file drop feature needed

From Nextcloud 9 on people can allow users to upload files to a public link without seeing the files stored in the folder.

To do this you have to create a public link for a folder, check "can upload" and then "hide file listing"

Add example which shows how to block the clients

Some administrators don't want users to be able to connect using the various clients we offer.
We should give an example on how to configure Nextcloud to support this use case.

Beginners guide for making changes (branch, edit, pull request)

Something like this nextcloud/nextcloud.com#137 (comment) is missing from the current docs:
https://docs.nextcloud.com/server/10/developer_manual/bugtracker/codereviews.html

@MariusBluem You want to add it?

Developers documentation for dark/light themes

See nextcloud/server#819

cc @juliushaertl

Documentation password policy app needed

The password policy app (https://github.com/nextcloud/password_policy) allows the admin to define certain rules for passwords, like min length, require special characters, check against most common password list, etc

Letsencrypt unable to renew certificate

Steps to reproduce

1. Copy and paste nginx config from nextcloud docs
2. Remove fastcgi_request_buffering off; For same reason as comment in issue #149
3. Adding letsencrypt certificate
4. Try certbot-auto renew --dry-run

Expected behaviour

Successful dry run of certificate renewal.

Actual behaviour

Successfull certificate renewal for owncloud certificate but not for nextcloud

Domain: www.nextcloud.mydomain.com
Type:   unauthorized
Detail: Invalid response from http://www.nextcloud.mydomain.com/.well-known/acme-challenge/Hr4V5noM7w9JKdU0HsD5...
   [XX.XXX.XXX.XX]: 403

Server configuration

Operating system: Ubungu 14.04

Web server: nginx

Nextcloud version: 9.0

Updated from an older Nextcloud/ownCloud or fresh install: fresh

Where did you install Nextcloud from: nextcloud website

Configuration

Web server configuration

#upstream php-handler {
#    server 127.0.0.1:9000;
#    #server unix:/var/run/php5-fpm.sock;
#}

server {
    listen 80;
    server_name nextcloud.mydomain.com www.nextcloud.mydomain.com;
    # enforce https
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name nextcloud.mydomain.com www.nextcloud.mydomain.com;

    ssl_certificate /etc/letsencrypt/live/nextcloud.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/nextcloud.mydomain.com/privkey.pem;

    # Add headers to serve security related headers
    # Before enabling Strict-Transport-Security headers please read into this
    # topic first.
    # add_header Strict-Transport-Security "max-age=15768000;
    # includeSubDomains; preload;";
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Robots-Tag none;
    add_header X-Download-Options noopen;
    add_header X-Permitted-Cross-Domain-Policies none;

    # Path to the root of your installation
    root /var/www/nextcloud/;

    location = /robots.txt {
        allow all;
        log_not_found off;
        access_log off;
    }

    # The following 2 rules are only needed for the user_webfinger app.
    # Uncomment it if you're planning to use this app.
    #rewrite ^/.well-known/host-meta /public.php?service=host-meta last;
    #rewrite ^/.well-known/host-meta.json /public.php?service=host-meta-json
    # last;

    location = /.well-known/carddav { return 301
     $scheme://$host/remote.php/dav; }
    location = /.well-known/caldav { return 301
     $scheme://$host/remote.php/dav; }

    location /.well-known/acme-challenge { }

    # set max upload size
    client_max_body_size 512M;
    fastcgi_buffers 64 4K;

    # Disable gzip to avoid the removal of the ETag header
    gzip off;

    # Uncomment if your server is build with the ngx_pagespeed module
    # This module is currently not supported.
    #pagespeed off;

    error_page 403 /core/templates/403.php;
    error_page 404 /core/templates/404.php;

    location / {
        rewrite ^ /index.php$uri;
    }

    location ~ ^/(?:build|tests|config|lib|3rdparty|templates|data)/ {
        deny all;
    }
    location ~ ^/(?:\.|autotest|occ|issue|indie|db_|console) {
        deny all;
    }

    location ~ ^/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|updater/.+|ocs-provider/.+|core/templates/40[34])\.php(?:$|/) {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_param HTTPS on;
        #Avoid sending the security headers twice
        fastcgi_param modHeadersAvailable true;
        fastcgi_param front_controller_active true;
        fastcgi_pass php-handler;
        fastcgi_intercept_errors on;
        #fastcgi_request_buffering off;
    }

    location ~ ^/(?:updater|ocs-provider)(?:$|/) {
        try_files $uri/ =404;
        index index.php;
    }

    # Adding the cache control header for js and css files
    # Make sure it is BELOW the PHP block
    location ~* \.(?:css|js)$ {
        try_files $uri /index.php$uri$is_args$args;
        add_header Cache-Control "public, max-age=7200";
        # Add headers to serve security related headers (It is intended to
        # have those duplicated to the ones above)
        # Before enabling Strict-Transport-Security headers please read into
        # this topic first.
        # add_header Strict-Transport-Security "max-age=15768000;
        #  includeSubDomains; preload;";
        add_header X-Content-Type-Options nosniff;
        add_header X-Frame-Options "SAMEORIGIN";
        add_header X-XSS-Protection "1; mode=block";
        add_header X-Robots-Tag none;
        add_header X-Download-Options noopen;
        add_header X-Permitted-Cross-Domain-Policies none;
        # Optional: Don't log access to assets
        access_log off;
    }

    location ~* \.(?:svg|gif|png|html|ttf|woff|ico|jpg|jpeg)$ {
        try_files $uri /index.php$uri$is_args$args;
        # Optional: Don't log access to other assets
        access_log off;
    }
}

Upgrade script has no documentation

From the discussion here, It would be nice to show the steps required to upgrade nextcloud with the upgrade script.
Somewhere on this page

Thanks

html source pages contain owncloud in id

Hi,
in some of the pages there is a reference to owncloud in the id of the element:

id="owncloud" tabindex="1">

this should be changed to nextcloud.

I have seen this in access_webdav.html, index.html and federated_cloud_sharing.html

Remove bookmarks

Bookmarks is a community app. It was once shipped with core, so it should be removed from the docs, as @BernhardPosselt mentioned here.

https://github.com/JSoko/nextcloud-documentation/commit/79280bc4ccff534dd9cae26fc240dd00d0966664
https://github.com/JSoko/nextcloud-documentation/commit/92068e7aa35bc37f2bad06a362aeb5df2ebed1e9

Update redis requirement

owncloud-archive/documentation#2700

Not sure what this is about, but I guess we should do the same?

Missing 2FA + TOTP documentation for admins and end-users

There is a blog post which needs to be migrated to our official documentation.

http://blog.wuc.me/2016/09/08/nextcloud-totp-two-factor.html

@ChristophWurst

Header is missing some menu entries

This is the header when browsing the documentation

And this is the one when browsing the website

Can you fix it @jospoortvliet ?

Shorten and SEO improve doc URLs

This https://docs.nextcloud.com/server/10/developer_manual/app/css.html could be improved to something like this https://docs.nextcloud.com/developer/app/css.html
For one thing the levels should be less and the readability improved, so people see, where they are or which link they click or even what to type when they directly want to access the docs).

Secondly, after each release the documentation you get in search engines is outdated, because of the version number. There should be a default without version number, which gives you the current version automatically.

For example: https://www.google.de/search?q=nextcloud+documentation+css 😐

Missing Nextcloud 11 section

Master is now NC 11 and we need the documentation for that to show up online.

Movie previews require ffmpeg/avconf

This is not mentioned in the docs, but kind of crucial.
Should also mention for any other providers if they have dependencies:

• Movies: ffmpeg/avconf
• Docs: libreoffice/openoffice or imagick-pdf support
• Image formats: the respective imagick support

'/' is missing in command line for centos 7 php5.5 upgrade

Hi,
in the page:
https://docs.nextcloud.org/server/9/admin_manual/installation/php_55_installation.html
Copy the PHP 5.5 Apache modules into place:

cp /opt/rh/httpd24/root/etc/httpd/conf.d/php55-php.conf /etc/httpd/conf.d/
cp /opt/rh/httpd24/root/etc/httpd/conf.modules.d/10-php55-php.conf /etc/httpdconf.modules.d/
cp /opt/rh/httpd24/root/etc/httpd/modules/libphp55-php5.so /etc/httpd/modules/

should be: /etc/httpd/conf.modules.d/
"/" after httpd

Modify documentation for RHEL7

Adapt this page to PHP 5.6
https://docs.nextcloud.com/server/10/admin_manual/installation/php_55_installation.html

Path variable in the strong permission script is wrong

The path variable in strong permission script is wrong. Should be ncpath not dcpath.

PDF version of Admin & User manual

Hi,
since many people going "online" only, there are many people around, who love to hold a "printed" version an "old fashion" paper in its hands to read and study! The rivaling OwnCloud project provides a pdf - version of its admin manual for "major " releases. Are there any tools scripts, etc. available to generate a pdf - version of the "online" manual ?

regards, hitam 4450

status.php in monitoring considerations

The status.php is now protected by a cookie. How about the documentation section for the considerations on monitoring? cc @LukasReschke

https://github.com/nextcloud/documentation/blob/master/admin_manual/operations/considerations_on_monitoring.rst#statusphp

Missing download link of l10n.pl script to translate apps.

Hi,
In the developer manual you refers to a perl script that is not distributed in the nextcloud/owncloud tarball..

https://docs.nextcloud.com/server/10/developer_manual/app/l10n.html#creating-your-own-translatable-files

Well.. Where you can download this?

Finally I could translate my application using this script:

https://github.com/nextcloud/apps/blob/master/l10n/l10n.pl

...but their use is differently than described. 😕

Missing /

Hello.

Could you please review the script at the following page:
https://docs.nextcloud.com/server/10/admin_manual/installation/installation_wizard.html#strong-perms-label

find ${ocpath} -type f -print0 | xargs -0 chmod 0640
find ${ocpath} -type d -print0 | xargs -0 chmod 0750

In my opinion an "/" is missing and critical... in the worst case it makes the system unusable.

find ${ocpath}/ -type f -print0 | xargs -0 chmod 0640
find ${ocpath}/ -type d -print0 | xargs -0 chmod 0750

Br,
Christian

Adjust install documentation to ubuntu 16.04 and php 7.0

14.04 and php5 is so old school, see #220

Committing to master should not be possible

At the moment it is possible to commit directly to master.

Manual installation download links to owncloud

Found on: https://docs.nextcloud.org/server/9/admin_manual/installation/source_installation.html

The link that says "Nextcloud Download Page" goes to https://owncloud.org/install

Adjust code signing section once app store is ready

Reccomended way of upgrading.

I am not completly sure if this is an issue or not but I think it seems strange regarding with what the nextcloud team said earlier on IRC.
But if you look in the docs then the reccomended way to upgrade Nextcloud is Using your Linux package manager with our official Nextcloud repositories. This is the recommended method.
and i am pretty sure you guys said there wouldn't be any official repos for nextcloud in the nearest feature?.

Get rid of the words "Enterprise only" from the documentation

A good job has been done to remove those words, but we should list all remaining occurrences and get rid of them:

• https://docs.nextcloud.com/server/10/user_manual/external_storage/sharepoint_connecting.html

Errors from s//

using the Nextcloud / Nextcloud Desktop Sync Client
https://docs.nextcloud.org/server/10/user_manual/

Use of the upstream was intended.

Proper documentation needed for pretty URLs

Missing doc

This is the only paragraph found in the documentation:

Pretty URLs are created automatically when .htaccess is writable by the HTTP user, mod_env and mod_rewrite are installed, and 'overwrite.cli.url' in your config.php is set to any non-null value.

This means that if your setup wasn't a 100% as expected by Nextcloud before creating the admin account, you will have missed your chance to setup pretty URLs, because there isn't any documentation available on how to set it up manually.

Config sample is unclear

From the config sample

• Note that above rule is not valid in every case, there are some rare setup
  • cases where this may not apply. However, to avoid any update problems this
  • configuration value is explicitly opt-in.

This means that unlike all other parameters, this needs to be added to config.php.
I think this should be the first line in that large comment and the setting should be commented out since it's not working when found in the sample.

---

@MorrisJobke

Documentation update and translation with transifex

Would appreciate an update of the documentation and translation via transifex.

Major goal is an update of the documentation.
Minor goal is transifex translation.

Would start with an update of the english documentation and then at least create a german translation via transifex.
As I am new to nextcloud i would appreciate every help i can get.
I assume that this should be handled with high priority as it helps spreading nextcloud to users and could ease handle and supporting effort.