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

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**.