How to install JupyterHub with Docker on a local machine and in a sub domain

Question

I will run JupyterHub in a sub domain. Here is the Dockerfile, jupyterhub_config.py, .gitlab-ci.yml. My first question is how to configure the jupyter_config.py. How can I load the jupyterhub_config.py on the build in the container?

How do I start Jupyterhub in the .gitlab-ci.yml for tests and how do I copy the application in the sub domain? I wrote a README.md. I need a little help for the JupyterHub. If all works fine, I will write a complete HOWTO Install JupyterHub on a local machine and in a sub domain by a provider.

FROM continuumio/miniconda3

# Updating packages
RUN apt-get update -y \
    && apt-get install -y --no-install-recommends \
       git \
       nano \
       unzip \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Install conda and Jupyter
RUN conda update -y conda
RUN conda install -c conda-forge jupyter_nbextensions_configurator \
    jupyterhub \
    jupyterlab \
    matplotlib \
    pandas \
    scipy

# Setup application
EXPOSE 8000

CMD ["jupyterhub", "--ip='*'", "--port=8000", "--no-browser", "--allow-root"]

The .gitlab-ci.yml

image: docker:latest

variables:
  CONTAINER_IMAGE: registry.gitlab.com/joklein
  DOCKER_IMAGE: jupyterhub
  TAG: 0.1.0

services:
  - docker:dind

stages:
  - build
  - test
  - release
  - deploy

before_script:
  - echo "$GITLAB_PASSWORD" | docker login registry.gitlab.com --username $GITLAB_USER --password-stdin

build:
  stage: build
  script:
    - docker build -t $CONTAINER_IMAGE/$DOCKER_IMAGE .
    - docker push $CONTAINER_IMAGE/$DOCKER_IMAGE

test:
  stage: test
  script:
    - docker pull $CONTAINER_IMAGE/$DOCKER_IMAGE
      #    - docker run $CONTAINER_IMAGE/$DOCKER_IMAGE -dt -p 8000:8000 --name $DOCKER_IMAGE

release:
  stage: release
  script:
    - docker pull $CONTAINER_IMAGE/$DOCKER_IMAGE
    - docker tag  $CONTAINER_IMAGE/$DOCKER_IMAGE:latest $CONTAINER_IMAGE/$DOCKER_IMAGE:$TAG
    - docker push $CONTAINER_IMAGE/$DOCKER_IMAGE:$TAG
  only:
    - master

deploy:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk update && apk add git openssh-client rsync
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
    - mkdir "${HOME}/.ssh"
    - echo "${SSH_HOST_KEY}" > "${HOME}/.ssh/known_hosts"
    - echo "${SSH_PRIVATE_KEY}" > "${HOME}/.ssh/id_rsa"
    - chmod 700 "${HOME}/.ssh/id_rsa"
    - rsync -hrvz --delete --exclude=_ public/ [email protected]:www/jupyter/
  only:
    - master

The jupyterhub_config.py

c = get_config()
# Letsencrypt (https://letsencrypt.org/) to obtain a free, trusted SSL
# certificate.
c.JupyterHub.ssl_key = '/etc/letsencrypt/live/example.com/privkey.pem'
c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/example.com/fullchain.pem'
c.JupyterHub.port = 443
#
# Change from JupyterHub to JupyterLab
c.Spawner.default_url = '/lab'
c.Spawner.debug = True
#
# # Specify users and admin
c.Authenticator.whitelist = {"systemuser"}
c.Authenticator.admin_users = {"systemuser"}

Docker base image of JupyterHub and JupyterLab

JupyterHub is a multi-user server for Jupyter notebooks. JupyterLab is the next-generation web-based user interface for the Jupyter Project. This JupyterHub is a Docker base image for JupyterHub and JupyterLab that works as a stand-alone application and in a (sub) domain.

Images derived from this image can either run as a stand-alone server, or function as a volume image for your server. You can also use them in a CI/CD system such as GitLab CI to build your content prior to bundling it into a standalone server container.

Building your JupyterHub image

Based on this structure, you can easily build an image for your needs. There are two options for using the image you generated:

• as a stand-alone image
• as a volume image for your webserver

The simplest way to build your own image is to use a Dockerfile. This is only an example. If you need more software packages you can install them with this Dockerfile and conda.

Build the container

docker build -t juypterhub .

Your JupyterHub with JupyterLab is automatically generated during this build.

Run the container

docker run -p 8000:8000 -d --name jupyterhub jupyterhub jupyterhub

• -p is used to map your local port 8000 to the container port 8000
• -d is used to run the container in background. JupyterHub will just write logs so no need to output them in your terminal unless you want to troubleshoot a server error.
• -- name jupyterhub names your container jupyterhub
• jupyterhub the image
• jupyterhub is the last command used to start the jupyterhub server

and your JupyterHub with Jupyterlab is now available of http://localhost:8000.

Start / Stop JupyterHub

docker start / stop juyterhub

Configure JupyterHub

Let's encrypt certificates for JupyterHub

To enable HTTPS on your website, you need to get a certificate (a type of file) from a Certificate Authority (CA). Let’s Encrypt is a CA. In order to get a certificate for your website’s domain from Let’s Encrypt, you have to demonstrate control over the domain. With Let’s Encrypt, you do this using software that uses the ACME protocol, which typically runs on your web host.

Change to zerossl.com and generate a certificate for your domain. As the result you get four files, domain-key.txt, domain-crt.txt, domain-csr.txt, account-key.txt. This files uses base 64, which is readable in ASCII, not binary format. The certificates are already in PEM format. Just change the extension to *.pem.

For JupyterHub only the files domain-key.txt and domain-crt are needed.

cp domain-crt.txt fullchain.pem
cp domain-key.txt privkey.pem

Add a System user in the container

By default JupyterHub searches for users on the server. In order to be able to log in to our new JupyterHub server we need to connect to the JupyterHub docker container and create a new system user with a password.

docker exec -it jupyterhub bash
useradd --create-home systemuser
passwd systemuser
exit

The command docker exec -it jupyterhub bash will spawn a root shell in your docker container. You can use the root shell to create system users in the container. These accounts will be used for authentication in JupyterHub's default configuration.

The first command useradd creates a new user named systemuser. The second will ask you for a password.

Answer 1

The all process might be simpler with GitLab 12.0 (June 2019), and its Git integration for JupyterHub

Deploying JupyterHub via GitLab’s Kubernetes integration provides an easy way to get started with Jupyter notebooks, which can be used to create and share documents that contain live code, visualizations, and even runbooks.

Starting with GitLab 12.0, JupyterLab’s Git extension is automatically provisioned and configured when installing JupyterHub onto your Kubernetes cluster.
This integration enables full version control of your notebooks as well as issuance of Git commands within Jupyter. Git commands can be issued via the Git tab on the left panel or via Jupyter’s command line prompt.

See documentation and gitlab-ce issue 47138.

Answer 2

jupyterhub --generate-config

This is what on the documentation

It created a config.py file in /srv/jupyterhub