From 659605fb907d6cb8a18e5c776204bbab96ba9d5b Mon Sep 17 00:00:00 2001 From: kafonek Date: Tue, 4 Jun 2019 05:51:29 -0400 Subject: [PATCH 01/14] Adding directions for configuring a 'shared-directory' --- docs/howto/content/share-data.rst | 13 +++++- docs/howto/content/shared-directory.rst | 56 +++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 docs/howto/content/shared-directory.rst diff --git a/docs/howto/content/share-data.rst b/docs/howto/content/share-data.rst index b0e7e06..0a83edc 100644 --- a/docs/howto/content/share-data.rst +++ b/docs/howto/content/share-data.rst @@ -5,7 +5,7 @@ Share data with your users ========================== There are a few options for sharing data with your users, this page covers -a few useful patterns. +a few useful patterns. Option 1: Distributing data with `nbgitpuller` ============================================== @@ -78,3 +78,14 @@ From now on, when a new user account is created, their home directory will have this symbolic link (and any other files in ``/etc/skel``) in their home directory. This will have **no effect on the directories of existing users**. + +Option 3: Create a directory for users to share Notebooks and other files +========================================================================= + +You may want a place for users to share files with each other rather than +only having administrators share files with users (Option 2). In this +configuration, any user can put files into ``/srv/scratch`` that other users +can read. However, only the user that created the file can edit the file. + +For information on creating and sharing a **shared directory** for users, see +:ref:`howto/content/shared-directory`. \ No newline at end of file diff --git a/docs/howto/content/shared-directory.rst b/docs/howto/content/shared-directory.rst new file mode 100644 index 0000000..7290204 --- /dev/null +++ b/docs/howto/content/shared-directory.rst @@ -0,0 +1,56 @@ +.. _howto/content/share-data: + +================================================= +Shared-directory for users to "publish" Notebooks +================================================= + +One way for users to share or "publish" Notebooks in a JupyterHub environment +is to create a shared directory. Any user can create files in the directory, +but only the creator may edit that file afterwards. + +For instance, in a Hub with three users, User A develops a Notebook in their +`/home` directory. When it is ready to share, User A copies it to the +`shared` directory. At that time, User B and User C can see User A's +Notebook and run it themselves (or view it in a Dashboard layout +such as `voila` or `panel` if that is running in the Hub), but User B +and User C cannot edit the Notebook. Only User A can make changes. + + +#. **Log** in to your JupyterHub as an **administrator user**. + +#. **Create a terminal session** with your JupyterHub interface. + + .. image:: ../../images/notebook/new-terminal-button.png + :alt: New terminal button. + +#. **Create a folder** where your data will live. We recommend placing shared + data in ``/srv``. The following command creates a directory ``/srv/scratch`` + + .. code-block:: bash + + sudo mkdir -p /srv/scratch + +#. **Change group ownership** of the new folder + + .. code-block:: bash + + sudo chown root:jupyterhub-users /srv/scratch + +#. **Change default permissions to use group**. The default permissions for new + sub-directories uses the global umask (``drwxr-sr-x``), the ``chmod g+s`` tells + new files to use the default permissions for the group ``jupyterhub-users`` + (``rw-r--r--``) + + .. code-block:: bash + + sudo chmod 777 /srv/scratch + sudo chmod g+s /srv/scratch + + +#. **Create a symbolic link** to the scratch folder in users home directories + + .. code-block:: bash + + sudo ln -s /srv/scratch /etc/skel/scratch + + From 645bedded0dcfb22fb47c6dc6ae024025cd300c6 Mon Sep 17 00:00:00 2001 From: kafonek Date: Tue, 4 Jun 2019 07:34:14 -0400 Subject: [PATCH 02/14] formatting for shared-directory docs --- docs/howto/content/shared-directory.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/content/shared-directory.rst b/docs/howto/content/shared-directory.rst index 7290204..188ca82 100644 --- a/docs/howto/content/shared-directory.rst +++ b/docs/howto/content/shared-directory.rst @@ -34,7 +34,7 @@ and User C cannot edit the Notebook. Only User A can make changes. .. code-block:: bash - sudo chown root:jupyterhub-users /srv/scratch + sudo chown root:jupyterhub-users /srv/scratch #. **Change default permissions to use group**. The default permissions for new sub-directories uses the global umask (``drwxr-sr-x``), the ``chmod g+s`` tells From 17294b76d217b819619f7799f15c343482423acb Mon Sep 17 00:00:00 2001 From: kafonek Date: Tue, 4 Jun 2019 07:36:27 -0400 Subject: [PATCH 03/14] formatting for shared-directory docs --- docs/howto/content/shared-directory.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/howto/content/shared-directory.rst b/docs/howto/content/shared-directory.rst index 188ca82..0a64e4a 100644 --- a/docs/howto/content/shared-directory.rst +++ b/docs/howto/content/shared-directory.rst @@ -32,9 +32,9 @@ and User C cannot edit the Notebook. Only User A can make changes. #. **Change group ownership** of the new folder - .. code-block:: bash + .. code-block:: bash - sudo chown root:jupyterhub-users /srv/scratch + sudo chown root:jupyterhub-users /srv/scratch #. **Change default permissions to use group**. The default permissions for new sub-directories uses the global umask (``drwxr-sr-x``), the ``chmod g+s`` tells From 62a83cdc3a33fc3260901f75ac017a1c446c7df0 Mon Sep 17 00:00:00 2001 From: kafonek Date: Tue, 4 Jun 2019 11:39:59 -0400 Subject: [PATCH 04/14] included plugin link --- docs/howto/content/shared-directory.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/howto/content/shared-directory.rst b/docs/howto/content/shared-directory.rst index 0a64e4a..18d3a65 100644 --- a/docs/howto/content/shared-directory.rst +++ b/docs/howto/content/shared-directory.rst @@ -54,3 +54,8 @@ and User C cannot edit the Notebook. Only User A can make changes. sudo ln -s /srv/scratch /etc/skel/scratch +======================= +Shared-directory plugin +======================= + +A TLJH Plugin at https://github.com/kafonek/tljh-shared-directory installs ``voila`` and sets up the directories as specified above. Include ``--plugin git+https://github.com/kafonek/tljh-shared-directory`` in your deployment startup script. \ No newline at end of file From 9ac9f0499777dc2f6d98246a9bfa2ef3e4685e38 Mon Sep 17 00:00:00 2001 From: kafonek Date: Wed, 5 Jun 2019 06:23:08 -0400 Subject: [PATCH 05/14] plugin docs update --- docs/contributing/plugins.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/contributing/plugins.rst b/docs/contributing/plugins.rst index a51369b..396d875 100644 --- a/docs/contributing/plugins.rst +++ b/docs/contributing/plugins.rst @@ -21,6 +21,17 @@ points in the application that can be explicitly extended by plugins, balancing the need to change TLJH internals in the future with the stability required for a good plugin ecosystem. +Installing Plugins +================== + +Include ``--plugin `` in the Installer script. See :ref:`topics/customizing-installer#installing-tljh-plugins` for more info. + +Example Plugins +=============== + + - .. tljh-pangeo: https://github.com/yuvipanda/tljh-pangeo + - .. shared-directory: https://github.com/kafonek/tljh-shared-directory + Writing a simple plugins ======================== From b52ac8eebb6c9703a101018a3455a8324854fe56 Mon Sep 17 00:00:00 2001 From: kafonek Date: Wed, 5 Jun 2019 06:33:02 -0400 Subject: [PATCH 06/14] rst syntax is hard --- docs/contributing/plugins.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/plugins.rst b/docs/contributing/plugins.rst index 396d875..75d250c 100644 --- a/docs/contributing/plugins.rst +++ b/docs/contributing/plugins.rst @@ -29,8 +29,8 @@ Include ``--plugin `` in the Installer script. See :ref:`topics/c Example Plugins =============== - - .. tljh-pangeo: https://github.com/yuvipanda/tljh-pangeo - - .. shared-directory: https://github.com/kafonek/tljh-shared-directory + - `tljh-pangeo `_ + - `shared-directory `_ Writing a simple plugins ======================== From b8e2ff5fe96af0f3c09b794e349b0cfa8d5c2542 Mon Sep 17 00:00:00 2001 From: kafonek Date: Wed, 5 Jun 2019 06:34:20 -0400 Subject: [PATCH 07/14] rst syntax is hard --- docs/contributing/plugins.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/plugins.rst b/docs/contributing/plugins.rst index 75d250c..a3bf803 100644 --- a/docs/contributing/plugins.rst +++ b/docs/contributing/plugins.rst @@ -29,8 +29,8 @@ Include ``--plugin `` in the Installer script. See :ref:`topics/c Example Plugins =============== - - `tljh-pangeo `_ - - `shared-directory `_ + - `tljh-pangeo `_ + - `shared-directory `_ Writing a simple plugins ======================== From 278de7dd7b3b7da4527a41f553cef7057ba9db67 Mon Sep 17 00:00:00 2001 From: kafonek Date: Wed, 5 Jun 2019 06:37:58 -0400 Subject: [PATCH 08/14] fix name for plugin examples --- docs/contributing/plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/plugins.rst b/docs/contributing/plugins.rst index a3bf803..755d71d 100644 --- a/docs/contributing/plugins.rst +++ b/docs/contributing/plugins.rst @@ -30,7 +30,7 @@ Example Plugins =============== - `tljh-pangeo `_ - - `shared-directory `_ + - `tljh-shared-directory `_ Writing a simple plugins ======================== From dc4011b90fa0caf3836d30de78e985f2361696b5 Mon Sep 17 00:00:00 2001 From: kafonek Date: Wed, 5 Jun 2019 06:56:20 -0400 Subject: [PATCH 09/14] fix to .rst label --- docs/howto/content/shared-directory.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/content/shared-directory.rst b/docs/howto/content/shared-directory.rst index 18d3a65..b8a667d 100644 --- a/docs/howto/content/shared-directory.rst +++ b/docs/howto/content/shared-directory.rst @@ -1,4 +1,4 @@ -.. _howto/content/share-data: +.. _howto/content/shared-directory: ================================================= Shared-directory for users to "publish" Notebooks From 113e1cf3ac3778641b9cf3a0200f649e80cd23b1 Mon Sep 17 00:00:00 2001 From: kafonek Date: Wed, 5 Jun 2019 07:10:53 -0400 Subject: [PATCH 10/14] fix :ref: to customizing installer --- docs/contributing/plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/plugins.rst b/docs/contributing/plugins.rst index 755d71d..3f91244 100644 --- a/docs/contributing/plugins.rst +++ b/docs/contributing/plugins.rst @@ -24,7 +24,7 @@ stability required for a good plugin ecosystem. Installing Plugins ================== -Include ``--plugin `` in the Installer script. See :ref:`topics/customizing-installer#installing-tljh-plugins` for more info. +Include ``--plugin `` in the Installer script. See :ref:`topics/customizing-installer` for more info. Example Plugins =============== From 680eb679da014f425b922b066c2e4d34556cd500 Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Wed, 5 Jun 2019 17:14:18 +0200 Subject: [PATCH 11/14] Fix typo --- docs/contributing/plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/plugins.rst b/docs/contributing/plugins.rst index 3f91244..faeb75c 100644 --- a/docs/contributing/plugins.rst +++ b/docs/contributing/plugins.rst @@ -24,7 +24,7 @@ stability required for a good plugin ecosystem. Installing Plugins ================== -Include ``--plugin `` in the Installer script. See :ref:`topics/customizing-installer` for more info. +Include ``--plugin `` in the Installer script. See :ref:`topic/customizing-installer` for more info. Example Plugins =============== From b1cdd9733b976defda69f22c91a4d59fcd92f73b Mon Sep 17 00:00:00 2001 From: GeorgianaElena Date: Thu, 22 Oct 2020 10:28:34 +0300 Subject: [PATCH 12/14] Add shared-directory to index --- docs/howto/content/shared-directory.rst | 1 - docs/howto/index.rst | 2 ++ 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/howto/content/shared-directory.rst b/docs/howto/content/shared-directory.rst index b8a667d..67a1668 100644 --- a/docs/howto/content/shared-directory.rst +++ b/docs/howto/content/shared-directory.rst @@ -54,7 +54,6 @@ and User C cannot edit the Notebook. Only User A can make changes. sudo ln -s /srv/scratch /etc/skel/scratch -======================= Shared-directory plugin ======================= diff --git a/docs/howto/index.rst b/docs/howto/index.rst index 9f6369a..e69bfc7 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -7,6 +7,7 @@ How-To Guides content/nbgitpuller content/add-data content/share-data + content/shared-directory env/user-environment env/notebook-interfaces env/server-resources @@ -36,6 +37,7 @@ Content and Data content/nbgitpuller content/add-data content/share-data + content/shared-directory The user environment -------------------- From 5890a490614d83c6690fb9275331ce5b9506c02b Mon Sep 17 00:00:00 2001 From: GeorgianaElena Date: Thu, 22 Oct 2020 13:48:11 +0300 Subject: [PATCH 13/14] Move example plugins to the already existing list --- docs/contributing/plugins.rst | 10 +++------- docs/howto/content/shared-directory.rst | 3 ++- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/contributing/plugins.rst b/docs/contributing/plugins.rst index faeb75c..173553a 100644 --- a/docs/contributing/plugins.rst +++ b/docs/contributing/plugins.rst @@ -26,12 +26,6 @@ Installing Plugins Include ``--plugin `` in the Installer script. See :ref:`topic/customizing-installer` for more info. -Example Plugins -=============== - - - `tljh-pangeo `_ - - `tljh-shared-directory `_ - Writing a simple plugins ======================== @@ -137,10 +131,12 @@ If you are looking for a way to extend or customize your TLJH deployment, you mi Here is a non-exhaustive list of known TLJH plugins: -- `tljh-pangeo `_: TLJH Plugin for setting up the Pangeo Stack +- `tljh-pangeo `_: TLJH plugin for setting up the Pangeo Stack - `tljh-voila-gallery `_: TLJH plugin that installs a gallery of Voilà dashboards - `tljh-repo2docker `_: TLJH plugin to build multiple user environments with `repo2docker `_. +- `tljh-shared-directory `_: TLJH plugin which sets up a *shared directory* + for the Hub users in ``/srv/scratch``. If you have authored a plugin, please open a PR to add it to this list! diff --git a/docs/howto/content/shared-directory.rst b/docs/howto/content/shared-directory.rst index 67a1668..b7bb6b3 100644 --- a/docs/howto/content/shared-directory.rst +++ b/docs/howto/content/shared-directory.rst @@ -57,4 +57,5 @@ and User C cannot edit the Notebook. Only User A can make changes. Shared-directory plugin ======================= -A TLJH Plugin at https://github.com/kafonek/tljh-shared-directory installs ``voila`` and sets up the directories as specified above. Include ``--plugin git+https://github.com/kafonek/tljh-shared-directory`` in your deployment startup script. \ No newline at end of file +A TLJH Plugin at https://github.com/kafonek/tljh-shared-directory installs ``voila`` and sets up the directories as specified above. +Include ``--plugin git+https://github.com/kafonek/tljh-shared-directory`` in your deployment startup script. \ No newline at end of file From f1e89501d2d3a9605d37799c140208d99573428b Mon Sep 17 00:00:00 2001 From: GeorgianaElena Date: Thu, 22 Oct 2020 14:21:07 +0300 Subject: [PATCH 14/14] Move shared-directory to how to share data section Co-authored-by: kafonek --- docs/howto/content/share-data.rst | 54 ++++++++++++++++++++-- docs/howto/content/shared-directory.rst | 61 ------------------------- docs/howto/index.rst | 2 - 3 files changed, 51 insertions(+), 66 deletions(-) delete mode 100644 docs/howto/content/shared-directory.rst diff --git a/docs/howto/content/share-data.rst b/docs/howto/content/share-data.rst index 0a83edc..5e98324 100644 --- a/docs/howto/content/share-data.rst +++ b/docs/howto/content/share-data.rst @@ -85,7 +85,55 @@ Option 3: Create a directory for users to share Notebooks and other files You may want a place for users to share files with each other rather than only having administrators share files with users (Option 2). In this configuration, any user can put files into ``/srv/scratch`` that other users -can read. However, only the user that created the file can edit the file. +can read. However, only the user that created the file can edit the file. -For information on creating and sharing a **shared directory** for users, see -:ref:`howto/content/shared-directory`. \ No newline at end of file +One way for users to share or "publish" Notebooks in a JupyterHub environment +is to create a shared directory. Any user can create files in the directory, +but only the creator may edit that file afterwards. + +For instance, in a Hub with three users, User A develops a Notebook in their +``/home`` directory. When it is ready to share, User A copies it to the +`shared` directory. At that time, User B and User C can see User A's +Notebook and run it themselves (or view it in a Dashboard layout +such as ``voila`` or ``panel`` if that is running in the Hub), but User B +and User C cannot edit the Notebook. Only User A can make changes. + +#. **Log** in to your JupyterHub as an **administrator user**. + +#. **Create a terminal session** with your JupyterHub interface. + + .. image:: ../../images/notebook/new-terminal-button.png + :alt: New terminal button. + +#. **Create a folder** where your data will live. We recommend placing shared + data in ``/srv``. The following command creates a directory ``/srv/scratch`` + + .. code-block:: bash + + sudo mkdir -p /srv/scratch + +#. **Change group ownership** of the new folder + + .. code-block:: bash + + sudo chown root:jupyterhub-users /srv/scratch + +#. **Change default permissions to use group**. The default permissions for new + sub-directories uses the global umask (``drwxr-sr-x``), the ``chmod g+s`` tells + new files to use the default permissions for the group ``jupyterhub-users`` + (``rw-r--r--``) + + .. code-block:: bash + + sudo chmod 777 /srv/scratch + sudo chmod g+s /srv/scratch + +#. **Create a symbolic link** to the scratch folder in users home directories + + .. code-block:: bash + + sudo ln -s /srv/scratch /etc/skel/scratch + +.. note:: + The TLJH Plugin at https://github.com/kafonek/tljh-shared-directory installs ``voila`` and sets up the directories as specified above. + Include ``--plugin git+https://github.com/kafonek/tljh-shared-directory`` in your deployment startup script to install it. \ No newline at end of file diff --git a/docs/howto/content/shared-directory.rst b/docs/howto/content/shared-directory.rst deleted file mode 100644 index b7bb6b3..0000000 --- a/docs/howto/content/shared-directory.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _howto/content/shared-directory: - -================================================= -Shared-directory for users to "publish" Notebooks -================================================= - -One way for users to share or "publish" Notebooks in a JupyterHub environment -is to create a shared directory. Any user can create files in the directory, -but only the creator may edit that file afterwards. - -For instance, in a Hub with three users, User A develops a Notebook in their -`/home` directory. When it is ready to share, User A copies it to the -`shared` directory. At that time, User B and User C can see User A's -Notebook and run it themselves (or view it in a Dashboard layout -such as `voila` or `panel` if that is running in the Hub), but User B -and User C cannot edit the Notebook. Only User A can make changes. - - -#. **Log** in to your JupyterHub as an **administrator user**. - -#. **Create a terminal session** with your JupyterHub interface. - - .. image:: ../../images/notebook/new-terminal-button.png - :alt: New terminal button. - -#. **Create a folder** where your data will live. We recommend placing shared - data in ``/srv``. The following command creates a directory ``/srv/scratch`` - - .. code-block:: bash - - sudo mkdir -p /srv/scratch - -#. **Change group ownership** of the new folder - - .. code-block:: bash - - sudo chown root:jupyterhub-users /srv/scratch - -#. **Change default permissions to use group**. The default permissions for new - sub-directories uses the global umask (``drwxr-sr-x``), the ``chmod g+s`` tells - new files to use the default permissions for the group ``jupyterhub-users`` - (``rw-r--r--``) - - .. code-block:: bash - - sudo chmod 777 /srv/scratch - sudo chmod g+s /srv/scratch - - -#. **Create a symbolic link** to the scratch folder in users home directories - - .. code-block:: bash - - sudo ln -s /srv/scratch /etc/skel/scratch - - -Shared-directory plugin -======================= - -A TLJH Plugin at https://github.com/kafonek/tljh-shared-directory installs ``voila`` and sets up the directories as specified above. -Include ``--plugin git+https://github.com/kafonek/tljh-shared-directory`` in your deployment startup script. \ No newline at end of file diff --git a/docs/howto/index.rst b/docs/howto/index.rst index e69bfc7..9f6369a 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -7,7 +7,6 @@ How-To Guides content/nbgitpuller content/add-data content/share-data - content/shared-directory env/user-environment env/notebook-interfaces env/server-resources @@ -37,7 +36,6 @@ Content and Data content/nbgitpuller content/add-data content/share-data - content/shared-directory The user environment --------------------