Merge pull request #3643 from owncloud/describe-moving-apps-to-differ…

…ent-app-folder

Better document how to use custom app directories and how to move apps between directories

admin_manual/installation/apps_management_installation.rst

@@ -44,35 +44,58 @@ If they are, then they will not be installed.
    refer to the `developer manual
    <https://doc.owncloud.org/server/9.0/developer_manual/app/index.html>`_.
 
+.. _using_custom_app_directories_label:
+
 Using Custom App Directories
 ----------------------------
 
-Use the **apps_paths** array in ``config.php`` to set any custom apps directory locations. 
-The key **path** defines the absolute file system path to the app folder. 
-The key **url** defines the HTTP web path to that folder, starting at the ownCloud web root. The key **writable** indicates if a user can install apps in that folder.
+There are several reasons for using custom app directories instead of ownCloud's default.
+These are:
+
+#. It separates ownCloud's core apps from user or admin downloaded apps. Doing so distinguishes which apps are core and which aren't, simplifying upgrades.
+#. It eases manual upgrades. Downloaded apps must be manually copied. Having them in a separate directory makes it simpler to manage.
+#. ownCloud may gain new core apps in newer versions. Doing so orphans deprecated apps, but doesn't remove them.
+
+If you want to store apps in a custom directory, instead of ownCloud's default (``/app``), you need to modify the ``apps_paths`` element in ``config/config.php``.
+There, you need to add a new associative array that contains three elements.
+These are:
+
+- ``path``: The absolute file system path to the custom app folder. 
+- ``url``: The request path to that folder relative to the ownCloud web root, prefixed with ``/``. 
+- ``writable``: Whether users can install apps in that folder. After the configuration is added, new apps will only install in a directory where ``writable`` is set to ``true``.
 
-.. note:: 
-   To ensure that the default **/apps/** folder only contains apps shipped with ownCloud, follow this example to setup an **/apps2/** folder which will be used to store all other apps.
+The configuration example below shows how to add a second directory, called ``apps2``. 
 
-.. code-block:: php
+.. literalinclude:: ./examples/custom-app-directory-configuration.php
+   :language: php
+   :emphasize-lines: 9-13
 
-  <?php
+After you add a new directory configuration, you can then move apps from the original app directory to the new one. 
+To do so, follow these steps:
 
-    "apps_paths" => array (
-        0 => array (
-                "path"     => OC::$SERVERROOT."/apps",
-                "url"      => "/apps",
-                "writable" => false,
-        ),
-        1 => array (
-                "path"     => OC::$SERVERROOT."/apps2",
-                "url"      => "/apps2",
-                "writable" => true,
-        ),
-    ),
+#. Enable maintenance mode.
+#. Disable the apps that you want to move.
+#. Create a new apps directory and assign it the same user and group, and ownership permissions as the core apps directory.
+#. Move the apps from the old apps directory to the new apps directory.
+#. Add a new app directory in ``config/config.php``.
+#. Re-enable the apps.
+#. Disable maintenance mode.
 
 Manually Installing Apps
 ------------------------
 
-To install an app manually (locally), instead of by using the Appstore, copy the app into the ownCloud app folder (``/path/to/owncloud/apps``). 
-The folder name of the app and the name of the app **must be identical**.
+To install an app manually instead of by using `the Marketplace`_, copy the app either into ownCloud's default app folder (``</path/to/owncloud>/apps``) or :ref:`a custom app folder <using_custom_app_directories_label>`. 
+
+Be aware that the name of the app and its folder name **must be identical**!
+You can find these details in `the application's metadata file`, located in ``<app directory>/appinfo/info.xml``.
+
+Using the example below, both the app's name and directory name would be ``yourappname``.
+
+.. literalinclude:: ./examples/appinfo.xml
+   :language: xml
+   :emphasize-lines: 100
+
+.. Links
+   
+.. _the Marketplace: https://marketplace.owncloud.com
+.. _the application's metadata file: https://doc.owncloud.org/server/latest/developer_manual/app/fundamentals/info.html

admin_manual/installation/examples/appinfo.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0"?>
+<info>
+  <id>yourappname</id>
+  <name>Your App</name>
+  <version>1.0</version>
+</info>

admin_manual/installation/examples/custom-app-directory-configuration.php

@@ -0,0 +1,16 @@
+<?php
+$CONFIG = [
+    'apps_paths' => [
+        [
+            'path' => '/var/www/owncloud/apps',
+            'url' => '/apps',
+            'writable' => false,
+        ],
+        [
+            'path' => '/var/www/owncloud/apps2',
+            'url' => '/apps2',
+            'writable' => true,
+        ],
+    ],
+    // remainder of the configuration
+];