Ansible role that installs a public-facing Jupyter instance with JupyterHub and JupyterLab on Ubuntu
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
taha@asks2 5aac155f2c Extended and improved README. Other changes: 2 months ago
defaults Extended and improved README. Other changes: 2 months ago
handlers Role migrated fromr luxor playbook. Not confirmed working yet. 2 months ago
meta Extended and improved README. Other changes: 2 months ago
tasks Extended and improved README. Other changes: 2 months ago
templates Role migrated fromr luxor playbook. Not confirmed working yet. 2 months ago
.gitignore Role migrated fromr luxor playbook. Not confirmed working yet. 2 months ago
LICENSE Initial commit 2 months ago
README.md Extended and improved README. Other changes: 2 months ago

README.md

Jupyter with JupyterLab and JupyterHub

This Ansible role creates a secure Jupyter installation (tested on Ubuntu 18.04) using JupyterHub (to handle authentication) and JupyterLab (for the nice web UI).

This is the actual code I use to maintain my own Jupyter server. The code should be workable as-is for others, as long as you reset the role variables and create your own cookie secret.

If you face problems, contact me directly or open an issue, and I'd be happy to help you!

Role variables

Available variables are listed below, along with default values (see defaults/main.yml):

jupyter_domain: "jupyter.example.com"
jupyter_email: "webmaster@example.com"

The domain of your Jupyter instance. You must have configured DNS at your registrar so this domain points to the server where you are installing Jupyter. The email address is used to fetch a Let's Encrypt certificate for the domain.

jupyter_default_url: "/lab"
jupyter_notebook_dir: "/media/jupyter"
jupyter_allowed_users:
  - "{{ ansible_env.USER }}"

Unless you have specific reasons, I suggest you leave jupyter_default_url as it is. You must change jupyter_notebook_dir to a valid path on your machine. This is where JupyterLab will store all the notebooks and other work files your users create in Jupyter. Unless you specify which users are allowed to login to Jupyter, every Linux user account on your server will be allowed. Specify usernames as an Ansible list, at least one.

jupyter_kernel_julia: false
jupyter_kernel_R: false

Apart from the default Python kernel that comes with Jupyter, this role can install the Julia and R kernels. They are not installed by default. In the case that you enable either on of these kernels, your playbook must include those roles.

Dependencies (other Ansible roles)

NOTE! The R role has role dependencies of its own. If you want the R kernel, the R role presently depends on TeXLive, which is a rather large download and installation. I suggest you keep the R kernel disabled, unless you are willing to either install TeXLive or edit the R role manually to remove that dependency.

Example playbook

This section is written with an Ansible beginner in mind.

This is a very rudimentary example. The web contains plenty of guides on how to write Ansible playbooks.

In short, you will need to install Ansible, then create a directory to hold your playbook and create the following files in it: hosts.yml, ansible.cfg, and playbook.yml. Here are some working examples to get you started (replace all chevron-enclosed strings, <>, with your own):

### hosts.yml
all:
  vars: 
    ansible_python_interpreter: /usr/bin/python3
<hosts-groupname>:
  hosts:
    <hostname>:
      ansible_host: <hostname>

ansible_host is where you tell Ansible how to reach your host. It can be an IP address, but I suggest you learn to use SSH and ~/.ssh/config. Then you can just use the same Host-name in your Ansible hosts file, and Ansible will obediently follow your ssh configuration.

It's also possible to install Jupyter etc. on the same machine where you have installed Ansible (you will want to search for "running Ansible playbook on localhost").

### ansible.cfg
### https://github.com/ansible/ansible/blob/devel/examples/ansible.cfg
[defaults]
inventory = ./hosts.yml
[privilege_escalation]
become_method = sudo
### playbook.yml
- hosts: <hosts-groupname>
  become: yes
  roles:
    - { role: jupyter }

Make sure you download this Jupyter role and all its dependency roles into the folder roles/ inside your playbook directory. I suggest you simply git clone each role from inside your roles/ directory. You should end up with a tree looking something like this:

.
├── ansible.cfg
├── hosts.yml
├── playbook.yml
└── roles
    ├── jupyter
    └── nodejs

Finally, before running the playbook, please generate a cookie secret for Jupyter by entering the ./roles/jupyter/ directory and saving a random string to the files subdirectory, like this:

cd ./roles/jupyter
sudo openssl rand -hex 32 > files/jupyterhub_cookie_secret

Now run your playbook (make sure you are in your playbook's top directory):

ansible-playbook playbook.yml --ask-become-pass

Since this role installs system packages, you will need to pass your sudo password for the machine Ansible is targeting to the playbook. This is what --ask-become-pass does--it makes Ansible ask for your password. If you don't provide a password (or the wrong password), the playbook will fail at the first task that requires elevated rights (but not before).