mirror of
https://github.com/jupyter/docker-stacks.git
synced 2025-10-07 18:14:05 +00:00
bceaead5d2
* Migrate start-notebook.sh to bash Based on > Stop using bash, haha 👍 from https://github.com/jupyter/docker-stacks/issues/1532. If there's more apetite for this, I'll try to migrate `start.sh` and `start-singleuser.sh` as well - I think they should all be merged together. We can remove the `.sh` suffixes for accuracy, and keep symlinks in so old config still works. Since the shebang is what is used to launch the correct interpreter, the `.sh` doesn't matter. Will help fix https://github.com/jupyter/docker-stacks/issues/1532, as I believe all those things are going to be easier to do from python than bash * Rename start-notebook.sh to start-notebook * Cleanup start-notebook a little * Fix typo * Migrate start-singleuser as well * Remove unused import * Run symlink commands as root * Combine repetitive RUN commands * Remove multiple args to env -u can not be set by shebang, we must set the env var instead * Fix conditional inversion Co-authored-by: Ayaz Salikhov <mathbunnyru@users.noreply.github.com> * Fix how start-singleuser is exec'd * Actually call jupyterhub-singleuser in start-singleuser * Pass through any additional args we get * Put .py suffix on the start-* scripts * Add .sh shims for the start-* scripts * Document start-notebook.sh and start-singleuser.sh * Partially test start-notebook.sh * Reflow warning docs Co-authored-by: Ayaz Salikhov <mathbunnyru@users.noreply.github.com> --------- Co-authored-by: Ayaz Salikhov <mathbunnyru@users.noreply.github.com>
192 lines
8.8 KiB
Markdown
192 lines
8.8 KiB
Markdown
# Running a Container
|
|
|
|
Using one of the Jupyter Docker Stacks requires two choices:
|
|
|
|
1. Which Docker image you wish to use
|
|
2. How you wish to start Docker containers from that image
|
|
|
|
This section provides details about the second.
|
|
|
|
## Using the Docker CLI
|
|
|
|
You can launch a local Docker container from the Jupyter Docker Stacks using the [Docker command-line interface](https://docs.docker.com/engine/reference/commandline/cli/).
|
|
There are numerous ways to configure containers using the CLI.
|
|
The following are some common patterns.
|
|
|
|
### Example 1
|
|
|
|
This command pulls the `jupyter/scipy-notebook` image tagged `2023-09-25` from Docker Hub if it is not already present on the local host.
|
|
It then starts a container running Jupyter Server with the JupyterLab frontend and exposes the server on host port 8888.
|
|
The server logs appear in the terminal and include a URL to the server.
|
|
|
|
```bash
|
|
docker run -it -p 8888:8888 jupyter/scipy-notebook:2023-09-25
|
|
|
|
# Entered start.sh with args: jupyter lab
|
|
|
|
# ...
|
|
|
|
# To access the server, open this file in a browser:
|
|
# file:///home/jovyan/.local/share/jupyter/runtime/jpserver-7-open.html
|
|
# Or copy and paste one of these URLs:
|
|
# http://042fc8ac2b0c:8888/lab?token=f31f2625f13d131f578fced0fc76b81d10f6c629e92c7099
|
|
# or http://127.0.0.1:8888/lab?token=f31f2625f13d131f578fced0fc76b81d10f6c629e92c7099
|
|
```
|
|
|
|
Pressing `Ctrl-C` twice shuts down the Server but leaves the container intact on disk for later restart or permanent deletion using commands like the following:
|
|
|
|
```bash
|
|
# list containers
|
|
docker ps --all
|
|
# CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
|
# 221331c047c4 jupyter/scipy-notebook:2023-09-25 "tini -g -- start-no…" 11 seconds ago Exited (0) 8 seconds ago cranky_benz
|
|
|
|
# start the stopped container
|
|
docker start --attach 221331c047c4
|
|
# Entered start.sh with args: jupyter lab
|
|
# ...
|
|
|
|
# remove the stopped container
|
|
docker rm 221331c047c4
|
|
# 221331c047c4
|
|
```
|
|
|
|
### Example 2
|
|
|
|
This command pulls the `jupyter/r-notebook` image tagged `2023-09-25` from Docker Hub if it is not already present on the local host.
|
|
It then starts a container running Server and exposes the server on host port 10000.
|
|
The server logs appear in the terminal and include a URL to the Server, but with the internal container port (8888) instead of the correct host port (10000).
|
|
|
|
```bash
|
|
docker run -it --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work jupyter/r-notebook:2023-09-25
|
|
```
|
|
|
|
Pressing `Ctrl-C` twice shuts down the Server and immediately destroys the Docker container.
|
|
New files and changes in `~/work` in the container will be preserved.
|
|
Any other changes made in the container will be lost.
|
|
|
|
```{note}
|
|
By default, [jupyter's root_dir](https://jupyter-server.readthedocs.io/en/latest/other/full-config.html) is `/home/jovyan`.
|
|
So, new notebooks will be saved there, unless you change the directory in the file browser.
|
|
|
|
To change the default directory, you will need to specify `ServerApp.root_dir` by adding this line to previous command: `start-notebook.py --ServerApp.root_dir=/home/jovyan/work`.
|
|
```
|
|
|
|
### Example 3
|
|
|
|
This command pulls the `jupyter/all-spark-notebook` image currently tagged `latest` from Docker Hub if an image tagged `latest` is not already present on the local host.
|
|
It then starts a container named `notebook` running a JupyterLab server and exposes the server on a randomly selected port.
|
|
|
|
```bash
|
|
docker run --detach -P --name notebook jupyter/all-spark-notebook
|
|
```
|
|
|
|
where:
|
|
|
|
- `--detach`: will run the container in detached mode
|
|
|
|
You can also use the following docker commands to see the port and Jupyter Server token:
|
|
|
|
```bash
|
|
# get the random host port assigned to the container port 8888
|
|
docker port notebook 8888
|
|
# 0.0.0.0:49153
|
|
# :::49153
|
|
|
|
# get the notebook token from the logs
|
|
docker logs --tail 3 notebook
|
|
# Or copy and paste one of these URLs:
|
|
# http://878f1a9b4dfa:8888/lab?token=d336fa63c03f064ff15ce7b269cab95b2095786cf9ab2ba3
|
|
# or http://127.0.0.1:8888/lab?token=d336fa63c03f064ff15ce7b269cab95b2095786cf9ab2ba3
|
|
```
|
|
|
|
Together, the URL to visit on the host machine to access the server, in this case, is <http://127.0.0.1:49153/lab?token=d336fa63c03f064ff15ce7b269cab95b2095786cf9ab2ba3>.
|
|
|
|
The container runs in the background until stopped and/or removed by additional Docker commands:
|
|
|
|
```bash
|
|
# stop the container
|
|
docker stop notebook
|
|
# notebook
|
|
|
|
# remove the container permanently
|
|
docker rm notebook
|
|
# notebook
|
|
```
|
|
|
|
## Using the Podman CLI
|
|
|
|
An alternative to using the Docker CLI is to use the Podman CLI. Podman is mostly compatible with Docker.
|
|
|
|
### Podman example
|
|
|
|
If we use Podman instead of Docker in the situation given in _Example 2_, it will look like this:
|
|
|
|
The example makes use of rootless Podman; in other words, the Podman command is run from a regular user account.
|
|
In a Bash shell, set the shell variables _uid_ and _gid_ to the UID and GID of the user _jovyan_ in the container.
|
|
|
|
```bash
|
|
uid=1000
|
|
gid=100
|
|
```
|
|
|
|
Set the shell variables _subuidSize_ and _subgidSize_ to the number of subordinate UIDs and GIDs, respectively.
|
|
|
|
```bash
|
|
subuidSize=$(( $(podman info --format "{{ range .Host.IDMappings.UIDMap }}+{{.Size }}{{end }}" ) - 1 ))
|
|
subgidSize=$(( $(podman info --format "{{ range .Host.IDMappings.GIDMap }}+{{.Size }}{{end }}" ) - 1 ))
|
|
```
|
|
|
|
This command pulls the `docker.io/jupyter/r-notebook` image tagged `2023-09-25` from Docker Hub if it is not already present on the local host.
|
|
It then starts a container running a Jupyter Server with the JupyterLab frontend and exposes the server on host port 10000.
|
|
The server logs appear in the terminal and include a URL to the server, but with the internal container port (8888) instead of the correct host port (10000).
|
|
|
|
```bash
|
|
podman run -it --rm -p 10000:8888 \
|
|
-v "${PWD}":/home/jovyan/work --user $uid:$gid \
|
|
--uidmap $uid:0:1 --uidmap 0:1:$uid --uidmap $(($uid+1)):$(($uid+1)):$(($subuidSize-$uid)) \
|
|
--gidmap $gid:0:1 --gidmap 0:1:$gid --gidmap $(($gid+1)):$(($gid+1)):$(($subgidSize-$gid)) \
|
|
docker.io/jupyter/r-notebook:2023-09-25
|
|
```
|
|
|
|
```{warning}
|
|
The `podman run` options `--uidmap` and `--gidmap` can be used to map the container user _jovyan_ to the regular user on the host when running rootless Podman.
|
|
The same Podman command should not be run with sudo (i.e. running rootful Podman)
|
|
because then the mapping would map the container user _jovyan_ to the root user on the host.
|
|
It's a good security practice to run programs with as few privileges as possible.
|
|
```
|
|
|
|
```{note}
|
|
The `podman run` command in the example above maps all subuids and subgids of the user into the container.
|
|
That works fine but is actually more than needed.
|
|
The `podman run` option `--userns=auto` will, for instance, not be possible to use as long as there are no unused subuids and subgids available.
|
|
The example could be improved by investigating more in detail which UIDs and GIDs need to be available in the container and then only map them.
|
|
```
|
|
|
|
Pressing `Ctrl-C` twice shuts down the Server and immediately destroys the Docker container.
|
|
New files and changes in `~/work` in the container will be preserved.
|
|
Any other changes made in the container will be lost.
|
|
|
|
## Using Binder
|
|
|
|
[Binder](https://mybinder.org/) is a service that allows you to create and share custom computing environments for projects in version control.
|
|
You can use any of the Jupyter Docker Stacks images as a basis for a Binder-compatible Dockerfile.
|
|
See the
|
|
[docker-stacks example](https://mybinder.readthedocs.io/en/latest/examples/sample_repos.html#using-a-docker-image-from-the-jupyter-docker-stacks-repository) and
|
|
[Using a Dockerfile](https://mybinder.readthedocs.io/en/latest/tutorials/dockerfile.html) sections in the
|
|
[Binder documentation](https://mybinder.readthedocs.io/en/latest/index.html) for instructions.
|
|
|
|
## Using JupyterHub
|
|
|
|
You can configure JupyterHub to launcher Docker containers from the Jupyter Docker Stacks images.
|
|
If you've been following the [Zero to JupyterHub with Kubernetes](https://z2jh.jupyter.org/en/latest/) guide,
|
|
see the [Use an existing Docker image](https://z2jh.jupyter.org/en/latest/jupyterhub/customizing/user-environment.html#choose-and-use-an-existing-docker-image) section for details.
|
|
If you have a custom JupyterHub deployment, see the [Picking or building a Docker image](https://jupyterhub-dockerspawner.readthedocs.io/en/latest/docker-image.html)
|
|
instructions for the [dockerspawner](https://github.com/jupyterhub/dockerspawner) instead.
|
|
|
|
## Using Other Tools and Services
|
|
|
|
You can use the Jupyter Docker Stacks with any Docker-compatible technology
|
|
(e.g., [Docker Compose](https://docs.docker.com/compose/), [docker-py](https://github.com/docker/docker-py), your favorite cloud container service).
|
|
See the documentation of the tool, library, or service for details about how to reference, configure, and launch containers from these images.
|