How to test k8s-singleuser-sample alone and locally -- without deploying to EKS?

Hi, there,

Since I need to rebuild the docker images based on Amazon linux, I want to do the local test to make sure the image works. However, when I tried to run out of box of k8s-singleuser-sample docker image, and I also config the host port as 8888, even I can run it using docker command, however, I just can’t access the web console (I got the URL from the log – the last line). The error message is (I also tried localhost but got same error):

This page isn’t working didn’t send any data.

Could anyone let me know if I can run the singleuser-sample alone and locally? If I can, how to do that?

By the way, since I will also need to rebuild proxy and hub, could anyone let me know how to do the local test for those two images? I mean by just running the docker image locally, without deploying to EKS.

Many thanks!

I’m pretty sure this is due to the server binding to localhost only so expose doesn’t work, on kubernetes networking is plumbed differently. To test locally with docker you should be able to override the command.

I just tested locally as follows

  1. cd images/singleuser-sample
  2. docker build -t k8s-singleuser-sample:local .

If you just run per the you can check to see if it is actually running by docker exec -it CONTAINER_ID python and using requests to connect locally (the image doesn’t have curl or netstat I think).

Python 3.11.1 (main, Jan 23 2023, 21:18:23) [GCC 10.2.1 20210110] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import requests
>>> requests.get("")
<Response [200]>

To get it to bind correctly for local testing just give it the command setting the ip to

docker run  -it  --rm  -p 8888:8888 k8s-singleuser-sample:local -- jupyter lab  --ip

Then try in your browser.

Thanks Pris! @pnasrat

A quick question, could you let me know the image location? I am using Windows 10 with WSL 2, I searched everywhere but just can’t find the images. Also, if I run docker info, I will get
Docker Root Dir: /var/lib/docker
But apparently it’s not available on my windows machine.

In fact, if I understand correctly, I can just download the singleuser-sample dockerfile, and then run the build command suggested by you:
docker build -t k8s-singleuser-sample:local .

Will that work? If that works, could you confirm below is the correct dockerfile for singleuser-sample:

Also, how can tell if above link is version 2.0.0? If not, could you let me know how to get the dockerfile for the version 2.0.0?

Much thanks!

If you just want to run the image you don’t need the build step you can pull the image and run

docker pull jupyterhub/k8s-singleuser-sample:2.0.0
docker run  -it  --rm  -p 8888:8888 jupyterhub/k8s-singleuser-sample:2.0.0  -- jupyter lab  --ip

To correctly build the image you will want to clone the repository so you have the requirements files the image build uses as well as the Dockerfile. If you absolutely want to build off the tag you can do:

git clone
cd zero-to-jupyterhub-k8s/images/singleuser-sample
git checkout 2.0.0

You shouldn’t have to worry about the local location of the image on disk - but to get this to work you’ll need to push the rebuilt image to a repository that your kubernetes cluster has access to and override the image in your helm config.yaml - see Customizing User Environment — Zero to JupyterHub with Kubernetes documentation

Also I’m wondering why you have to rebuild the images on Amazon linux - I don’t think EKS requires that. Is there another customization you are doing.

Just trying to understand your end goal here


1 Like

@pnasrat Thanks, Pris! However, I got error when I tried to run the docker command you suggested. Below is the command and error:

docker run -it --rm -p 8888:8888 jupyterhub/k8s-singleuser-sample:2.0.0 – jupyter lab --ip

[FATAL tini (7)] exec – failed: No such file or directory

Could you take a look?


Because of the security concern, we have to rebuild the docker images based on Amazon Linux.

My instructions were written assuming you are using a UNIX shell to run, that takes a double dash -- to mean end of argument parsing.

I don’t have a Windows shell readily available to me to test. But this looks as if the shell you are using does not do this (you mentioned WSL so I assumed you might be using bash). Try either without the double dash

docker run -it --rm -p 8888:8888 jupyterhub/k8s-singleuser-sample:2.0.0 jupyter lab --ip

Or if you are using powershell you might be able to use --% in that case

However this is largely outside of your original question

@pnasrat Thanks, Pris! It works now!

By the way, any idea about how to test hub and proxy locally : - )


@sam123 given your goal is rebuilding images from a different base to run on EKS, that is not really using Zero to JupyterHub on Kubernetes.

I would probably recommend you build and test using the helm charts and a local kubernetes (minikube, k3s, kind).

I don’t think you are going to get the testing you want using just the docker images.

However you should be able to get each individual component running locally - for hub you probably want to provide a config.

Can you explain a bit more about the security issue you mention

If it is a specific CVE that needs a rebuild that wouldn’t need you to basically create your own images. I do see that there is an automatic scan for vulnerabilities that causes rebuilds - eg see this

Amazon Linux also gets CVEs and would need updating as far as I understand it

@pnasrat Thanks for the information, Pris!

Per your questions, it’s the company policy about docker base image (must base on Amazon Linux). It’s kind of strange requirement but leaves no choice for us except rebuild.

The local testing what I mean is to do the preliminary testing locally using docker (instead of deploy to EKS). For example, for singleuser, as long as I can run the docker image locally as a docker container and can access the Notebook web console, then I can do some functional testing to make sure the rebuilt docker image works (to some kind). Of course, eventually will deploy the rebuilt docker image to EKS for the finial testing.

Same thing for hub and proxy local testing. I just want to make sure I can run both locally using docker, and do some preliminary testing locally to make sure the docker image works and the main function works. After that, will deploy both to EKS for the final testing.

Please let me know for any further questions.

In that case, I would greatly appreciate if you could advice how to do the local test for hub and proxy–just need to run as docker container, then either ssh login the container or maybe there are some external tools that I can use to do some functional testing.

Thanks and have a great weekend!

@pnasrat Hi, Pris,

A quick question, after I start the singleuser-sample locally as a docker container, there is no authentication and I can go directly get to the web console, as a normal user. I know the hub will do the authentication part. My question is, if there is any simple settings to change on singleuser-sample to make the user as admin. I just want to test more locally.

Thanks and have a great weekend!