Welcome to a small project that enables an aspiring person to run a "Science Platform" suitable for astrophysics research. This might be overkill if all you need is a local JupyterLab notebook with Python 3.7 (and the amazing astronomy and processing libraries). However, if you want to leverage more of an ecosystem around those components with JupyterHub then this can be a springboard to launch your own project.
If you're looking for a large enterprise-scale JupyterHub deployment running on Kubernetes then checkout Zero-to-JupyterHub with k8s
- Reverse-Proxy
- Industry-standard SSO Authentication
- SQL database for persistent configurations and for SQL-based workflows
- Mock S3 object store
- Full-suite of the common Python astrophysics & astronomical libraries
- Spark processing cluster (future)
Loosely based on the documented JupyterHub deployment at Université de Versailles which is described in depth in this blog post.
Additionally look up the official JupyterHub Docker Deploy for more JupyterHub+Docker information.
This deployment is ready for you to explore. But if you want to clone and roll on your own server read below!
Disclaimer: ensure you understand the well-written by outdated blog post first, to be sure you understand the configuration.
Then, if you like, clone this repository and look into making (at least) the following changes:
- In
.env, set the variableHOSTto the name of the server you intend to host your deployment on. - In
reverse-proxy/traefik.toml, edit the paths incertFileandkeyFileand point them to your own TLS certificates. Possibly edit thevolumessection in thereverse-proxyservice indocker-compose.yml. - In
jupyterhub/jupyterhub_config.py, edit the "Authenticator" section according to your authentication server. If in doubt, read here.
Other changes you may like to make:
- Edit
jupyterlab/Dockerfileto include different software you like. Do not forget to changejupyterhub/jupyterhub_config.pyaccordingly, in particular the "user data persistence" section.
Once you are ready, build and launch the application with:
docker-compose build
docker-compose up -d
Then navigate to jupyterhub.docker.localhost (Google Chrome might work better than other browsers, YMMV)
Jupyterhub can be accessed by either registering a new user or using super:super1123 to quickly access a user space
Keycloak has the following administrator: admin:admin
docker-compose down
Creating this project was a labor of love. While it didn't take an obscene amount of time, the main frustration was the constant hunt for reference documents and examples from other successful projects. Links to additional content and resources which helped put all of the pieces together are below in no particular order.
| Link | Content |
|---|---|
| CloudServer Docker hub | Docker images and README |
| CloudServer Read the Docs | Goldmine of CloudServer documentation under previous name of S3-Server |
| CloudServer Github | CloudServer code in case you need to dig deeper |
| DockerSpawner Read the Docs | DockerSpawner docs (fun to debug!) |
| DockerSpawner Github | DockerSpawner details |
| JupyterHub Docker | Official reference deployment of JupyterHub with Docker |
| JupyterHub Oauth issue thread | Long and confusing thread. Valuable insights to understand some issues |
| JupyterHub Read the Docs | So much content here |
| JupyterHub SciPy Notebooks | If you want to start with a different JupyterLab flavor, look here |
| JupyterHub Vienna DS Group | Another hosted JupyterHub project |
| Keycloak blog post | Keycloak and docker-compose |
| Keycloak Medium post | Keycloak running in Docker |
| Traefik Quick Start | This is really all you probably need to get Traefik working |
| Traefik Routing | If you need more details on Traefik, it's probably the routing |