docs: filebrowser guide (#11)

* docs: add filebrowser guide in vfolder menu * docs: add images about using filebrowser * docs: minor revision Co-authored-by: Jonghyun Park <adrysn@gmail.com>
lablup · Mar 7, 2021 · a462314 · a462314
1 parent ddb3a9c
commit a462314
Show file tree

Hide file tree

Showing 13 changed files with 491 additions and 3 deletions.
diff --git a/docs/locale/ko/LC_MESSAGES/vfolder/vfolder.po b/docs/locale/ko/LC_MESSAGES/vfolder/vfolder.po
diff --git a/docs/vfolder/app_dialog_with_filebrowser.png b/docs/vfolder/app_dialog_with_filebrowser.png
diff --git a/docs/vfolder/click_arrow_icon.png b/docs/vfolder/click_arrow_icon.png
diff --git a/docs/vfolder/filebrowser_in_session_page.png b/docs/vfolder/filebrowser_in_session_page.png
diff --git a/docs/vfolder/filebrowser_upload.png b/docs/vfolder/filebrowser_upload.png
diff --git a/docs/vfolder/filebrowser_upload_finished.png b/docs/vfolder/filebrowser_upload_finished.png
diff --git a/docs/vfolder/filebrowser_with_new_window.png b/docs/vfolder/filebrowser_with_new_window.png
diff --git a/docs/vfolder/first_step_to_access_filebrowser.png b/docs/vfolder/first_step_to_access_filebrowser.png
diff --git a/docs/vfolder/folderexplorer_with_filebrowser.png b/docs/vfolder/folderexplorer_with_filebrowser.png
diff --git a/docs/vfolder/moving_operation_in_filebrowser_finished.png b/docs/vfolder/moving_operation_in_filebrowser_finished.png
diff --git a/docs/vfolder/select_folders.png b/docs/vfolder/select_folders.png
diff --git a/docs/vfolder/select_the_destination.png b/docs/vfolder/select_the_destination.png
diff --git a/docs/vfolder/vfolder.rst b/docs/vfolder/vfolder.rst
@@ -145,3 +145,154 @@ For more detailed information on the usage of Automount folders, refer to
 
 .. image:: vfolder_automount_folders.png
    :alt: Automount folders
+
+
+Using FileBrowser
+-----------------
+
+Backend.AI supports `FileBrowser <https://filebrowser.org>`_ from version
+20.09. FileBrowser is a program that helps you manage files on a remote server
+through a web browser. This is especially useful when uploading a directory from
+the user's local machine.
+
+Currently, Backend.AI provides a FileBrowser as an application of a compute
+session. Therefore, the following conditions are required to launch it.
+
+* User can create at least one compute session
+* User can allocated at least 1 core of CPU and 512 MB of memory
+* Image that supports FileBrowser has been installed
+
+You can access FileBrowser in two ways.
+
+* Execute FileBrowser from file explorere dialog of a data folder in Data &
+  Stroage page
+* Launch a compute session directly from a FileBrowser image on Sessions page
+
+
+Execute FileBrowser from folder explorer dialog in Data & Storage page
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Go to the Data & Storage page and open the file explorer dialog of target
+data folder. Click the folder icon in the Control column to the right of the
+data folder to open the file explorer.
+
+.. image:: first_step_to_access_filebrowser.png
+   :alt: first step to access FileBrowser
+
+.. warning::
+   You cannot launch FileBrowser from read-only data folders if .
+
+Click EXECUTE FILEBROWSER button in the upper-right corner of the explorer.
+
+.. image:: folderexplorer_with_filebrowser.png
+   :alt: Folder explorer with FileBrowser
+
+You can see the FileBrowser is opened in a new window. You can also see that the
+data folder you opened the explorer dialog becomes the root directory. From the
+FileBrowser window, you can freely upload, modify, and delete any directories
+and files.
+
+.. image:: filebrowser_with_new_window.png
+   :alt: FileBrowser with new window
+
+When user clicks EXECUTE FILEBROWSER, Backend.AI automatically creates a
+dedicated compute session for the app. So, in the Sessions page, you should see
+FileBrowser compute session. It is user's reponsibility to delete this compute
+session.
+
+.. image:: filebrowser_in_session_page.png
+   :alt: FileBrowser in session page
+
+.. note::
+   If you accidentally close the FileBrowser window and want to reopen it, just
+   go to Sessions page and click the FileBrowser application icon of the
+   FileBrowser compute session.
+
+   .. image:: app_dialog_with_FileBrowser.png
+      :align: center
+
+   |
+   | When you click EXECUTE FILEBROWSER button again in the data folder
+       explorer, a new compute session will be created and a total of two
+       FileBrowser sessions
+       will appear.
+
+Create a compute session with FileBrowser image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can directly create a compute session with FileBrowser supported images.
+You need to mount at least one or more data folders to access them. You can use
+FileBrowser without a problem even if you do not mount any data folder, but
+every uploaded/updated files will be lost after the session is terminated.
+
+.. note::
+   The root directory of FileBrowser will be ``/home/work``. Therefore, you
+   can access any mounted data folders for the compute session.
+
+Basic usage examples of FileBrowser
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here, we present some basic usage examples of FileBrowser in Backend.AI. Most
+of the FileBrowser operations are intuitive, but if you need more detailed
+guide, please refer to the
+`FileBrowser documentation <https://filebrowser.org>`_.
+
+**Upload local directory using FileBrowser**
+
+FileBrowser supports uploading one or more local directories while maintaining
+the tree structure. Click the upload button in the upper right corner of the
+window, and click Folder button. Then, local file explorer dialog will appear
+and you can select any directory you want to upload.
+
+.. image:: filebrowser_upload.png
+   :align: center
+
+Let's upload a directory with the following structure.
+
+.. code-block:: shell
+
+   foo
+   +-- test
+   |    +-- test2.txt
+   +-- test.txt
+
+After selecting ``foo`` directory, you can see the directory just uploaded
+successfully.
+
+.. image:: FileBrowser_upload_finished.png
+
+You can also upload local files and directories by drag and drop.
+
+**Move files or directories to another directory**
+
+Moving files or directories in data folder is also possible from FileBrowser.
+You can move files or directories by following steps below.
+
+1. Select directories or files from FileBrowser.
+
+.. image:: select_folders.png
+   :align: center
+
+2. Click the arrow icon in the upper right corner of FileBrowser
+
+.. image:: click_arrow_icon.png
+   :width: 400
+   :align: center
+
+3. Select the destination
+
+.. image:: select_the_destination.png
+   :width: 400
+   :align: center
+
+4. Click MOVE button
+
+You will see that moving operation is successfully finished.
+
+.. image:: moving_operation_in_filebrowser_finished.png
+   :align: center
+
+.. note::
+   FileBrowser is provided via application inside a compute session currently.
+   We are planning to update FileBrowser so that it can run independently
+   without creating a session.