zhangyiss/the-littlest-jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/the-littlest-jupyterhub.git synced 2025-12-18 21:54:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

updating content from zexuan's user test

Browse Source
This commit is contained in:
Chris Holdgraf
2018-08-10 10:09:24 -07:00
committed by yuvipanda
parent 258e350abc
commit 2181947f83
21 changed files with 468 additions and 200 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
docs/howto/admin-users.rst
View File

@@ -1,55 +0,0 @@
.. _howto/admin-users:
========================
Add / Remove admin users
========================
Admin users in TLJH have the following powers:
#. Full root access to the server with passwordless ``sudo``.
This lets them do literally whatever they want in the server
#. Access servers / home directories of all other users
#. Install new packages for everyone with ``conda``, ``pip`` or ``apt``
#. Change configuration of TLJH
This is a lot of power, so make sure you know who you are giving it
to. Admin users should have decent passwords / secure logni mechanisms,
so attackers can not easily gain control of the system.
Make sure an admin user is present
==================================
You should make sure an admin user is present when you **install** TLJH
the very first time. The ``:ref:`--admin <topic/customizing-installer/admin>```
flag passed to the installer does this. If you had forgotten to do so, the
easiest way to fix this is to run the installer again.
Adding new admin users
======================
New admin users can be added by executing the following commands on an
admin terminal:
.. code-block:: bash
sudo -E tljh-config add-item users.admin <username>
sudo -E tljh-config reload
If the user is already using the JupyterHub, they might have to stop and
start their server from the control panel to gain new powers.
Removing admin users
====================
You can remove an existing admin user by executing the following commands in
an admin terminal:
.. code-block:: bash
sudo -E tljh-config remove-item users.admin <username>
sudo -E tljh-config reload
If the user is already using the JupyterHub, they will continue to have
some of their admin powers until their server is stopped. Another admin
can force their server to stop by clicking 'Stop Server' in the admin
panel.

101
docs/howto/admin/admin-users.rst Normal file
View File

@@ -0,0 +1,101 @@
.. _howto/admin/admin-users:
========================
Add / Remove admin users
========================
Admin users in TLJH have the following powers:
#. Full root access to the server with passwordless ``sudo``.
This lets them do literally whatever they want in the server
#. Access servers / home directories of all other users
#. Install new packages for everyone with ``conda``, ``pip`` or ``apt``
#. Change configuration of TLJH
This is a lot of power, so make sure you know who you are giving it
to. Admin users should have decent passwords / secure logni mechanisms,
so attackers can not easily gain control of the system.
.. important::
You should make sure an admin user is present when you **install** TLJH
the very first time. The ``:ref:`--admin <topic/customizing-installer/admin>```
flag passed to the installer does this. If you had forgotten to do so, the
easiest way to fix this is to run the installer again.
Adding admin users from the JupyterHub interface
================================================
There are two primary user interfaces for doing work on your JupyterHub. By
default, this is the Notebook Interface, and will be used in this section.
If you are using JupyterLab, you can access the Notebook Interface by replacing
``/lab`` with ``/tree`` in your URL.
#. First, navigate to the Jupyter Notebook interface home page. You can do this
by going to the URL ``<my-hub-url>/user/<my-username>/tree``.
#. Open the **Control Panel** by clicking the control panel button on the top
right of your JupyterHub.
.. image:: ../../images/control-panel-button.png
:alt: Control panel button in notebook, top right
#. In the control panel, open the **Admin** link in the top left.
.. image:: ../../images/admin/admin-access-button.png
:alt: Admin button in control panel, top left
This opens up the JupyterHub admin page, where you can add / delete users,
start / stop peoples' servers and see who is online.
#. Click the **Add Users** button.
.. image:: ../../images/admin/add-users-button.png
:alt: Add Users button in the admin page
A **Add Users** dialog box opens up.
#. Type the names of users you want to add to this JupyterHub in the dialog box,
one per line. **Make sure to tick the Admin checkbox**.
.. image:: ../../images/admin/add-users-dialog.png
:alt: Adding users with add users dialog
#. Click the **Add Users** button in the dialog box. Your users are now added
to the JupyterHub with administrator privileges!
Adding admin users from the command line
========================================
Sometimes it is easier to add or remove admin users from the command line (for
example, if you forgot to add an admin user when first setting up your JupyterHub).
Adding new admin users
----------------------
New admin users can be added by executing the following commands on an
admin terminal:
.. code-block:: bash
sudo -E tljh-config add-item users.admin <username>
sudo -E tljh-config reload
If the user is already using the JupyterHub, they might have to stop and
start their server from the control panel to gain new powers.
Removing admin users
--------------------
You can remove an existing admin user by executing the following commands in
an admin terminal:
.. code-block:: bash
sudo -E tljh-config remove-item users.admin <username>
sudo -E tljh-config reload
If the user is already using the JupyterHub, they will continue to have
some of their admin powers until their server is stopped. Another admin
can force their server to stop by clicking 'Stop Server' in the admin
panel.

2
docs/howto/https.rst → docs/howto/admin/https.rst
View File

@@ -1,4 +1,4 @@
.. _howto/https:
.. _howto/admin/https:
============
Enable HTTPS

4
docs/howto/nbresuse.rst → docs/howto/admin/nbresuse.rst
View File

@@ -1,4 +1,4 @@
.. _howto/nbresuse:
.. _howto/admin/nbresuse:
=======================
Check your memory usage
@@ -11,5 +11,5 @@ top right corner of the notebook interface. Note that this is memory usage
for everything your user is running through the Jupyter notebook interface,
not just the specific notebook it is shown on.
.. image:: ../images/nbresuse.png
.. image:: ../../images/nbresuse.png
:alt: Memory limit / usage shown with nbresuse

0
docs/howto/resource-estimation.rst → docs/howto/admin/resource-estimation.rst
View File

36
docs/howto/auth/firstuse.rst Normal file
View File

@@ -0,0 +1,36 @@
.. _howto/auth/firstuse:
==================================================
Let users choose a password when they first log in
==================================================
The **First Use Authenticator** lets users choose their own password.
Upon their first log-in attempt, whatever password they use will be stored
as their password for subsequent log in attempts. This is
the default authenticator that ships with TLJH.
Enabling the authenticator
==========================
.. note:: the FirstUseAuthenticator is enabled by default in TLJH.
#. Enable the authenticator and reload config to apply the configuration:
sudo -E tljh-config set auth.type firstuseauthenticator.FirstUseAuthenticator
sudo -E tljh-config reload
Users who are currently logged in will continue to be logged in. When they
log out and try to log back in, they will be asked to provide a username and
password.
Allowing anyone to log in to your JupyterHub
============================================
By default, you need to manually create user accounts before they will be able
to log in to your JupyterHub. If you wish to allow **any** user to access
the JupyterHub, run the following command.
.. code-block:: bash
tljh-config set auth.FirstUseAuthenticator.create_users true
tljh-config reload

93
docs/howto/auth/github.rst
View File

@@ -9,52 +9,81 @@ GitHub user ID / password. To do so, you'll first need to register an
application with GitHub, and then provide information about this
application to your ``tljh`` configuration.
Enabling the authenticator
==========================
.. note::
You'll need a GitHub account in order to complete these steps.
#. Create a GitHub application
#. Go to the `GitHub OAuth app creation page <https://github.com/settings/applications/new>`_.
#. **Application name**: Choose a descriptive application name (e.g. ``tljh``)
#. **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. ``http://<my-tljh-url>```.
#. **Application description**: Use any description that you like.
#. **Authorization callback URL**: Insert text with the following form::
Step 1: Create a GitHub application
===================================
http://<my-tljh-url>/hub/oauth_callback
#. Go to the `GitHub OAuth app creation page <https://github.com/settings/applications/new>`_.
#. When you're done filling in the page, it should look something like this:
* **Application name**: Choose a descriptive application name (e.g. ``tljh``)
* **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. ``http://<my-tljh-url>```.
* **Application description**: Use any description that you like.
* **Authorization callback URL**: Insert text with the following form::
http://<my-tljh-ip-address>/hub/oauth_callback
* When you're done filling in the page, it should look something like this:
.. image:: ../../images/auth/github/create_application.png
:alt: Create a GitHub OAuth application
#. Click "Register application".
#. You'll be taken to a page with the registered application details. Note
the **Client ID** and **Client Secret**, as you will use these later.
#. Click "Register application". You'll be taken to a page with the registered application details.
#. Copy the **Client ID** and **Client Secret** from the application details
page. You will use these later to configure your JupyterHub authenticator.
.. image:: ../../images/auth/github/client_id_secret.png
:alt: Your client ID and secret
.. image:: ../../images/auth/github/client_id_secret.png
:alt: Your client ID and secret
#. Configure your JupyterHub to use the GitHub Oathenticator
#. Log in as an administrator account to your JupyterHub.
#. Open a terminal on your JupyterHub.
#. Configure the GitHub OAuthenticator to use your client ID and secret with the following commands::
.. important::
sudo -E tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>'
sudo -E tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>'
If you are using a virtual machine from a cloud provider and
**stop the VM**, then when you re-start the VM, the provider will likely assign a **new public
IP address** to it. In this case, **you must update your GitHub application information**
with the new IP address.
#. Tell your JupyterHub to *use* the GitHub OAuthenticator for authentication::
Configure your JupyterHub to use the GitHub Oathenticator
=========================================================
sudo -E tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
We'll use the ``tljh-config`` tool to configure your JupyterHub's authentication.
For more information on ``tljh-config``, see :ref:`topic/tljh-config`.
#. Restart your JupyterHub so that new users see these changes::
#. Log in as an administrator account to your JupyterHub.
#. Open a terminal window.
sudo -E tljh-config reload
#. Confirm that the new authentactor works.
#. Open an **incognito window** in your browser.
#. Go to your JupyterHub URL.
#. You should see a GitHub login button like below:
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
.. image:: ../../images/auth/github/client_id_secret.png
:alt: The GitHub authenticator login button.
#. Configure the GitHub OAuthenticator to use your client ID and secret with the following commands::
sudo -E tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>'
::
sudo -E tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>'
#. Tell your JupyterHub to *use* the GitHub OAuthenticator for authentication::
sudo -E tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
#. Restart your JupyterHub so that new users see these changes::
sudo -E tljh-config reload
Confirm that the new authentactor works
=======================================
#. **Open an incognito window** in your browser (do not log out until you confirm
that the new authentication method works!)
#. Go to your JupyterHub URL.
#. You should see a GitHub login button like below:
.. image:: ../../images/auth/github/login_button.png
:alt: The GitHub authenticator login button.
#. After you log in with your GitHub credentials, you should be directed to the
Jupyter interface used in this JupyterHub.
#. **If this does not work** you can revert back to the default
JupyterHub authenticator by following the steps in :ref:`howto/auth/firstuse`.

95
docs/howto/content/add-data.rst Normal file
View File

@@ -0,0 +1,95 @@
.. _howto/content/add-data:
=============================
Adding data to the JupyterHub
=============================
This section covers how to add data to your JupyterHub either from the internet
or from your own machine. To learn how to **share data** that is already
on your JupyterHub, see :ref:`_howto/content/share-data`.
.. note::
When you add data using the methods on this page, you will **only add it
to your user directory**. This is not a place that is accessible to others.
For information on sharing this data with users on the JupyterHub, see
:ref:`_howto/content/share-data`.
Adding data from your local machine
===================================
The easiest way to add data to your JupyterHub is to use the "Upload" user
interface. To do so, follow these steps:
#. First, navigate to the Jupyter Notebook interface home page. You can do this
by going to the URL ``<my-hub-url>/user/<my-username>/tree``.
#. Click the "Upload" button to open the file chooser window.
.. image:: ../../images/content/upload-button.png
:alt: The upload button in Jupyter.
#. Choose the file you wish to upload. You may select multiple files if you
wish.
#. Click "Upload" for each file that you wish to upload.
.. image:: ../../images/content/file-upload-buttons.png
:alt: Multiple file upload buttons.
#. Wait for the progress bar to finish for each file. These files will now
be on your JupyterHub, your home user's home directory.
To learn how to **share** this data with new users on the JupyterHub,
see :ref:`_howto/content/share-data`.
Downloading data from the command line
======================================
If the data of interest is on the internet, you may also use code in order
to download it to your JupyterHub. There are several ways of doing this, so
we'll cover the simplest approach using the unix tool ``wget``.
#. Log in to your JupyterHub and open a terminal window.
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
#. Use ``wget`` to download the file to your current directory in the terminal.
.. code-block:: bash
wget <MY-FILE-URL>
Example: Downloading the `gapminder <https://www.gapminder.org/>`_ dataset.
---------------------------------------------------------------------------
In this example we'll download the `gapminder <https://www.gapminder.org/>`_
dataset, which contains information about country GDP and live expectancy over
time. You can download it from your browser `at this link <https://swcarpentry.github.io/python-novice-gapminder/files/python-novice-gapminder-data.zip>`_.
#. Log in to your JupyterHub and open a terminal window.
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New terminal button.
#. Use ``wget`` to download the gapminder dataset to your current directory in
the terminal.
.. code-block:: bash
wget https://swcarpentry.github.io/python-novice-gapminder/files/python-novice-gapminder-data.zip
#. This is a **zip** file, so we'll need to download a unix tool called "unzip"
in order to unzip it.
.. code-block:: bash
sudo -E apt-get install unzip
#. Finally, unzip the the file:
unzip python-novice-gapminder-data.zip
#. Confirm that your data was unzipped. It could be in a folder called ``data/``.
To learn how to **share** this data with new users on the JupyterHub,
see :ref:`_howto/content/share-data`.
.. TODO: Downloading data with the "download" module in Python? https://github.com/choldgraf/download

138
docs/howto/content/nbgitpuller.rst Normal file
View File

@@ -0,0 +1,138 @@
.. _howto/content/nbgitpuller:
================================================
Distributing materials to users with nbgitpuller
================================================
Goal
====
A very common need when using JupyterHub is to easily
distribute study materials / lab notebooks to students.
Students should be able to:
1. Easily get the latest version of materials, including any updates the instructor
has made to materials the student already has a copy of.
2. Be confident they won't lose any of their work. If an instructor has modified
something the student has also modified, the student's modification should
never be overwritten.
3. Not have to deal with manual merge conflicts or other complex operations.
Instructors should be able to:
1. Use modern collaborative version control tools to author & store their
materials. This currently means using Git.
**nbgitpuller** is a Jupyter Notebook extension that helps achieve these goals.
This tutorial will walk you through the process of creating a magic
nbgitpuller link that users of your JupyterHub can click to fetch the latest
version of materials from a git repo.
Pre-requisites
==============
1. A JupyterHub set up with The Littlest JupyterHub
2. A git repository containing materials to distribute
Step 1: Generate nbgitpuller link
=================================
**Generate the link with a Binder app**.
#. The easiest way to generate an nbgitpuller link is to use the
`mybinder.org based application <https://mybinder.org/v2/gh/jupyterhub/nbgitpuller/master?urlpath=apps/binder%2Flink_generator.ipynb>`_.
Open it, and wait for it to load.
.. image:: ../../images/nbgitpuller/binder-progress.png
:alt: Progress bar as the binder application loads
#. A blank form with some help text will open up.
.. image:: ../../images/nbgitpuller/blank-application.png
:alt: Blank application to make nbgitpuller links
#. Enter the IP address or URL to your JupyterHub under ``hub_url``.
Include ``http://`` or ``https://`` as appropriate.
.. image:: ../../images/nbgitpuller/hub-url-application.png
:alt: Application with hub_url filled out
#. Enter the URL to your Git repository. This could be from GitHub,
GitLab or any other git provider - including the disk of the
server The Littlest JupyterHub is installed on. As you start
typing the URL here, you'll notice that the link is already
being printed below!
.. image:: ../../images/nbgitpuller/git-url-application.png
:alt: Application with git_url filled out
#. If your git repository is using a non-default branch name,
you can specify that under ``branch``. Most people do not
need to customize this.
#. If you want to open a specific notebook when the user clicks
on the link, specify the path to the notebook under ``filepath``.
Make sure this file exists, otherwise users will get a 'File not found'
error.
.. image:: ../../images/nbgitpuller/filepath-application.png
:alt: Application with filepath filled out
If you do not specify a file path, the user will be shown the
directory listing for the repository.
#. By default, notebooks will be opened in the classic Jupyter Notebook
interface. You can select ``lab`` under ``application`` to open it in the
`JupyterLab <https://github.com/jupyterlab/jupyterlab>`_ instead.
The link printed at the bottom of the form can be distributed to students
now! You can also click it to test that it is working as intended,
and adjust the form values until you get something you are happy with.
**Hand-craft your nbgitpuller link**
If you'd prefer to hand-craft your ``nbgitpuller`` link (e.g. if the Binder
link above doesn't work), you can use the following pattern::
http://<my-jhub-address>/hub/user-redirect/git-pull?repo=<your-repo-url>&branch=<your-branch-name>&subPath=<subPath>&app=<notebook | lab>
- **repo** is the URL of the git repository you want to clone. This parameter is required.
- **branch** is the branch name to use when cloning from the repository.
This parameter is optional and defaults to ``master``.
- **subPath** is the path of the directory / notebook inside the repo to launch after cloning.
This parameter is optional, and defaults to opening the base directory of the linked Git repository.
- **app** This parameter is optional and defaults to either the environment variable
`NBGITPULLER_APP`'s value or `notebook` if it is undefined. The allowed values
are `lab` and `notebook`, the value will determine in what application view
you end up in.
- **urlPath** will, if specified, override `app` and `subPath` and redirect
blindly to the specified path.
Step 2: Users click on the nbgitpuller link
===========================================
#. Send the link to your users in some way - email, slack, post a
shortened version (with `bit.ly <https://bit.ly>`_ maybe) on the wall, or
put it on your syllabus page (like `UC Berkeley's data8 does <http://data8.org/sp18/>`_).
Whatever works for you :)
#. When users click the link, they will be asked to log in to the hub
if they have not already.
#. Users will see a progress bar as the git repository is fetched & any
automatic merging required is performed.
.. image:: ../../images/nbgitpuller/pull-progress.png
:alt: Progress bar with git repository being pulled
#. Users will now be redirected to the notebook specified in the URL!
This workflow lets users land directly in the notebook you specified
without having to understand much about git or the JupyterHub interface.
Advanced: hand-crafting an nbgitpuller link
===========================================
For information on hand-crafting an ``nbgitpuller`` link, see
`the nbgitpuller README <https://github.com/jupyterhub/nbgitpuller#constructing-the-nbgitpuller-url>`_.

80
docs/howto/content/share-data.rst Normal file
View File

@@ -0,0 +1,80 @@
.. _howto/content/share-data:
==========================
Share data with your users
==========================
There are a few options for sharing data with your users, this page covers
a few useful patterns.
Option 1: Distributing data with `nbgitpuller`
==============================================
For small datasets, the simplest way to share data with your users is via
``nbgitpuller`` links. In this case, users click on your link and the dataset
contained in the link's target repository is downloaded to the user's home
directory. Note that a copy of the dataset will be made for each user.
For information on creating and sharing ``nbgitpuller`` links, see
:ref:`tutorials/nbgitpuller`.
Option 2: Create a read-only shared folder for data
===================================================
If your data is large or you don't want copies of it to exist, you can create
a read-only shared folder that users have access to. To do this, follow these
steps:
#. **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 two folders (``/srv/data`` and
``/srv/data/my_shared_data_folder``).
.. code-block:: bash
sudo -E mkdir -p /srv/data/my_shared_data_folder
#. **Download the data** into this folder. See :ref:`howto/content/add-data` for
details on how to do this.
#. All users now have read access to the data in this folder.
Add a link to the shared folder in the user home directory
----------------------------------------------------------
Optionally, you may also **create a symbolic link to the shared data folder**
that you created above in each **new user's** home directory.
To do this, you can use the server's **user skeleton directory** (``/etc/skel``).
Anything that is placed in this directory will also
show up in a new user's home directory.
To create a link to the shared folder in the user skeleton directory,
follow these steps:
#. ``cd`` into the skeleton directory:
.. code-block:: bash
cd /etc/skel
#. **Create a symbolic link** to the data folder
.. code-block:: bash
sudo ln -s /src/data/my_shared_data_folder my_shared_data_folder
#. **Confirm that this worked** by logging in as a new user. You can do this
by opening a new "incognito" browser window and accessing your JupyterHub.
After you log in as a **new user**, the folder should appear in your new
user home directory.
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**.

12
docs/howto/notebook-interfaces.rst → docs/howto/envt/notebook-interfaces.rst
View File

@@ -1,8 +1,8 @@
.. _notebook_interfaces:
.. _howto/envt/notebook_interfaces:
===========================================
Change default Notebook Interface for users
===========================================
=======================================
Change default User Interface for users
=======================================
By default, logging into TLJH puts you in the classic Jupyter Notebook interface
we all know and love. However, there are at least two other popular notebook
@@ -14,8 +14,8 @@ interfaces you can use:
Both these interfaces are also shipped with tljh by default. You can try them
temporarily, or set them to be the default interface whenever you login.
Trying alternate interface tempoarily
=====================================
Trying an alternate interface temporarily
=========================================
When you log in & start your server, by default the URL in your browser
will be something like ``/user/<username>/tree``. The ``/tree`` is what tells

14
docs/howto/user-environment.rst → docs/howto/envt/user-environment.rst
View File

@@ -1,4 +1,4 @@
.. _user_environment:
.. _howto/envt/user_environment:
==================================
Install conda, pip or apt packages
@@ -9,7 +9,7 @@ environment. Packages / libraries installed in this environment are available
to all users on the JupyterHub. Users with :ref:`admin rights <howto/admin-users>` can install packages
easily.
.. _user_environment_pip:
.. _howto/envt/user_environment_pip:
Installing pip packages
=======================
@@ -20,7 +20,7 @@ almost 145,000 packages in it right now, so a lot of what you need is going to b
1. Log in as an admin user and open a Terminal in your Jupyter Notebook.
.. image:: ../images/notebook/new-terminal-button.png
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New Terminal button under New menu
If you already have a terminal open as an admin user, that should work too!
@@ -39,7 +39,7 @@ almost 145,000 packages in it right now, so a lot of what you need is going to b
If you get an error message like ``sudo: pip: command not found``,
make sure you are not missing the ``-E`` parameter after ``sudo``.
.. _user_environment_conda:
.. _howto/envt/user_environment_conda:
Installing conda packages
=========================
@@ -54,7 +54,7 @@ a community maintained repository of conda packages.
1. Log in as an admin user and open a Terminal in your Jupyter Notebook.
.. image:: ../images/notebook/new-terminal-button.png
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New Terminal button under New menu
If you already have a terminal open as an admin user, that should work too!
@@ -73,7 +73,7 @@ a community maintained repository of conda packages.
If you get an error message like ``sudo: conda: command not found``,
make sure you are not missing the ``-E`` parameter after ``sudo``.
.. _user_environment_apt:
.. _howto/envt/user_environment_apt:
Installing apt packages
=======================
@@ -90,7 +90,7 @@ make sure to look in the version of Ubuntu you are using!
1. Log in as an admin user and open a Terminal in your Jupyter Notebook.
.. image:: ../images/notebook/new-terminal-button.png
.. image:: ../../images/notebook/new-terminal-button.png
:alt: New Terminal button under New menu
If you already have a terminal open as an admin user, that should work too!

62
docs/howto/share-data.rst
View File

@@ -1,62 +0,0 @@
.. _howto/share-data:
==========================
Share data with your users
==========================
There are a few options for sharing data with your users, this page covers
a few useful patterns.
Distributing data with `nbgitpuller`
====================================
For small datasets, the simplest way to share data with your users is via
``nbgitpuller`` links. In this case, users click on your link and the dataset
contained in the link's target repository is downloaded to the user's home
directory. Note that a copy of the dataset will be made for each user.
For information on creating and sharing ``nbgitpuller`` links, see
:ref:`tutorials/nbgitpuller`.
Distributing data with a read-only shared folder
================================================
If your data is large or you don't want copies of it to exist, you can create
a read-only shared folder that users have access to. To do this, follow these
steps:
#. Log in to your JupyterHub as an **administrator user**.
#. Create a terminal session within your JupyterHub interface.
#. Create a folder where your data will live:
.. code-block:: bash
sudo mkdir /srv/data/mydatafolder
#. Download the data into this folder. For example, using ``sudo curl`` or by running
a ``python`` script that downloads the data.
#. All users now have read access to the data in this folder.
Optionally, you may also **create a symbolic link to the data folder** in each
**new user's** home directory. To do this, you can use the server's "user skeleton"
directory (``/etc/skel``). Anything that is placed in this directory will also
show up in a new user's home directory. To create a link to the dataset,
follow these steps:
#. Change into the skeleton directory:
.. code-block:: bash
cd /etc/skel
#. Create a symbolic link to the data folder
.. code-block:: bash
sudo ln -s /src/data/mydatafolder mydatafolder
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 effects on the home directories of existing
users.