From 7c950f4aaee0de18abc1d24f171f27e014e5af23 Mon Sep 17 00:00:00 2001 From: Josh Richards Date: Thu, 5 Mar 2026 10:04:52 -0500 Subject: [PATCH 1/2] refactor(admin): improve data directory move section in troubleshooting chapter Signed-off-by: Josh Richards --- .../issues/general_troubleshooting.rst | 63 +++++++++++++------ 1 file changed, 43 insertions(+), 20 deletions(-) diff --git a/admin_manual/issues/general_troubleshooting.rst b/admin_manual/issues/general_troubleshooting.rst index 65b8146ae41..b2a5c3cd91f 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -325,7 +325,7 @@ There are also several techniques to remedy this, which are described extensivel the `Sabre DAV website `_. Troubleshooting sharing ------------------------------------ +----------------------- Users' Federated Cloud IDs not updated after a domain name change ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -375,32 +375,55 @@ Troubleshooting contacts & calendar Troubleshooting data-directory ------------------------------ -If you have a fresh install, consider reinstalling with your preferred directory location. +Moving the data directory / changing the ``datadirectory`` path +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Unofficially moving the data directory can be done as follows: +For local storage, Nextcloud identifies storage by its absolute path on disk. +Ideally, the location of the data directory should not change after deployment. If +this is a new installation, consider reinstalling with your preferred directory +location before moving into production. -1. Make sure no cron jobs are running -2. Stop apache -3. Move /data to the new location -4. Change the config.php entry -5. Edit the database: In oc_storages change the path on the local::/old-data-dir/ entry -6. Ensure permissions are still correct -7. Restart apache +.. danger:: + If you must change the ``datadirectory`` path -- unless the transition is handled + carefully -- Nextcloud will treat its content as "new storage." This can trigger + duplicate or orphaned files, lost file metadata, and the loss of previously shared + links. -.. warning:: - However this is not supported and you risk breaking your database. +For safely moving the data directory, the recommended actions are: -For a safe moving of data directory, supported by Nextcloud, recommended actions are: +1. Make sure no cron jobs are running and, if using system cron, that the Nextcloud crontab +entry is disabled. +2. Stop web/app server(s). +3. Move ``/data`` to the new location (ensure you also move hidden/dot files such as +``.ncdata``). +4. Create a symlink from the original location to the new location. +5. Ensure permissions are still correct (including for any parent folders). +6. Restart web/app server(s). +7. Re-enable Nextcloud's system crontab entry (if applicable). -1. Make sure no cron jobs are running -2. Stop apache -3. Move /data to the new location -4. Create a symlink from the original location to the new location -5. Ensure permissions are still correct -6. Restart apache +.. note:: + You may need to configure your web server to support symlinks. + +It is also possible to move the data directory without using symlinks, but +this requires manually modifying the internal ``oc_storages`` database table: + +1. Make sure no cron jobs are running and, if using system cron, that the Nextcloud crontab +entry is disabled. +2. Stop web/app server(s). +3. Move ``/data`` to the new location (ensure you also move hidden/dot files such as +``.ncdata``). +4. Update the value of ``datadirectory`` in your ``config.php``. +5. Edit the database: In the ``oc_storages`` table, update the path portion of the ``id`` +field of the entry beginning with ``local::/old-data-dir/`` (e.g., change +``local::/old-data-dir/`` to ``local::/new-data-dir/``). +6. Ensure permissions are still correct (including for any parent folders). +7. Restart web/app server(s). +8. Re-enable Nextcloud's system crontab entry (if applicable). .. warning:: - Note, you may need to configure your webserver to support symlinks. + This method is not supported and you risk breaking your database. Always make sure you + have up-to-date backups -- including your database -- and a working (tested) restore + process **before** attempting this. Troubleshooting quota or size issues ------------------------------------ From 3ab3edc638edb971957644e39653ec60781c7210 Mon Sep 17 00:00:00 2001 From: Josh Richards Date: Thu, 5 Mar 2026 10:19:42 -0500 Subject: [PATCH 2/2] chore: fixup list formating Signed-off-by: Josh Richards --- .../issues/general_troubleshooting.rst | 30 ++++++++++++------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/admin_manual/issues/general_troubleshooting.rst b/admin_manual/issues/general_troubleshooting.rst index b2a5c3cd91f..6ce1845ca81 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -391,14 +391,18 @@ location before moving into production. For safely moving the data directory, the recommended actions are: -1. Make sure no cron jobs are running and, if using system cron, that the Nextcloud crontab -entry is disabled. +1. Make sure no cron jobs are running and, if using system cron, that the Nextcloud crontab entry is disabled. + 2. Stop web/app server(s). -3. Move ``/data`` to the new location (ensure you also move hidden/dot files such as -``.ncdata``). + +3. Move ``/data`` to the new location (ensure you also move hidden/dot files such as ``.ncdata``). + 4. Create a symlink from the original location to the new location. + 5. Ensure permissions are still correct (including for any parent folders). + 6. Restart web/app server(s). + 7. Re-enable Nextcloud's system crontab entry (if applicable). .. note:: @@ -407,17 +411,21 @@ entry is disabled. It is also possible to move the data directory without using symlinks, but this requires manually modifying the internal ``oc_storages`` database table: -1. Make sure no cron jobs are running and, if using system cron, that the Nextcloud crontab -entry is disabled. +1. Make sure no cron jobs are running and, if using system cron, that the Nextcloud crontab entry is disabled. + 2. Stop web/app server(s). -3. Move ``/data`` to the new location (ensure you also move hidden/dot files such as -``.ncdata``). + +3. Move ``/data`` to the new location (ensure you also move hidden/dot files such as ``.ncdata``). + 4. Update the value of ``datadirectory`` in your ``config.php``. -5. Edit the database: In the ``oc_storages`` table, update the path portion of the ``id`` -field of the entry beginning with ``local::/old-data-dir/`` (e.g., change -``local::/old-data-dir/`` to ``local::/new-data-dir/``). + +5. Edit the database: In the ``oc_storages`` table, update the path portion of the ``id`` field of the entry + beginning with ``local::/old-data-dir/`` (e.g., change ``local::/old-data-dir/`` to ``local::/new-data-dir/``). + 6. Ensure permissions are still correct (including for any parent folders). + 7. Restart web/app server(s). + 8. Re-enable Nextcloud's system crontab entry (if applicable). .. warning::