Improve the "creating your user's environment" section

[choldgraf]

We should improve the sections of z2jh that discuss how to construct a Docker image that your users can use. We can use this issue to discuss a few related ones that talk about more specific cases of this as well.

Steps to close this issue

• follow instructions on customisation via repo2docker
• try out the image you built
• if this fails work out which additional repo2docker flags/settings need to be set
• add those instructions to the documentation

#414
#402

[betatim]

Also #608

[consideRatio]

@choldgraf @betatim this is set as a 0.7 milestone - I'm prioritizing #758 but want to push onwards to a release - could you on a course of action for this issue? I'm thinking along the lines of deciding to implement / delegate / abandon / postpone the issue.

[betatim]

Steps to close this:

• follow instructions on customisation via repo2docker
• try out the image you built
• if this fails work out which additional repo2docker flags/settings need to be set
• add those instructions to the documentation

[choldgraf]

I updated the top-level comment to include @betatim 's helpful info

[consideRatio]

Would you agree that the repo2docker instructions should not be featured this much in the guide as they currently are? I think the best practice is to use an existing jupyter/docker-stacks image or build of one of those. Using repo2docker together with z2jh will cause a lot of additional challenges not currently mentioned.

I'm working in #850 to refresh the most basic parts to work well and be up to date for the JupyterHub tutorial. I'd love for a brief review on Tuesday and the trust to accept the changes even though they might not be perfect - but as better than the current state which is too out of date.

[consideRatio]

I went through this section quite thoroughly, the repo2docker instructions does not really belong in here as the created images are not well suited for use with a real jupyterhub where storage is persistent.

The repo2docker instructions, which i went through before removing them, are now unlinked in the docs.