sa-jupyterhub

Adding Users to JupyterHub

To allow users to work with JupyterHub, add them to the "jupyter" group by running:

sudo usermod -a -G jupyter userName

# Example:
sudo usermod -a -G jupyter vagrant
sudo usermod -a -G jupyter ubuntu

If a user is not allowed to access JupyterHub, they will not be able to start a session. The error message might not be clear, for example: 'Anaconda Error in Authenticator.pre_spawn_start: ValueError substring not found.'

Usage Examples

Basic Usage

- {
    role: "sa-jupyterhub"
}

Advanced Usage

- {
    role: "sa-jupyterhub",

    option_install_python2: True,
    option_install_python3: True,
    option_install_anaconda: True,

    option_install_git: True,

    jupyterhub_python: "anaconda",  # Options: python3 / anaconda
    option_install_nodejs_legacy: True,

    jupyterhub_properties:
      - {regexp: "^c.Authenticator.admin_users*", line: "c.Authenticator.admin_users = {'jupyter'}"}
      - {regexp: "^c.LocalAuthenticator.create_system_users*", line: "c.LocalAuthenticator.create_system_users = True"}
      - {regexp: "^c.JupyterHub.confirm_no_ssl*", line: "c.JupyterHub.confirm_no_ssl = True"}

    jupyterhub_ip: "{{ansible_default_ipv4.address}}",

    # ANACONDA SETTINGS
    anaconda_version: '5.1.0',
    anaconda_python: 3,  # Options: 2|3

    option_anaconda_addtoprofile: False,
    option_anaconda_update_packages: True,

    anaconda_base_dir: /usr/local,
    anaconda_additional_packages: [],
    
    # PYTHON 3 SETTINGS
    python_version: "3.6.4"
}

Credits

If you install Anaconda in favor of Python 3, a third-party module called conda is used for package management. You can find it here: Ansible Conda Module. Check the License for usage details.

Installing Custom Kernels

1. Log in as the "jupyter" user:

$ whoami
jupyter

2. List all available kernels:

jupyter kernelspec list

3. To create a new kernel using conda:

Make sure to prepare your shell for conda by running:

conda init <SHELL_NAME>

Then, check available Python versions:

/usr/local/anaconda/bin/conda search "^python$"

Pick a Python version and create a virtual environment:

/usr/local/anaconda/bin/conda create -n Anaconda3.6 python=3.6 anaconda

Next, activate the virtual environment:

conda activate Anaconda3.6

Ensure the environment is activated and install ipykernel:

(Anaconda3.6) jupyter@bionic:~$ pip install ipykernel

Register the kernel for use in Jupyter notebooks:

python -m ipykernel install --user --name Anaconda3.6 --display-name "Python 3.6 - anaconda venv"

You can check the installed kernels:

jupyter kernelspec list

Kernel registration is simply a JSON file located at /home/jupyter/.local/share/jupyter/kernels/anaconda3.6/kernel.json.

You can install kernels for a specific user, or for all users (in which case they will go to /usr/local/share/jupyter/kernels/ and you should set the correct permissions for the jupyter group).

Installing Ansible Kernel

To install the Ansible kernel, run:

pip install ansible-kernel
python -m ansible_kernel.install

# or

pip install ansible-kernel
python -m ansible_kernel.install --sys-prefix

Using with Ansible Galaxy

To use the sa-jupyterhub role, install it with:

ansible-galaxy install softasap.sa-jupyterhub

Then, include it in your playbook:

- {
    role: "softasap.sa-jupyterhub"
}

Copyright and License

This code is dual-licensed under the BSD 3-Clause License and the MIT License. Choose the one that fits you best.

Contact Us

Stay updated by subscribing for role updates on Facebook.

Join the discussion channel on Gitter.

Explore other roles at SoftAsap Roles Registry.

Check out our blog at SoftAsap Blog.