├── LICENSE ├── README.md ├── Singularity ├── jupyter.png └── local.png /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 Vanessa Sochat 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Jupyter 2 | 3 | This example will show how to run a jupyter notebook server with nginx, from a container (singularity container in this case). 4 | 5 | - perhaps you ran an analysis when you created the container, and want to serve the notebook as a result) or 6 | - perhaps you want this to be like a working container, to store a particular version of your software to use on local files 7 | 8 | If you are interested in more proper container orchestration with [singularity-compose](https://singularityhub.github.io/singularity-compose/), see the [singularity-compose jupyter example](https://github.com/singularityhub/singularity-compose-examples/tree/master/jupyter-simple) that can more easily handle adding other containers as services, volumes, etc. 9 | 10 | ## Branches 11 | 12 | - [Windows Filesystem Support](https://github.com/singularityhub/jupyter/tree/cifs) A basic example for Windows Filesystem Support is on this cifs branch. 13 | 14 | ## Getting Started 15 | 16 | If you haven't installed singularity, do that with [these instructions](http://singularity.lbl.gov/install-linux). Then download the repo if you haven't already: 17 | 18 | ```bash 19 | git clone https://www.github.com/singularityhub/jupyter 20 | cd jupyter 21 | ``` 22 | 23 | Let's now create a jupyter notebook! 24 | First, we will create the writable container image in a _writable_ *ext3* file system, instead of the *squashfs* which only allows _read-only_. [read more](http://singularity.lbl.gov/docs-build-container) 25 | 26 | ```bash 27 | $ sudo singularity build --sandbox jupyter-box Singularity 28 | ``` 29 | 30 | Then to run our container, since we need to write files to `/opt/notebooks` inside the container, we must use sudo and add the `--writable` command: 31 | 32 | ```bash 33 | $ sudo singularity run --writable jupyter-box 34 | ``` 35 | 36 | When we open the browser, we see our server! Cool! 37 | 38 | ![jupyter.png](jupyter.png) 39 | 40 | **Important** using this container requires the allow-root flag, which isn't great practice. 41 | If you really need to run a notebook in a container, you might be better off building one 42 | that installs the notebook with your user (e.g. see [this Docker example](https://github.com/hpsee/discourse-cluster/blob/master/Dockerfile) that could be translated to Singularity). You would want to change 43 | the user jovyan to your username. If you can, you can also just use Docker! EIther you 44 | can use the image linked there, or you can check out [repo2docker](https://github.com/jupyter/repo2docker) to build 45 | a custom container. 46 | 47 | Since the notebooks are being written to the image, this means that all of our work is preserved in it. I can finish working, close up shop, and hand my image to someone else, and it's preserved. Here, I'll show you. Let's shell into the container after we've shut down the server (note that I didn't need to use sudo for this). 48 | 49 | ```bash 50 | sudo singularity shell jupyter-box 51 | Singularity: Invoking an interactive shell within container... 52 | 53 | Singularity.jupyter.sif> ls /opt/notebooks 54 | Untitled.ipynb 55 | ``` 56 | 57 | There it is! I really should work on naming my files better :) That is so cool. 58 | 59 | You can also map to a folder on your local machine, if you don't want to save the notebooks inside: 60 | 61 | ```bash 62 | sudo singularity run -B $PWD:/opt/notebooks --writable jupyter-box 63 | ``` 64 | 65 | and here I am sitting in my local directory, but the entire software and depdencies are provided by my container. STILL really cool. 66 | 67 | ![local.png](local.png) 68 | ## Note on port forwarding 69 | If you are running Singularity in Windows through vagrant, you will need to configure port forwarding in the Vagrantfile that you use to set up the Singularity container as well. 70 | As an example, you should add a line that might look like this. 71 | `config.vm.network "forwarded_port", guest: 8888, host: 8888, host_ip: "127.0.0.1"` 72 | -------------------------------------------------------------------------------- /Singularity: -------------------------------------------------------------------------------- 1 | BootStrap: docker 2 | From: continuumio/anaconda3 3 | 4 | %runscript 5 | 6 | echo "Starting notebook..." 7 | echo "Open browser to localhost:8888" 8 | exec /opt/conda/bin/jupyter notebook --notebook-dir=/opt/notebooks --ip='*' --port=8888 --no-browser --allow-root 9 | 10 | %post 11 | 12 | # Install jupyter notebook 13 | /opt/conda/bin/conda install jupyter -y --quiet 14 | mkdir /opt/notebooks 15 | apt-get autoremove -y 16 | apt-get clean 17 | -------------------------------------------------------------------------------- /jupyter.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/singularityhub/jupyter/846ee133ba107cc34b9b71066e059f938065664d/jupyter.png -------------------------------------------------------------------------------- /local.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/singularityhub/jupyter/846ee133ba107cc34b9b71066e059f938065664d/local.png --------------------------------------------------------------------------------