Installation of Jupyterhub on remote server

Min RK edited this page Oct 16, 2018 · 12 revisions

Installation of Jupyterhub on remote server

  1. Linux Anaconda Installation (Anaconda conveniently installs Python, the Jupyter Notebook, and other commonly used packages for scientific computing and data science. )

    • Go to : Continuum Analytics - Anaconda Downloads

    • Under Linux Anaconda Installation (copy link of 64 bit): On Terminal

      $ wget

      It will download Anaconda*.sh file

    • Installing by using following command:

      $ bash

      Enter(many times) >> yes >> give directory or keep it as Default

  2. Installing Python3 (dependency of jupyterhub is on python3)

    $ sudo apt-get -y install python3-pip

  3. Install nodejs/npm

    $ sudo apt-get -y install npm nodejs-legacy

  4. Install proxy with npm

    $ npm install -g configurable-http-proxy

  5. Install Jupyterhub

    $ pip3 install jupyterhub

  6. Install Jupyter notebook (/upgrade)

    $ pip3 install --upgrade notebook

  7. Test Jupyterhub default configuration

    $ jupyterhub --no-ssl

    This will start session in localhost:8000

    ** Make sure that port isn't protected under Firewall of your system

  8. It is recommended to use secure SSL certificate file for the public facing interface of the proxy. To produce personal security certificates commands are as follows:

    $ openssl req ­-x509 ­-nodes ­-days 365 ­-newkey rsa:1024 ­-keyout mykey.key ­-out mycert.pem

    **Fill in the credentials.(even if you dont..It's ok!)

  9. Create Jupyterhub configuration file

    $ jupyterhub --generate-config

  10. We will use Github OAuthentication as our Authenticator. so steps are as follows:

  11. Go to your Github profile > Settings > Oauth application

  • it is more convenient to not use capital letters in GitHub username
  1. Register new application

  2. Under callback URL is: https://your_host/hub/oauth_callback

Where **your­host** is where your server will be running. Such as .
  1. click on Register application.

You will see Client id and secret key generated above:

    Github client_id = '---­­­­­­­Some cryptic string----­­­­­'
    Github client_secret = '­­­­­­­---­­­­­­­Some cryptic string----­­'
  1. In Terminal, write command

    $ sudo nano

    • Run this after #15 below
  2. Install OAuthenticator:

    $ pip3 install oauthenticator

  3. Create userlist file

    $ sudo nano userlist

    It should be like username and admin after one space for giving admin right otherwise only username for normal user. Example:

    nipunsadvilkar admin
    manasRK admin

    ** Make sure that these usernames should match with your Github profile name.

  4. Create these users in your server machine:

    For ubuntu:

    $ sudo adduser nipunsadvilkar

    fill in credentials. & repeat same for other users.

  5. Create Default Directory for your Jupyter Notebooks:

    $ sudo mkdir /home/nipunsadvilkar/notebooks

    So now all users notebooks will be under ~/notebooks directory

    • Make sure to give full access to notebooks folder to your user (read/write/execute). You can check current access with:

    $ ls -la notebooks

  6. Now Edit as follows:

    $ sudo nano

    # Application configuration
    # This is an application.
    c.JupyterHub.authenticator_class = 'oauthenticator.GitHubOAuthenticator'
    c.GitHubOAuthenticator.oauth_callback_url = 'https://your_ip_addrees/hub/oauth_callback'
    c.GitHubOAuthenticator.client_id = '---­­­­­­­Some cryptic string----­­­­­'
    c.GitHubOAuthenticator.client_secret = '---­­­­­­­Some cryptic string----­­­­­'
    # This is an application.
    # create system users that don't exist yet
    c.LocalAuthenticator.create_system_users = True
    c.Authenticator.whitelist = {'nipunsadvilkar', 'manasRK', 'Benybrahim'}
    c.Authenticator.admin_users = {'nipunsadvilkar', 'manasRK'}
    c.Spawner.notebook_dir = '~/notebooks'
    c.JupyterHub.ssl_cert = 'mycert.pem'
    c.JupyterHub.ssl_key = 'mykey.key'
    c.JupyterHub.cookie_secret_file = '/home/ubuntu/jupyterhub_cookie_secret'
    c.JupyterHub.proxy_cmd = ['/usr/local/bin/configurable-http-proxy']

    Ctrl + X and press 'Y' for yes to save this file.

  7. Now starting jupyterhub with above configuration

    $ jupyterhub

    Go to https://your_ip_address:8000

    Your browser will raise "Untrusted certificates". click on "Proceed anyways"

    • It will show "Sign-in with Github"
    • After clicking on it, It will redirect the page to Github login page
    • Then if you are Admin then screen will have control panel

    Enjoy start server and enjoy Jupyter Notebook.

  8. If you want to install Python2 kernel in Jupyter Notebook. These are steps to follow :

    • Check already existing kernels

      $ sudo jupyter kernelspec list

    • Install ipykernel package

      1.$ sudo python -m pip install ipykernel

      if you dont have pip (of python2)

        1.`$ sudo apt-get -y install python-pip`
        if you get compilation error as :
            #include "Python.h"
        compilation terminated.
        error: command 'x86_64-linux-gnu-gcc' failed with exit status 1
        2.Then use following command:
        `$ sudo apt-get -y install python-zmq`
        Again do step 1) of 'ipykernel' and see whether it installs or not.
      1. Installing python2 kernel with ipykernel

        $ python2 -m ipykernel install

        instead of python you can add address of python2 directory also.

        1. Another hack would be

          1. Inside - /usr/local/share/jupyter/kernels/python2/kernel.json

          2. Edit - "argv" address : /home/ubuntu/anaconda2/bin/python2.7

                     "display_name": "Python 2",
                     "language": "python",
                     "argv": [

            ** Make sure that addreess is accessible to all otherwise it will raise permissionError: [Errno 13] Permission denied failed to start kernel

Run jupyterhub as a system service

  1. edit /lib/systemd/system/jupyterhub.service and /etc/systemd/system/jupyterhub.service as follows:

    ExecStart=/usr/local/bin/jupyterhub -f /home/ubuntu/
  2. sudo systemctl daemon-reload to load the config

  3. Now you can manage it using sudo systemctl <start|stop|status> jupyterhub

  4. To ensure it runs at startup systemctl enable jupyterhub.service


** Make sure all file link given in are proper.

Common issues with installation:

    Common error raising error to check for.
  1. 500 : Internal Server Error

    Common Reason:

    • Its mainly because you have given wrong Default directory address or directory which doesnt exist. [In above example directory is /notebooks]

    • Another reason would be user doesnt exist in on your machine (server). name of user should match with Github profile name otherwise there will be error like KeyError: 'access_token'

  2. 403 : Forbidden

    Same as above user might not exist on machine.

  3. permissionError: [Errno 13] Permission denied failed to start kernel

    Kernel address is not accessible to you (you dont have permissions)

    either change permission and read/write mode by using:

     `$ chmod -R 755 /your_python_directory_address`
     `$ chown user:user /your_python_directory_address`
  4. RuntimeError: Proxy failed to start with exit code 8

    Probably file address of mykey.key or mycert.pem is wrong or doesn't exist

References :

  4. Use link
    Most useful for quick responses.

I Hope this is Helpful! :+1: :smile: :v:

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.