Docs Improvement | Set up BinderHub

sgibson91 commented 5 years ago

Hello team! 👋

Here are some more questions and suggestions I had while setting up my test BinderHub deployment that I would like to feedback 😄These are specific to the Set up BinderHub page.

Step 3.1. Preparing to Install

My question here is very similar to a question I had in jupyterhub/zero-to-jupyterhub-k8s/issues/1165.

The binderhub folder created in this step is going to contain tokens, secrets and passwords. Where should it be kept such that an RSE team can work collaboratively on it, to maintain and customise the BinderHub, without compromising the security of the contents? Or if it's only being maintained by one person, can we link to some info on security for these sorts of files?

I'm planning a meeting next week where I hope to get some answers and best practices regarding the Turing deployment. Fingers crossed I'll be able to contribute some generalised guidance on this after that meeting.

Step 3.2.2. Create a `secret.yaml` file: If you are using DockerHub

Is encryption of the docker ID and password supported by BinderHub? If so, can we include how to do this? I feel kind of uncomfortable leaving a file with my password in it somewhere on my laptop 😬This could also fall under the security aspect I mentioned in the last point ☝️

Step 3.4. Install BinderHub

In the helm install command, --version is given as 0.1.0-... but I think the chart is well into 0.2.0-... now. Shall we update it or is it given as 0.1.0-... for a specific reason? See #804

Step 3.5. Connect BinderHub and JupyterHub

It might be worth noting here that the --version argument parsed to the helm upgrade command should be the same number-commit combo as in Step 3.4 for first-time deployment - but isn't necessary if you're updating JupyterHub/BinderHub to a newer, stable chart release? Also, I think there's a stray v in that argument that's not supposed to be there? See #804

I hope this is useful and thank you!! Hopefully, I'll learn some things around the security aspect over the next week or so that I can contribute in a PR. I'm happy to clean up some of the smaller things I've mentioned as well 😄

betatim commented 5 years ago

On the security/encrypted files point: for mybinder.org we use https://github.com/AGWA/git-crypt to encrypt files "transparently". This means if you have the key and "unlock" the vault the files are readable with your normal tools (vim or emacs or cat). However in a "locked" version of the repo you just get gibberish https://github.com/jupyterhub/mybinder.org-deploy/tree/master/secrets

Now you have a choice to lock and unlock your vault to not have secrets that are readable by everyone. I think there are other tools as well that could be used that are a bit more user friendly. One thing I struggled with in particular is distribution of the key via ssh-vault. It worked in the end but took me a few attempts. The full docs on how to obtain the secrets is https://mybinder-sre.readthedocs.io/en/latest/production_environment.html#secrets.

An alternative workflow for sharing the key that unlocks the git-crypt vault is http://keybase.io/ who have a nice user friendly desktop client and shared encrypted folders for a group. I've used this for sharing secrets with less tech savvy people and it worked well. You can even store a whole git repository there, but you can't use GitHub any more. If I was to start again today I'd combine keybase for distribution of the key and git-crypt for in-repo encryption.

betatim commented 5 years ago

Step 3.4 -> jupp updating is a good idea. I don't think there is a good reason it lags behind other than no one has gotten round to updating it in a while. maybe we can add a sentence saying "this is an example that should just work but if you are doing this for real go find the most recent version here"? I like tutorials where the commands just work and then requiring some updating. That way I know that the command itself is working and that the tutorial is broken/I made a mistake/etc. Then it is a "small" step to insert the most recent version.

I think one PR per point/topic (security&secrets, 3.4+3.5) would be good. In the hopes that each separately can be merged quickly because it is uncontroversial.

sgibson91 commented 5 years ago

PR open for updating steps 3.4 & 3.5: #804

manics commented 3 years ago

What else needs to be done here?

sgibson91 commented 3 years ago

In the wisdom I have learned since opening this issue (which I believe is my first open contribution!), I would say that to address the first 2 points I raised all that is required is some links in the docs to resources like Key Vaults for sharing secrets amongst distributed teams, and sops for encrypting files (as examples). Maybe some little note boxes like "Wanting to run a BinderHub in production and worried about X? Go here to learn more about this solution!"

jupyterhub / binderhub