From ef7c5dd1936f21c150f9976814b02a08a764d2dd 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 93b4acf4375..197a93cecbc 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -327,7 +327,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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -377,32 +377,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 2ae7b06f8c94750ca4a0bcd5fe42a4190c4cdaab 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 197a93cecbc..afb4f41d8d3 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -393,14 +393,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:: @@ -409,17 +413,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::