Add a FAQ entry for 'nbgitpuller link selecting profile options'

[yuvipanda]

This gets asked a lot, and it would be useful to have a central place to point people to!

[consideRatio]

The general case to discuss is when Spawner.options_form is configured and server options are presented, where KubeSpawner.profile_list is a way to provide a specialized Spawner.options_form indirectly.

I think there are separate things to consider:

1. To have jupyterhub pre-populates choices in the rendered options_form Currently the options_form is rendered to users without considerations to query parameters passed, based on inspecting this, and this, and this. In practice I think either the rendering of the options_form jinja2 HTML template that need to be done based on query parameters passed indicating what options to pre-select together with options_form content that respects this, or what was rendered need to include javascript to pre-select the choices just after the default choices has been selected.

2. To have jupyterhub directly start a server if needed based on provided choices Based on this, and this, I think JupyterHub can spawn a server directly.

   In order to spawn a server, not using the REST API which would require setup, but using the /hub/spawn page, its possible to use either a POST request or a GET request.

   • When using the POST request (the rendered options_from has been submitted), form data is provided in the web request's body.
   • When using GET request (from having carefully crafted a link yourself, this is otherwise not done), the form data must be put in query string parameters instead.

   The difference between the POST request and GET request is mostly that the information passed to the spawner is parsed via either Spawner.options_from_form (POST) or Spawner.options_from_query (GET), but that the latter is implemented by default to just rely on Spawner.options_from_form.

Practical direct spawn test via link

Since I think its possible to have jupyterhub directly start a server if needed based on provided choices in a link, I'll trial to mimic this POST request in a hub with an options_form based on KubeSpawner.profile_list by carefully crafting a link.

To craft a link with query parameters, I first inspect the equivalent form submission to start a server via chrome's inspector's network section. The form looked like this:

The POST requests's body looked like this:

Knowing that kubespawner in its main branch (used when testing, with https://github.com/jupyterhub/kubespawner/pull/774) accepts being passed only some choices and letting the others be set to the defaults, I tested the following spawn link.

https://my-hub.example.com/hub/spawn?profile=small and it worked out to start a server, and clicking it again took me to a started, where changing the profile=small to profile=medium would have no effect once the server was started via the first link-click.

Okay, so how can we combine this with a nbgitpuller link? Can I make a link like this be combined with a "start profile=small" choice?

https://my-hub.example.com/hub/user-redirect/git-pull?repo=https%3A%2F%2Fgithub.com%2FconsideRatio%2Fstencils&urlpath=lab%2Ftree%2Fstencils%2Fderiv-antideriv.ipynb&branch=master

Yes, this works by combining the spawn server link https://my-hub.example.com/hub/spawn?profile=small by appending &next=<other link url encoded> where the other link is /hub/user-redirect/git-pull?repo=https%3A%2F%2Fgithub.com%2FconsideRatio%2Fstencils&urlpath=lab%2Ftree%2Fstencils%2Fderiv-antideriv.ipynb&branch=master, but then URL-encoded (google and a website can do this for you).

Conclusion

We can craft links to "auto-launch if server is started or use the existing server and then git pull", but generating such links require information about the configured Spawner.options_form (or KubeSpawner.profile_list) as well.

Nbgitpuller link generator enhancement proposal

If the link generator is to support this, I think we should make it Spawner agnostic and options_form agnostic, instead just allowing the user to declare query parameters to pass to hub/spawn. If such parameters are specified, the resulting link will take on a different form, where it will transition from visiting /hub/user-redirect/git-pull... to visiting /hub/spawn?parameter1=value1&parameter2=value2&next=%2Fhub%2Fuser-redirect%2Fgit-pull....

[yuvipanda]

Thanks @consideRatio. The primary problem here is the case (2) outlined in the PR - what happens when there is already a server running, but it was started with a different profile and options?

Also, what do you think is the path forward for this particular PR?

[sgibson91]

Also, what do you think is the path forward for this particular PR?

I think we should merge this PR as is for now, and make Erik's comment a new issue for further discussion and planning around completing the required work, including the question around "what if a server is already running". This docs section can be updated when those changes are rolled out.

[yuvipanda]

Thanks @consideRatio and @sgibson91!