mounting rclone (da16d9ff) · Commits · Solidipes / DCSM server documentation

src/user_guide.rst

+157 −2

Changes for src/user_guide.rst: 157 added lines, 2 removed lines.
Original line number	Diff line number	Diff line
		@@ -12,6 +12,10 @@ Open the platform in your browser:

		Production deployment (login via ORCID authentication)

		.. note::

		all authors of a dataset (included in metadata, with their ORCID specified) have read and write access


		2. Create a new curation
		------------------------
		@@ -246,7 +250,7 @@ A dataset can be started, stopped, and restarted at any time:
		:width: 600px
		:align: center

		Restart button in the DCSM interface.
		Example of the Restart button in the DCSM interface. The interface may look different in other versions.

		.. note::

		@@ -279,6 +283,12 @@ through different interfaces depending on your needs.

		.. dropdown:: Solidipes Curation

		.. note::

		For a complete overview of Solidipes, refer to the official documentation:

		`Solidipes User Documentation <https://solidipes.readthedocs.io/en/stable/src/user/index.html>`_

		Click on Solidipes Curation to access the curation interface.

		.. figure:: images/solidipes.png
		@@ -469,6 +479,8 @@ Three protocols are available:
		Rclone allows you to access and manage your dataset files directly from
		the terminal through the DCSM WebDAV endpoint.

		.. dropdown:: Configuration

		Installation

		If Rclone is not already installed on your machine, follow the official
		@@ -511,7 +523,7 @@ Three protocols are available:
		- Manually by editing the Rclone configuration file
		- Automatically using the interactive Rclone configuration command

		Manual configuration
		.. dropdown:: Manual configuration (optional)

		Open the Rclone configuration file in a text editor. The file is usually located at:

		@@ -609,6 +621,8 @@ Three protocols are available:

		~/.config/rclone/rclone.conf

		.. dropdown:: Rclone usage

		.. dropdown:: Accessing dataset files

		List the files available in the dataset:
		@@ -639,6 +653,147 @@ Three protocols are available:

		rclone sync ./local_directory testdataset1:/destination_directory

		.. dropdown:: mounting the dataset

		If you don't have enough local disk space to copy the entire dataset (e.g., 1TB of data),
		you can mount it as a virtual drive instead. This allows you to access the files directly
		without downloading them locally.

		Mounting is an alternative to copying or syncing files, especially useful for large datasets.

		.. important::

		Before mounting, ensure that Rclone is already configured with your dataset remote.
		If you haven't configured Rclone yet, follow the Configuration steps above first.

		.. warning::

		Rclone installed via Homebrew does not support the mount command on macOS.
		You must install Rclone from the official binary.

		To install the official Rclone version:

		.. code-block:: bash

		# Remove Homebrew version if installed
		brew uninstall rclone

		# Install official version
		curl https://rclone.org/install.sh \| sudo bash

		Verify the installation:

		.. code-block:: bash

		rclone version

		You should see ``rclone v1.xx.x`` without any mention of Homebrew.


		Install macFUSE

		macFUSE is required to mount remote filesystems on macOS. It allows Rclone to create a virtual drive that appears as a local folder.

		.. code-block:: bash

		brew install --cask macfuse

		After installation, a popup may appear asking you to allow the kernel extension. If not, follow the steps below.

		Allow macFUSE kernel extension

		On macOS, system extensions must be manually approved. Follow these steps:

		1. Go to System Settings → Privacy & Security
		2. Scroll down to the Security section
		3. Look for a message like:
		- "System software from developer 'Benjamin Fleischer' was blocked..."
		- or simply "macFUSE"

		4. Click Allow or Approve
		5. Reboot your Mac (this is important!)

		.. dropdown:: If the security message does not appear

		If you don't see the message in System Settings:

		1. Try running the mount command (it will trigger the request):

		.. code-block:: bash

		rclone mount ya: ~/dcsm_mount_"name of your configured remote" --vfs-cache-mode writes

		Leave this command running and immediately go to System Settings.

		2. The message should now appear. Click Allow.

		3. If still nothing appears, you may need to start your Mac in Recovery Mode:

		- Shut down your Mac
		- Press and hold the power button until "Loading startup options" appears
		- Click Options → Continue
		- Open Startup Security Utility (in the Utilities menu)
		- Select your startup disk → Security Policy...
		- Choose Reduced Security
		- Check "Allow user management of kernel extensions from identified developers"
		- Restart your Mac and try again

		Test your Rclone connection

		Before mounting, verify that Rclone can access your dataset:

		.. code-block:: bash

		rclone ls "name of your configured remote":

		This should display the files and folders in your dataset.


		Create a mount point

		Create an empty directory where the dataset will be mounted:

		.. code-block:: bash

		mkdir ~/dcsm_mount

		Mount the dataset

		Mount your dataset to the mount point:

		.. code-block:: bash

		rclone mount ya: ~/dcsm_mount --daemon --vfs-cache-mode writes

		.. note::

		- The ``--daemon`` flag runs the mount in the background
		- The ``--vfs-cache-mode writes`` flag allows applications to write files normally

		Access the mounted dataset

		Once mounted, you can access the dataset as a local folder:

		.. code-block:: bash

		ls ~/dcsm_mount
		open ~/dcsm_mount

		Unmount the dataset

		When finished, unmount the dataset:

		.. code-block:: bash

		umount ~/dcsm_mount

		.. warning::

		Do not unmount while files are being accessed or written. This may cause data loss.




		.. dropdown:: Testing the connection

		Verify that the connection works correctly: