diff --git a/docs/contributing/dev-setup.rst b/docs/contributing/dev-setup.rst index 42c64c0..9ac08ec 100644 --- a/docs/contributing/dev-setup.rst +++ b/docs/contributing/dev-setup.rst @@ -1,5 +1,6 @@ .. _contributing_dev_setup: +================================== Setting up Development Environment ================================== diff --git a/docs/guides/admin.rst b/docs/guides/admin.rst index 3aa82f7..f3078aa 100644 --- a/docs/guides/admin.rst +++ b/docs/guides/admin.rst @@ -1,7 +1,8 @@ .. _admin_access: +===================== Administrative Access ---------------------- +===================== In The Littlest JupyterHub, we try to allow users to do as many administrative tasks as possible within JupyterHub itself. Admin users can: diff --git a/docs/guides/install.rst b/docs/guides/install.rst index 11e3555..baa2a19 100644 --- a/docs/guides/install.rst +++ b/docs/guides/install.rst @@ -1,10 +1,11 @@ .. _installation: +============ Installation ============ Quick Installation ------------------- +================== The quick way to install The Littlest JupyterHub (tljh) is: @@ -19,7 +20,7 @@ You should probably add yourself as an `admin user `_ after installation. Slightly less quick installation --------------------------------- +================================ If you can read ``python3`` and are nervous about the previous installation method, you can inspect the installer script before running it. diff --git a/docs/guides/notebook-interfaces.rst b/docs/guides/notebook-interfaces.rst index d9c7f04..273401b 100644 --- a/docs/guides/notebook-interfaces.rst +++ b/docs/guides/notebook-interfaces.rst @@ -1,5 +1,6 @@ .. _notebook_interfaces: +================================================== Notebook Interfaces (Classic, JupyterLab, nteract) ================================================== @@ -14,7 +15,7 @@ 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 -------------------------------------- +===================================== 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 @@ -26,7 +27,7 @@ the notebook server to give you the classic notebook interface. You can play around with them and see what fits your use cases best. Changing the default user interface ------------------------------------ +=================================== You can change the default interface users get when they log in by modifying ``config.yaml`` as an admin user. diff --git a/docs/guides/requirements.rst b/docs/guides/requirements.rst index 6baf9e7..fae4011 100644 --- a/docs/guides/requirements.rst +++ b/docs/guides/requirements.rst @@ -1,23 +1,24 @@ .. _requirements: +=================== Server Requirements =================== Operating System ----------------- +================ We recommend using Ubuntu 18.04 as the base operating system for your server. Ubuntu 16.04 should also work, but is not officially supported. other Linux distributions and operating systems are also not officially supported. Root access ------------ +=========== Full ``root`` access to this server is required. This might be via ``sudo`` (recommended) or by direct access to ``root`` (not recommended!) External IP ------------ +=========== An external IP allows users on the internet to reach your JupyterHub. Most VPS / Cloud providers give you a public IP address along with your server. If @@ -25,7 +26,7 @@ you are hosting on a physical machine somewhere, talk to your system administrat about how to get HTTP traffic from the world into your server. Memory (RAM) ------------- +============ RAM is often the biggest limiting factor to the question 'how many users can use this JupyterHub at the same time?'. If you want to support ``N`` maximum concurrent active users diff --git a/docs/guides/user-environment.rst b/docs/guides/user-environment.rst index 832d0f0..c78c23e 100644 --- a/docs/guides/user-environment.rst +++ b/docs/guides/user-environment.rst @@ -1,5 +1,6 @@ .. _user_environment: +============================ Customizing user environment ============================ @@ -11,7 +12,7 @@ easily. .. _user_environment_pip: Installing pip packages ------------------------ +======================= `pip `_ is the recomended tool for installing packages in Python from the `Python Packaging Index (PyPI) `_. PyPI has @@ -41,7 +42,7 @@ almost 145,000 packages in it right now, so a lot of what you need is going to b .. _user_environment_conda: Installing conda packages -------------------------- +========================= Conda lets you install new languages (such as new versions of python, node, R, etc) as well as packages in those languages. For lots of scientific software, installing @@ -75,7 +76,7 @@ a community maintained repository of conda packages. .. _user_environment_apt: Installing apt packages ------------------------ +======================= `apt `_ is the official package manager for the `Ubuntu Linux distribution `_. You can install @@ -112,7 +113,7 @@ make sure to look in the version of Ubuntu you are using! User environment location -------------------------- +========================= The user environment is a conda enviornment set up in ``/opt/tljh/user``, with a Python3 kernel as the default. It is readable by all users, but writeable only @@ -120,7 +121,7 @@ by users who have root access. This makes it possible for JupyterHub admins (who root access with ``sudo``) to install software in the user environment easily. Accessing user environment outside JupyterHub ---------------------------------------------- +============================================= We add ``/opt/tljh/user/bin`` to the ``$PATH`` environment variable for all JupyterHub users, so everything installed in the user environment is available to them automatically. diff --git a/docs/index.rst b/docs/index.rst index ca494d9..be34778 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,6 @@ +======================= The Littlest JupyterHub ------------------------ +======================= A simple `JupyterHub `_ distribution for a small (0-50) number of users on a single server. diff --git a/docs/troubleshooting/logs.rst b/docs/troubleshooting/logs.rst index 1ffebd6..f62f6c2 100644 --- a/docs/troubleshooting/logs.rst +++ b/docs/troubleshooting/logs.rst @@ -1,5 +1,6 @@ .. _troubleshoot_logs: +=============== Looking at Logs =============== @@ -19,7 +20,7 @@ user's notebook server. All the logs are accessible via `journalctl `_. Pre-requisites --------------- +============== #. A DigitalOcean account with a payment method attached. #. Some familiarity with the command line. Step 1: Installing The Littlest JupyterHub ------------------------------------------- +========================================== Let's create the server on which we can run JupyterHub. @@ -101,11 +102,11 @@ Let's create the server on which we can run JupyterHub. #. Congratulations, you have a running working JupyterHub! Step 2: Adding more users --------------------------- +========================== .. include:: add_users.txt Step 3: Install conda / pip packages for all users --------------------------------------------------- +================================================== .. include:: add_packages.txt diff --git a/docs/tutorials/google.rst b/docs/tutorials/google.rst index 931555b..7eb365f 100644 --- a/docs/tutorials/google.rst +++ b/docs/tutorials/google.rst @@ -1,22 +1,23 @@ .. _tutorial_quickstart_google: +==================================== Tutorial: JupyterHub on Google Cloud ==================================== Goal ----- +==== By the end of this tutorial, you should have a JupyterHub with some admin users and a user environment with packages you want installed running on `Google Cloud `_. Prerequisites -------------- +============= #. A Google Cloud account. You might use the free credits for trying it out! Step 1: Installing The Littlest JupyterHub ------------------------------------------- +========================================== Let's create the server on which we can run JupyterHub. @@ -84,7 +85,7 @@ Let's create the server on which we can run JupyterHub. For more guidance on the different options available to you, as well as pricing considerations on Google Cloud, see the `GCP Choosing a VM Guide `_. - + #. Under **Boot Disk**, click the **Change** button. This lets us change the operating system and the size of your disk. @@ -186,11 +187,11 @@ Let's create the server on which we can run JupyterHub. #. Congratulations, you have a running working JupyterHub! Step 2: Adding more users --------------------------- +========================== .. include:: add_users.txt Step 3: Install conda / pip packages for all users --------------------------------------------------- +================================================== .. include:: add_packages.txt diff --git a/docs/tutorials/jetstream.rst b/docs/tutorials/jetstream.rst index 6034cda..67a2b8d 100644 --- a/docs/tutorials/jetstream.rst +++ b/docs/tutorials/jetstream.rst @@ -1,24 +1,25 @@ .. _tutorial_quickstart_jetstream: +================================= Tutorial: JupyterHub on Jetstream ================================= Goal ----- +==== By the end of this tutorial, you should have a JupyterHub with some admin users and a user environment with packages you want installed running on `Jetstream `_. Prerequisites -------------- +============= #. A Jetstream account with an XSEDE allocation; for more information, go to the `Jetstream Allocations help page `_. #. Some familiarity with the command line. Step 1: Installing The Littlest JupyterHub ------------------------------------------- +========================================== Let's create the server on which we can run JupyterHub. @@ -125,11 +126,11 @@ Let's create the server on which we can run JupyterHub. #. Congratulations, you have a running working JupyterHub! Step 2: Adding more users --------------------------- +========================== .. include:: add_users.txt Step 3: Install conda / pip packages for all users --------------------------------------------------- +================================================== .. include:: add_packages.txt