Restore jupyterhub-singleuser as the default command

update docs to explain explicit `cmd: null` use case

Author: minrk

docs/source/jupyterhub/customizing/user-environment.md

@@ -44,6 +44,9 @@ image containing useful tools and libraries for data science, complete these ste
        # https://github.com/jupyter/docker-stacks/tree/HEAD/datascience-notebook/Dockerfile
        name: jupyter/datascience-notebook
        tag: latest
+       # `cmd: null` allows the custom CMD of the Jupyter docker-stacks to be used
+       # which performs further customization on startup.
+       cmd: null
    ```
 
    ```{note}
@@ -244,10 +247,9 @@ FROM jupyter/minimal-notebook:latest
 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"]
+# if you want to launch more complex startup than the default `juptyerhub-singleuser`.
+# To launch an image's custom CMD instead of the default `jupyterhub-singleuser`
+# set `singleuser.cmd: null` in your config.yaml.
 ```
 
 ```{note}
@@ -529,25 +531,33 @@ 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:
+By default, zero-to-jupyterhub will launch the command `jupyterhub-singleuser`.
+If you have an image (such as `jupyter/scipy-notebook` and other Jupyter Docker stacks)
+that defines a CMD with startup customization and ultimately launches `jupyterhub-singleuser`,
+you can chose to launch the image's default CMD instead by setting:
 
 ```yaml
 singleuser:
-  cmd: jupyterhub-singleuser
+  cmd: null
 ```
 
-```{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.
+Alternately, you can specify an explicit custom command as a string or list of strings:
+
+```yaml
+singleuser:
+  cmd:
+    - /usr/local/bin/custom-command
+    - "--flag"
+    - "--other-flag"
 ```
 
+:::{note}
+Docker has `ENTRYPOINT` and `CMD`,
+which k8s calls `command` and `args`.
+zero-to-jupyterhub always respects the ENTRYPOINT of the image,
+and setting `singleuser.cmd` only overrides the CMD.
+:::
+
 ## Disable specific JupyterLab extensions
 
 Sometimes you want to temporarily disable a JupyterLab extension on a JupyterHub

jupyterhub/schema.yaml

@@ -1019,7 +1019,7 @@ properties:
           extraPorts:
             type: array
             description: |
-              Extra ports to add to the Hub Service object besides `hub` / `8081`.  
+              Extra ports to add to the Hub Service object besides `hub` / `8081`.
               This should be an array that includes `name`, `port`, and `targetPort`.
               See [Multi-port Services](https://kubernetes.io/docs/concepts/services-networking/service/#multi-port-services) for more details.
           loadBalancerIP:
@@ -2124,6 +2124,10 @@ properties:
         description: |
           Passthrough configuration for
           [KubeSpawner.cmd](https://jupyterhub-kubespawner.readthedocs.io/en/latest/spawner.html#kubespawner.KubeSpawner.cmd).
+          The default is "jupyterhub-singleuser".
+          Use `cmd: null` to launch a custom CMD from the image,
+          which must launch jupyterhub-singleuser eventually.
+          For example: Jupyter's docker-stacks images.
       defaultUrl:
         type: [string, "null"]
         description: |
@@ -2636,7 +2640,7 @@ properties:
         description: |
           The path type to use. The default value is 'Prefix'.
 
-          See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#path-types) 
+          See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#path-types)
           for more details about path types.
       tls:
         type: array

jupyterhub/values.yaml

@@ -394,7 +394,7 @@ singleuser:
   extraResource:
     limits: {}
     guarantees: {}
-  cmd:
+  cmd: jupyterhub-singleuser
   defaultUrl:
   extraPodConfig: {}
   profileList: []