mirror of
https://github.com/jupyterhub/the-littlest-jupyterhub.git
synced 2025-12-18 21:54:05 +08:00
adopt myst
run rst2myst, with minimal manual formatting fixes
This commit is contained in:
Min RK
100
docs/howto/content/add-data.md
Normal file
100
docs/howto/content/add-data.md
Normal file
@@ -0,0 +1,100 @@
|
||||
(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:
|
||||
|
||||
1. 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`.
|
||||
|
||||
2. Click the "Upload" button to open the file chooser window.
|
||||
|
||||
```{image} ../../images/content/upload-button.png
|
||||
:alt: The upload button in Jupyter.
|
||||
```
|
||||
|
||||
3. Choose the file you wish to upload. You may select multiple files if you
|
||||
wish.
|
||||
|
||||
4. Click "Upload" for each file that you wish to upload.
|
||||
|
||||
```{image} ../../images/content/file-upload-buttons.png
|
||||
:alt: Multiple file upload buttons.
|
||||
```
|
||||
|
||||
5. 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`.
|
||||
|
||||
1. Log in to your JupyterHub and open a terminal window.
|
||||
|
||||
```{image} ../../images/notebook/new-terminal-button.png
|
||||
:alt: New terminal button.
|
||||
```
|
||||
|
||||
2. Use `wget` to download the file to your current directory in the terminal.
|
||||
|
||||
```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).
|
||||
|
||||
1. Log in to your JupyterHub and open a terminal window.
|
||||
|
||||
```{image} ../../images/notebook/new-terminal-button.png
|
||||
:alt: New terminal button.
|
||||
```
|
||||
|
||||
2. Use `wget` to download the gapminder dataset to your current directory in
|
||||
the terminal.
|
||||
|
||||
```bash
|
||||
wget https://swcarpentry.github.io/python-novice-gapminder/files/python-novice-gapminder-data.zip
|
||||
```
|
||||
|
||||
3. This is a **zip** file, so we'll need to download a unix tool called "unzip"
|
||||
in order to unzip it.
|
||||
|
||||
```bash
|
||||
sudo apt install unzip
|
||||
```
|
||||
|
||||
4. Finally, unzip the file:
|
||||
|
||||
```bash
|
||||
unzip python-novice-gapminder-data.zip
|
||||
```
|
||||
|
||||
5. 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
|
||||
@@ -1,97 +0,0 @@
|
||||
.. _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 apt install unzip
|
||||
|
||||
#. Finally, unzip the file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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
|
||||
@@ -1,11 +1,8 @@
|
||||
.. _howto/content/nbgitpuller:
|
||||
(howto-content-nbgitpuller)=
|
||||
|
||||
================================================
|
||||
Distributing materials to users with nbgitpuller
|
||||
================================================
|
||||
# Distributing materials to users with nbgitpuller
|
||||
|
||||
Goal
|
||||
====
|
||||
## Goal
|
||||
|
||||
A very common need when using JupyterHub is to easily
|
||||
distribute study materials / lab notebooks to students.
|
||||
@@ -29,38 +26,34 @@ 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
|
||||
==============
|
||||
## Pre-requisites
|
||||
|
||||
1. A JupyterHub set up with The Littlest JupyterHub
|
||||
2. A git repository containing materials to distribute
|
||||
|
||||
Step 1: Generate nbgitpuller link
|
||||
=================================
|
||||
## Step 1: Generate nbgitpuller link
|
||||
|
||||
The quickest way to generate a link is to use `nbgitpuller.link
|
||||
<https://jupyterhub.github.io/nbgitpuller/link.html>`_, but other options exist as described in the
|
||||
`nbgitpuller project's documentation
|
||||
<https://jupyterhub.github.io/nbgitpuller/use.html>`_.
|
||||
The quickest way to generate a link is to use [nbgitpuller.link](https://jupyterhub.github.io/nbgitpuller/link.html), but other options exist as described in the
|
||||
[nbgitpuller project's documentation](https://jupyterhub.github.io/nbgitpuller/use.html).
|
||||
|
||||
Step 2: Users click on the nbgitpuller link
|
||||
===========================================
|
||||
## 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/>`_).
|
||||
1. 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
|
||||
2. 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
|
||||
3. 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
|
||||
```{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!
|
||||
4. 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.
|
||||
137
docs/howto/content/share-data.md
Normal file
137
docs/howto/content/share-data.md
Normal file
@@ -0,0 +1,137 @@
|
||||
(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}`howto/content/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:
|
||||
|
||||
1. **Log** in to your JupyterHub as an **administrator user**.
|
||||
|
||||
2. **Create a terminal session** with your JupyterHub interface.
|
||||
|
||||
```{image} ../../images/notebook/new-terminal-button.png
|
||||
:alt: New terminal button.
|
||||
```
|
||||
|
||||
3. **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`).
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /srv/data/my_shared_data_folder
|
||||
```
|
||||
|
||||
4. **Download the data** into this folder. See {ref}`howto/content/add-data` for
|
||||
details on how to do this.
|
||||
|
||||
5. 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:
|
||||
|
||||
1. `cd` into the skeleton directory:
|
||||
|
||||
```bash
|
||||
cd /etc/skel
|
||||
```
|
||||
|
||||
2. **Create a symbolic link** to the data folder
|
||||
|
||||
```bash
|
||||
sudo ln -s /srv/data/my_shared_data_folder my_shared_data_folder
|
||||
```
|
||||
|
||||
3. **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**.
|
||||
|
||||
## 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.
|
||||
|
||||
1. **Log** in to your JupyterHub as an **administrator user**.
|
||||
|
||||
2. **Create a terminal session** with your JupyterHub interface.
|
||||
|
||||
```{image} ../../images/notebook/new-terminal-button.png
|
||||
:alt: New terminal button.
|
||||
```
|
||||
|
||||
3. **Create a folder** where your data will live. We recommend placing shared
|
||||
data in `/srv`. The following command creates a directory `/srv/scratch`
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /srv/scratch
|
||||
```
|
||||
|
||||
4. **Change group ownership** of the new folder
|
||||
|
||||
```bash
|
||||
sudo chown root:jupyterhub-users /srv/scratch
|
||||
```
|
||||
|
||||
5. **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--`)
|
||||
|
||||
```bash
|
||||
sudo chmod 777 /srv/scratch
|
||||
sudo chmod g+s /srv/scratch
|
||||
```
|
||||
|
||||
6. **Create a symbolic link** to the scratch folder in users home directories
|
||||
|
||||
```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.
|
||||
:::
|
||||
@@ -1,139 +0,0 @@
|
||||
.. _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:`howto/content/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 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 /srv/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**.
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user