Improve documentation around when / how to create your own environment

[choldgraf]

Background

Most administrators of a hub expect to be able to define their own environment (either for themselves or for their users). Currently, we have a few recommendations for customizing the environment, but this documentation could be improved. We should make it clear the recommendations for how people can customize their environments.

Here are a few scenarios to consider and document, in decreasing order of priority (so most-recommended first).

via pip installs in the notebooks

• Either by putting them in the first cell of notebooks
• Or asking administrators to put a requirements.txt in shared_readwrite that then gets referenced in user notebooks etc
• CH: could we somehow allow conda to discover environments that were present in ~/shared?
• Perhaps we can document a few patterns they could follow here...

via a custom Docker image for the hub

Some things we might want to cover:

• Brief idea of "what is Docker, images, etc"
• Scenarios that mean a person needs to create their own image
• Point to guides to use things like the repo2docker-action so people will be able to more easily update environments
• Considerations for data / keys / license files etc (things to access sensitive data)

We should also decide when the amount of customizations they request is enough to warrant a more complex hub at a higher price.

via changes to the base environment for all hubs

Finally, users can request that we change the base environment for all hubs. However, this is a highly non-scalable approach and is a long-term anti-pattern (the environments for base hubs should be chosen based on what we think is the "best" environment for a particular use-case, not based on what users happen to request).

Expected timeline

2 months or so. We could make quick progress now, but will also need to update this as we learn more while more people have to create their own images. We may also need to update as the technology changes.

Steps to complete this goal

• Take a pass at our current documentation to improve the reasoning etc behind environment generation
• Have some users try it out, give feedback
• Wait and watch, see if this continues to be unclear (if we continue getting questions about it) and add docs as needed

[yuvipanda]

I opened jupyterhub/repo2docker-action#60 to document how to use quay.io with jupyter-repo2docker. 2i2c-org/docs#55 has an environment page with the three options discussed here.

[choldgraf]

I believe this is now completed by 2i2c-org/docs#55 and is in our Hub Administrator's guide