Skip to content

Unset singleuser.cmd, previously jupyterhub-singleuser, to instead rely on the image's CMD by default #2449

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 25, 2021
Merged

Unset singleuser.cmd, previously jupyterhub-singleuser, to instead rely on the image's CMD by default #2449

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5e74a78
leave default cmd to the image
minrk Oct 21, 2021
9170bc8
document setting singleuser.cmd
minrk Oct 21, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions doc/source/jupyterhub/customizing/user-environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,6 +242,12 @@ FROM jupyter/minimal-notebook:177037d09156

# install additional package...
RUN pip install --no-cache-dir astropy

# set the default command of the image,
# if the parent image will not launch a jupyterhub singleuser server.
# The JupyterHub "Docker stacks" do not need to be overridden.
# Set either here or in `singleuser.cmd` in your values.yaml
# CMD ["jupyterhub-singleuser"]
Comment on lines +246 to +250
Copy link
Member

@consideRatio consideRatio Oct 21, 2021 •
edited by minrk
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this to be such a tricky subject that motivates some thorough explanation, if not to help us maintainers get less questions to answer manually, and to help questions be raised where they belong (z2jh / jupyterhub / docker-stacks).

Suggested change
# set the default command of the image,
# if the parent image will not launch a jupyterhub singleuser server.
# The JupyterHub "Docker stacks" do not need to be overridden.
# Set either here or in `singleuser.cmd` in your values.yaml
# CMD ["jupyterhub-singleuser"]
# NOTE: JupyterHub's user servers must in the end start the jupyterhub-singleuser
# script, but there are options on how to go about it.
#
# 1. Let the image define a ENTRYPOINT / CMD combination that results in
# jupyterhub-singleuser being started.
#
# The https://github.com/jupyter/docker-stacks derived images, such as
# jupyter/minimal-notebook, are already already configured to start
# jupyterhub-singleuser via another startup script declared in
# their Dockerfile's CMD field.
#
# If you write a Dockerfile from scratch, install the jupyterhub pip
# package or the jupyterhub-base conda-forge package and then declare
# CMD like this:
#
# CMD ["jupyterhub-singleuser"]
#
# 2. Let the Helm chart configuration override the CMD part of what was
# defined in the image via `singleuser.cmd`.

Copy link
Member Author

@minrk minrk Oct 21, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is a good representation of this information, but too much for an inline comment in the sample Dockerfile (this one comment would be the majority of the whole Dockerfile). Can you move this to the "setting the command" section I added below and add a 'see below for details' type comment here?

Copy link
Member

@consideRatio consideRatio Oct 25, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree! I want to get this merged, I can do that in a separate PR! I opened #2452 to represent this for later.

```

```{note}
Expand Down Expand Up @@ -501,3 +507,37 @@ using the Kubespawner `profile_form_template` configuration. See the
[Kubespawner configuration reference](https://jupyterhub-kubespawner.readthedocs.io/en/latest/spawner.html)
for more information.
```

(set-cmd)=

## Set command to launch

Ultimately, a single-user server should launch the `jupyterhub-singleuser` command.
However, an image may have a custom CMD that does this,
with some preparation steps, or adding additional command-line arguments,
or launching a custom wrapper command, etc.

:::{note}
If you have environment preparation at startup in your image,
this is best done in the ENTRYPOINT of the image,
and not in the CMD, so that overriding the command does not skip your preparation.
:::

By default, zero-to-jupyterhub will launch the default CMD that is specified in your chosen image,
respecting any startup customization that image may have.
If the image doesn't launch `jupyterhub-singleuser` by default,
you will additionally need to specify `singleuser.cmd`
in your `values.yaml` as the command to launch,
so that it ultimately launches `jupyterhub-singleuser`.
The simplest version:

```yaml
singleuser:
cmd: jupyterhub-singleuser
```

:::{versionchanged} 2.0
Prior to 2.0, the default behavior of zero-to-jupyterhub was to launch `jupyterhub-singleuser` explicitly,
ignoring what was in the image.
The default command is now whatever the image runs by default.
:::
2 changes: 1 addition & 1 deletion jupyterhub/values.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -387,7 +387,7 @@ singleuser:
extraResource:
limits: {}
guarantees: {}
cmd: jupyterhub-singleuser
cmd:
defaultUrl:
extraPodConfig: {}
profileList: []
Expand Down