Docker README Fixes

[jakirkham]

• Brings back a note in the README about the /notebook directory in the container.
• Switches back to the old form of port mapping as it appears the current form, unfortunately, maps ports randomly within a range. ( https://docs.docker.com/articles/networking/#binding-ports )

[jakirkham]

@funkyfuture, bringing to your attention.

[funkyfuture]

It should be rephrased to make clear that the data volume will be created internally and persist(!) if not overridden like in the example.

[jakirkham]

How do you mean persist here? Using --rm means the container will be cleaned up on exit.

[funkyfuture]

your example may be well for demonstration purposes. but it's hardly useful for daily usage.

my point is: this is a documentation of the Docker image. that image includes a volume declaration. for non-demonstration-usages it is essential to mention this volume explicitly.

[funkyfuture]

All notebooks from your session will be saved in the current directory. In reality, they are save inside the container at /notebook.

in the case of the example this is not true and a contradiction.

[jakirkham]

your example may be well for demonstration purposes. but it's hardly useful for daily usage.

I respectfully disagree. There are quite a few dependencies required by jupyter. Getting a nice working copy can sometimes be tricky. Being able to startup a docker container instead of debugging the build/install process is a huge asset. Not having to understand all of the ends and outs of docker in order to get jupyter up and running makes this worthwhile for the average end user.

If your point here is that docker is normally used on cluster deployments and the like, then I think that user will know enough about docker that they will have no problem changing these options to fit their needs.

my point is: this is a documentation of the Docker image. that image includes a volume declaration. for non-demonstration-usages it is essential to mention this volume explicitly.

Which it now is.

All notebooks from your session will be saved in the current directory. In reality, they are save inside the container at /notebook.
in the case of the example this is not true and a contradiction.

Not true. They are saved in that directory. While the container is up and running one could still find these using docker exec. The container is merely blown away on exit instead of merely being stopped.

I have tried to add a line to address the concern you have raised. If you think I have not done so, please be explicit about what you would like to see instead. I would like this to be resolved in a manner that we can both find satisfactory soon.

[funkyfuture]

They are saved in that directory.

yes, that's the path inside the container. but with the example with a host-path mounted, in 'reality' the nbs are saved in that host-path. or, if no mounted volumes is given, they will be saved in an extra data volume, that is not in the container, but used by it.

i will provide a proposal for a wording after a nap.

[willingc]

@jakirkham @funkyfuture Thank you both for sharing your thoughts. Let's please remember that all documentation is about the end user. Those end users are going to vary in skill and use cases.

Clarity and concrete points are most helpful in the README. I recommend that we work toward the 80/20 rule. Try to cover 80% of the typical users in the README and link the other 20% to more detailed information in the project documentation. Thank you. 🐧

[jakirkham]

Sorry this got really noisy. I had only meant to be helpful since I was already submitting a small patch and @funkyfuture made a good point. However, I think this was the wrong move in retrospect as I am clearly missing the mark as to what he is after and that isn't helping anyone. I would like to ask @funkyfuture to supply his own patch.

[willingc]

@jakirkham Oh no worries. I think that both you and @funkyfuture have helpful views here. I've opened an issue #571 since I believe that folks could benefit from the detail. 🍰

[funkyfuture]

hm, i'd just undo cb080df.

but again, that is targeted only to users who read here and links the relevant docs about volumes in Docker. in developing it's absolutely reasonable to use --rm.

[coveralls]

Changes Unknown when pulling 3c0c52c on jakirkham:docker_readme_fixes into ** on jupyter:master**.