Installation Guide


  • Start a server running latest Ubuntu version.

  • Enable password-less SSH access for ubuntu user.

  • Partition and format any local disks you want to mount.

  • Verify a valid DNS entry for the server.

  • Choose an SSL certificate source. Use either of these options:

    • Let’s Encrypt
    • obtain a trusted SSL certificate and key for the server at that FQDN.
  • Checkout the latest version of the repository including the ansible-conda submodule:

    $ git clone --recursive

Create the hosts group

  1. Edit the ./hosts file to lists the FQDN’s of the hosts in the jupyterhub_hosts group.
  2. Create for each host a file in ./host_vars directory with the name of the host, starting from ./host_vars/hostname.example.

Secure your deployment

  1. Create a cookie secret file, ./security/cookie_secret, using:

    $ openssl rand -hex 1024 > ./security/cookie_secret

    For additional information, see the cookie secret file section in the JupyterHub documentation.

  2. If you are using Let’s Encrypt, skip this step. Otherwise, install your SSL private key ./security/ssl.key and certificate as ./security/ssl.crt.

Deploy with Ansible

  1. Run ansible-playbook for the main deployment:

    $ ansible-playbook deploy.yml

Verify your deployment

  1. SSH into the server:

    $ ssh root@{hostname}

substituting your hostname for {hostname}. For example, ssh

  1. Reload supervisor:

    $ supervisorctl reload