From 72a64d35ce27f7c6d119067a93e37bc96822e706 Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Tue, 19 Dec 2017 15:12:21 +0100 Subject: [PATCH 1/3] Better document how to use custom app directories This fixes #3261. --- .../apps_management_installation.rst | 56 +++++++++++-------- .../custom-app-directory-configuration.php | 16 ++++++ 2 files changed, 48 insertions(+), 24 deletions(-) create mode 100644 admin_manual/installation/examples/custom-app-directory-configuration.php diff --git a/admin_manual/installation/apps_management_installation.rst b/admin_manual/installation/apps_management_installation.rst index 78e0d3c3f..1eed8cbfb 100644 --- a/admin_manual/installation/apps_management_installation.rst +++ b/admin_manual/installation/apps_management_installation.rst @@ -47,32 +47,40 @@ If they are, then they will not be installed. 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. - -.. 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. - -.. code-block:: php - - array ( - 0 => array ( - "path" => OC::$SERVERROOT."/apps", - "url" => "/apps", - "writable" => false, - ), - 1 => array ( - "path" => OC::$SERVERROOT."/apps2", - "url" => "/apps2", - "writable" => true, - ), - ), +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``. + +The configuration example below shows how to add a second directory, called ``apps2``. + +.. literalinclude:: ./examples/custom-app-directory-configuration.php + :language: php + :emphasize-lines: 9-13 + +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: + +#. 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**. \ No newline at end of file +The folder name of the app and the name of the app **must be identical**. diff --git a/admin_manual/installation/examples/custom-app-directory-configuration.php b/admin_manual/installation/examples/custom-app-directory-configuration.php new file mode 100644 index 000000000..726d0e22f --- /dev/null +++ b/admin_manual/installation/examples/custom-app-directory-configuration.php @@ -0,0 +1,16 @@ + [ + [ + 'path' => '/var/www/owncloud/apps', + 'url' => '/apps', + 'writable' => false, + ], + [ + 'path' => '/var/www/owncloud/apps2', + 'url' => '/apps2', + 'writable' => true, + ], + ], + // remainder of the configuration +]; From 29163fc7b39effd2fed0e6379ebac86499b2f005 Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Wed, 20 Dec 2017 13:46:54 +0100 Subject: [PATCH 2/3] Better document (and correct) the manual app installation details This commit replaces the Appstore reference with a link to the Marketplace, links to relevant sections of the documentation, and provides an XML snippet of an appinfo/info.xml file, to help the docs be more meaningful. Signed-off-by: Matthew Setter --- .../apps_management_installation.rst | 19 +++++++++++++++++-- .../installation/examples/appinfo.xml | 6 ++++++ 2 files changed, 23 insertions(+), 2 deletions(-) create mode 100644 admin_manual/installation/examples/appinfo.xml diff --git a/admin_manual/installation/apps_management_installation.rst b/admin_manual/installation/apps_management_installation.rst index 1eed8cbfb..4645f8933 100644 --- a/admin_manual/installation/apps_management_installation.rst +++ b/admin_manual/installation/apps_management_installation.rst @@ -44,6 +44,8 @@ If they are, then they will not be installed. refer to the `developer manual `_. +.. _using_custom_app_directories_label: + Using Custom App Directories ---------------------------- @@ -82,5 +84,18 @@ To do so, follow these steps: 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 (``/apps``) or :ref:`a custom app folder `. + +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 ``/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 diff --git a/admin_manual/installation/examples/appinfo.xml b/admin_manual/installation/examples/appinfo.xml new file mode 100644 index 000000000..5b08a6424 --- /dev/null +++ b/admin_manual/installation/examples/appinfo.xml @@ -0,0 +1,6 @@ + + + yourappname + Your App + 1.0 + From 25f7500335aadebe778c8de9bf5bc716a3fe0f7c Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Wed, 20 Dec 2017 13:47:11 +0100 Subject: [PATCH 3/3] Minor text correction --- admin_manual/installation/apps_management_installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/admin_manual/installation/apps_management_installation.rst b/admin_manual/installation/apps_management_installation.rst index 4645f8933..c4ad604e0 100644 --- a/admin_manual/installation/apps_management_installation.rst +++ b/admin_manual/installation/apps_management_installation.rst @@ -56,7 +56,7 @@ These are: #. 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``. +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: