diff --git a/docs/faq.rst b/docs/faq.rst new file mode 100644 index 0000000..18718f6 --- /dev/null +++ b/docs/faq.rst @@ -0,0 +1,12 @@ +================================ +Frequently Asked Questions (FAQ) +================================ + +What is the effect of using ``sudo -E``? +======================================== + +You may notice the use of ``sudo -E`` in several commands in this guide. Using +``-E`` with ``sudo`` allows you to carry over all the environment variables +into the ``sudo`` command. Most importantly, this lets use use the contents +of ``PATH`` with ``sudo``, which gives access to the right path for ``conda``, +``pip``, etc. diff --git a/docs/howto/admin-users.rst b/docs/howto/admin-users.rst deleted file mode 100644 index 4b72fb3..0000000 --- a/docs/howto/admin-users.rst +++ /dev/null @@ -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 ``` -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 - 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 - 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. diff --git a/docs/howto/admin/admin-users.rst b/docs/howto/admin/admin-users.rst new file mode 100644 index 0000000..7c897bf --- /dev/null +++ b/docs/howto/admin/admin-users.rst @@ -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 ``` + 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 ``/user//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 + 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 + 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. diff --git a/docs/howto/https.rst b/docs/howto/admin/https.rst similarity index 99% rename from docs/howto/https.rst rename to docs/howto/admin/https.rst index 5609a42..7a336b2 100644 --- a/docs/howto/https.rst +++ b/docs/howto/admin/https.rst @@ -1,4 +1,4 @@ -.. _howto/https: +.. _howto/admin/https: ============ Enable HTTPS diff --git a/docs/howto/nbresuse.rst b/docs/howto/admin/nbresuse.rst similarity index 89% rename from docs/howto/nbresuse.rst rename to docs/howto/admin/nbresuse.rst index 616146d..585c7d5 100644 --- a/docs/howto/nbresuse.rst +++ b/docs/howto/admin/nbresuse.rst @@ -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 diff --git a/docs/howto/resource-estimation.rst b/docs/howto/admin/resource-estimation.rst similarity index 100% rename from docs/howto/resource-estimation.rst rename to docs/howto/admin/resource-estimation.rst diff --git a/docs/howto/auth/firstuse.rst b/docs/howto/auth/firstuse.rst new file mode 100644 index 0000000..52b3766 --- /dev/null +++ b/docs/howto/auth/firstuse.rst @@ -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 diff --git a/docs/howto/auth/github.rst b/docs/howto/auth/github.rst index 7962657..ef01c4f 100644 --- a/docs/howto/auth/github.rst +++ b/docs/howto/auth/github.rst @@ -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 `_. - #. **Application name**: Choose a descriptive application name (e.g. ``tljh``) - #. **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. ``http://```. - #. **Application description**: Use any description that you like. - #. **Authorization callback URL**: Insert text with the following form:: +Step 1: Create a GitHub application +=================================== - http:///hub/oauth_callback +#. Go to the `GitHub OAuth app creation page `_. - #. 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://```. + * **Application description**: Use any description that you like. + * **Authorization callback URL**: Insert text with the following form:: + + http:///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 '' - sudo -E tljh-config set auth.GitHubOAuthenticator.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 '' + + :: + + sudo -E tljh-config set auth.GitHubOAuthenticator.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`. diff --git a/docs/howto/content/add-data.rst b/docs/howto/content/add-data.rst new file mode 100644 index 0000000..6614ecc --- /dev/null +++ b/docs/howto/content/add-data.rst @@ -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 ``/user//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 + +Example: Downloading the `gapminder `_ dataset. +--------------------------------------------------------------------------- + +In this example we'll download the `gapminder `_ +dataset, which contains information about country GDP and live expectancy over +time. You can download it from your browser `at this link `_. + +#. 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 diff --git a/docs/tutorials/nbgitpuller.rst b/docs/howto/content/nbgitpuller.rst similarity index 71% rename from docs/tutorials/nbgitpuller.rst rename to docs/howto/content/nbgitpuller.rst index def52b9..b35e699 100644 --- a/docs/tutorials/nbgitpuller.rst +++ b/docs/howto/content/nbgitpuller.rst @@ -1,4 +1,4 @@ -.. _tutorials/nbgitpuller: +.. _howto/content/nbgitpuller: ================================================ Distributing materials to users with nbgitpuller @@ -38,22 +38,24 @@ Pre-requisites 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 `_. Open it, and wait for it to load. - .. image:: ../images/nbgitpuller/binder-progress.png + .. 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 + .. image:: ../../images/nbgitpuller/blank-application.png :alt: Blank application to make nbgitpuller links -#. Enter the URL to your hub under ``hub_url``. Include ``http://`` or - ``https://`` as appropriate. +#. 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 + .. 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, @@ -62,7 +64,7 @@ Step 1: Generate nbgitpuller link typing the URL here, you'll notice that the link is already being printed below! - .. image:: ../images/nbgitpuller/git-url-application.png + .. 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, @@ -74,7 +76,7 @@ Step 1: Generate nbgitpuller link Make sure this file exists, otherwise users will get a 'File not found' error. - .. image:: ../images/nbgitpuller/filepath-application.png + .. 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 @@ -88,6 +90,25 @@ 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:///hub/user-redirect/git-pull?repo=&branch=&subPath=&app= + +- **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 =========================================== @@ -102,7 +123,7 @@ Step 2: Users click on the nbgitpuller link #. Users will see a progress bar as the git repository is fetched & any automatic merging required is performed. - .. image:: ../images/nbgitpuller/pull-progress.png + .. 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! diff --git a/docs/howto/content/share-data.rst b/docs/howto/content/share-data.rst new file mode 100644 index 0000000..6c0493c --- /dev/null +++ b/docs/howto/content/share-data.rst @@ -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**. diff --git a/docs/howto/notebook-interfaces.rst b/docs/howto/envt/notebook-interfaces.rst similarity index 87% rename from docs/howto/notebook-interfaces.rst rename to docs/howto/envt/notebook-interfaces.rst index f6e69ea..e4329e6 100644 --- a/docs/howto/notebook-interfaces.rst +++ b/docs/howto/envt/notebook-interfaces.rst @@ -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//tree``. The ``/tree`` is what tells diff --git a/docs/howto/user-environment.rst b/docs/howto/envt/user-environment.rst similarity index 94% rename from docs/howto/user-environment.rst rename to docs/howto/envt/user-environment.rst index a206c4e..f112526 100644 --- a/docs/howto/user-environment.rst +++ b/docs/howto/envt/user-environment.rst @@ -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 ` 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! diff --git a/docs/howto/share-data.rst b/docs/howto/share-data.rst deleted file mode 100644 index 8e68e88..0000000 --- a/docs/howto/share-data.rst +++ /dev/null @@ -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. diff --git a/docs/images/content/file-upload-buttons.png b/docs/images/content/file-upload-buttons.png new file mode 100644 index 0000000..7662e2a Binary files /dev/null and b/docs/images/content/file-upload-buttons.png differ diff --git a/docs/images/content/upload-button.png b/docs/images/content/upload-button.png new file mode 100644 index 0000000..313cb29 Binary files /dev/null and b/docs/images/content/upload-button.png differ diff --git a/docs/images/notebook/new-terminal-button.png b/docs/images/notebook/new-terminal-button.png index fee5d48..1abbfd9 100644 Binary files a/docs/images/notebook/new-terminal-button.png and b/docs/images/notebook/new-terminal-button.png differ diff --git a/docs/index.rst b/docs/index.rst index a03589e..f202f24 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,33 +33,31 @@ Ubuntu 18.04. We have a bunch of tutorials to get you started. install/custom-server Once you are ready to run your server for real, -it's a good idea to proceed directly to :doc:`howto/https`. - -Tutorials -========= - -Tutorials guide you step-by-step through accomplishing a specific task. - -.. toctree:: - :titlesonly: - - tutorials/nbgitpuller.rst +it's a good idea to proceed directly to :doc:`howto/admin/https`. How-To Guides ============= How-To guides answer the question 'How do I...?' for a lot of topics. +Content and Data +---------------- + .. toctree:: :titlesonly: - howto/https - howto/user-environment - howto/admin-users - howto/share-data - howto/notebook-interfaces - howto/resource-estimation - howto/nbresuse + howto/content/nbgitpuller + howto/content/add-data + howto/content/share-data + +The user environment +-------------------- + +.. toctree:: + :titlesonly: + + howto/envt/user-environment + howto/envt/notebook-interfaces Authentication -------------- @@ -73,6 +71,18 @@ with your JupyterHub. For more information on Authentication, see howto/auth/dummy howto/auth/github + howto/auth/firstuse + +Administration and security +--------------------------- + +.. toctree:: + :titlesonly: + + howto/admin/admin-users + howto/admin/resource-estimation + howto/admin/nbresuse + howto/admin/https Topic Guides ============ @@ -101,6 +111,7 @@ guides help you find what is broken & hopefully fix it. .. toctree:: :titlesonly: + faq troubleshooting/logs Often, your issues are not related to TLJH itself but to the cloud provider diff --git a/docs/install/add_packages.txt b/docs/install/add_packages.txt index b7f3510..a8eebc9 100644 --- a/docs/install/add_packages.txt +++ b/docs/install/add_packages.txt @@ -26,4 +26,4 @@ The packages ``gdal`` and ``there`` are now available to all users in JupyterHub If a user already had a python notebook running, they have to restart their notebook's kernel to make the new libraries available. -See :ref:`user_environment` for more information. +See :ref:`howto/envt/user_environment` for more information. diff --git a/docs/install/custom-server.rst b/docs/install/custom-server.rst index c340827..d476b72 100644 --- a/docs/install/custom-server.rst +++ b/docs/install/custom-server.rst @@ -33,16 +33,15 @@ Step 1: Installing The Littlest JupyterHub #. Copy the text below, and paste it into the terminal. Replace ```` with the name of the first **admin user** for this - JupyterHub. This admin user can log in after the JupyterHub is set up, and + JupyterHub. Choose any name you like (don't forget to replace the brackets!). + This admin user can log in after the JupyterHub is set up, and can configure it to their needs. **Remember to add your username**! .. code-block:: bash - curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py \ - | sudo python3 - \ - --admin + curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py | sudo python3 - --admin - .. note: + .. note:: See :ref:`topic/installer-actions` if you want to understand exactly what the installer is doing. :ref:`topic/customizing-installer` documents other options that can be passed to the installer. @@ -56,7 +55,8 @@ Step 1: Installing The Littlest JupyterHub .. image:: ../images/first-login.png :alt: JupyterHub log-in page -#. Login using the **admin user name** you used in step 2, and a password. Use a +#. Login using the **admin user name** you used in step 2. You can choose any + password that you wish. Use a strong password & note it down somewhere, since this will be the password for the admin user account from now on. diff --git a/docs/topic/security.rst b/docs/topic/security.rst index b4d8d8f..6399c3c 100644 --- a/docs/topic/security.rst +++ b/docs/topic/security.rst @@ -70,4 +70,4 @@ HTTPS ===== Any internet-facing JupyterHub should use HTTPS to secure its traffic. For -information on how to use HTTPS with your JupyterHub, see :ref:`howto/https`. +information on how to use HTTPS with your JupyterHub, see :ref:`_howto/admin/https`.