From 1cfc37a23b1b473ed13b94deaf500f53f50bf0ce Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Thu, 28 Jun 2018 02:34:51 -0700 Subject: [PATCH] Add a quickstart tutorial & re-organize index page We split docs into tutorials & more in-depth guides. --- docs/{ => guides}/admin.rst | 0 docs/{ => guides}/install.rst | 0 docs/{ => guides}/requirements.rst | 0 docs/index.rst | 26 +++++-- docs/install.md | 35 --------- docs/tutorials/quickstart.rst | 112 +++++++++++++++++++++++++++++ 6 files changed, 133 insertions(+), 40 deletions(-) rename docs/{ => guides}/admin.rst (100%) rename docs/{ => guides}/install.rst (100%) rename docs/{ => guides}/requirements.rst (100%) delete mode 100644 docs/install.md create mode 100644 docs/tutorials/quickstart.rst diff --git a/docs/admin.rst b/docs/guides/admin.rst similarity index 100% rename from docs/admin.rst rename to docs/guides/admin.rst diff --git a/docs/install.rst b/docs/guides/install.rst similarity index 100% rename from docs/install.rst rename to docs/guides/install.rst diff --git a/docs/requirements.rst b/docs/guides/requirements.rst similarity index 100% rename from docs/requirements.rst rename to docs/guides/requirements.rst diff --git a/docs/index.rst b/docs/index.rst index 6949388..3cd4af0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,9 +19,25 @@ at the public IP of your server! If this installation method (``curl | sudo bash -``) makes you nervous, check out the :ref:`other installation methods ` we support! -.. toctree:: - :maxdepth: 1 +Tutorials +========= - requirements - install - admin +Tutorials guide you through accomplishing specific goals. Great place to get +started! + +.. toctree:: + :titlesonly: + + tutorials/quickstart + +Guides +====== + +Guides provide in-depth explanations of specific topics. + +.. toctree:: + :titlesonly: + + guides/requirements + guides/install + guides/admin diff --git a/docs/install.md b/docs/install.md deleted file mode 100644 index ed2c68c..0000000 --- a/docs/install.md +++ /dev/null @@ -1,35 +0,0 @@ -# Installation - -## Quick Installation -The quick way to install The Littlest JupyterHub (tljh) is: - -```bash -curl https://raw.githubusercontent.com/yuvipanda/the-littlest-jupyterhub/master/installer/install.bash | sudo bash - -``` - -This takes 2-5 minutes to run. When completed, you can access your new JupyterHub -at the public IP of your server! - -You should probably add yourself as an [admin user](admin.md) -after installation. - -## Slightly less quick installation - -If you can read `bash` and are nervous about the previous installation method, -you can inspect the installer script before running it. - -1. Download the installer script - - ```bash - curl https://raw.githubusercontent.com/yuvipanda/the-littlest-jupyterhub/master/installer/install.bash -o install.bash - ``` - -2. Read the install script source using your favorite text editor - -3. Run the installer script - - ```bash - sudo install.bash - ``` - - This should have the exact same effects as the quick installer method. diff --git a/docs/tutorials/quickstart.rst b/docs/tutorials/quickstart.rst new file mode 100644 index 0000000..3f1703f --- /dev/null +++ b/docs/tutorials/quickstart.rst @@ -0,0 +1,112 @@ +.. _tutorial_quickstart: + +Tutorial: JupyterHub in under 10 minutes +======================================== + +Goal +---- + +By the end of this tutorial, you should have a JupyterHub with some admin +users and user environment with packages you want installed. This is 80% of what +most users need, so is a great place to start + +Pre-requisites +-------------- + +#. A fresh Ubuntu 18.04 server +#. Full root access +#. Some familiarity with the command line +#. Public IP for your server, so you can access your hub from the internet + +Step 1: Install the Littlest JupyterHub (TLJH) +---------------------------------------------- + +``ssh`` into the server, and install TLJH. + +.. code-block:: bash + + curl https://raw.githubusercontent.com/yuvipanda/the-littlest-jupyterhub/master/installer/install.bash | sudo bash - + +This takes about 1-3 minutes to finish. When completed, you can visit the +public IP of your server to use your JupyterHub! You can log in with any username +and password combination. + +Step 2: Add admin user +---------------------- + +You should add yourself as an admin user, so you can administer the JupyterHub +from inside JupyterHub itself. Making someone admin gives them ``root`` access to +the server, allowing them to make whatever changes they want. + +TLJH is configured with a ``config.yaml`` files, written in `YAML `_ syntax. +We will modify ``config.yaml`` to list admin users, and then restart JupyterHub to +let the changes take effect. + +1. Open the ``config.yaml`` file for editing. + + .. code-block:: bash + + sudo nano /opt/tljh/config.yaml + +2. Add usernames that should have admin access. + + .. code-block:: yaml + + users: + admin: + - user1 + - user2 + + Be careful around the syntax - indentation matters, and you should be using + spaces and not tabs. + + When you are done, save the file and exit. In ``nano``, you can do this with + ``Ctrl+X`` key. + +3. Restart jupyterhub so the changes can take effect. + + .. code-block:: bash + + sudo systemctl restart jupyterhub + + This should not disrupt any active users on your JupyterHub. + + If the user you made admin is already logged in, you might have to restart your + notebook server via the Control Panel page accessed from top right of your web + interface for your new superpowers to take effect. + +4. Open a terminal in your notebook server (New -> Terminal) & check if sudo works. + + .. code-block:: console + + $ sudo -E id + uid=0(root) gid=0(root) groups=0(root) + +Congratulations, you are now an admin user in JupyterHub! Most administrative +actions can now be performed from inside the Terminal in Jupyter Notebooks, +without requiring SSH usage. + +Step 3: Install conda / pip packages for all users +-------------------------------------------------- + +The **User Environment** is a conda environment that is shared by all users +in the JupyterHub. Libraries installed in this environment are immediately +available to all users. Admin users can install packages in this environment +with ``sudo -E``. + +1. As an admin user, open a terminal in your notebook server +2. Install ``numpy`` from `conda-forge `_. + + .. code-block:: bash + + sudo -E conda install -c conda-forge numpy + + The ``sudo -E`` is very important! + +3. Install ``there`` with ``pip`` + + .. code-block:: bash + + sudo -E pip install there + +The packages ``numpy`` and ``there`` are now available to all users in JupyterHub!