diff --git a/docs/contributing/plugins.rst b/docs/contributing/plugins.rst index a51369b..173553a 100644 --- a/docs/contributing/plugins.rst +++ b/docs/contributing/plugins.rst @@ -21,6 +21,11 @@ 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:`topic/customizing-installer` for more info. + Writing a simple plugins ======================== @@ -126,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/share-data.rst b/docs/howto/content/share-data.rst index b0e7e06..5e98324 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,62 @@ 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. + +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