Repository: kleinee/jns Branch: master Commit: 812630a83e7e Files: 19 Total size: 55.2 KB Directory structure: gitextract_6e2ihkt7/ ├── CHANGELOG.md ├── LICENSE.md ├── README.md └── scripts/ ├── conf_jupyter.sh ├── conf_service.sh ├── dnld_julia-1.1.0-arm32bit.py ├── inst_R-3.6.0.sh ├── inst_jns.sh ├── inst_julia-0.6.0.sh ├── inst_julia-1.1.0.sh ├── inst_julia.sh ├── inst_lab_ext.sh ├── inst_opencv.sh ├── inst_pi_hardware.sh ├── inst_sqlite.sh ├── inst_stack.sh ├── inst_tex.sh ├── prep.sh └── requirements.txt ================================================ FILE CONTENTS ================================================ ================================================ FILE: CHANGELOG.md ================================================ # 24 December 2019 * With Satoshi Teraski's instructions it is possible to get Julia 1.3.0 / IJulia working on Raspberry Pis with ARM v6 CPU * His repository can be found [here](https://github.com/Julia-Embedded/jlcross). * Response to [issue #21](https://github.com/Julia-Embedded/jlcross/issues/21) outlines the workaround to get IJulia working. * The IJulia installtion workaround should also work with other Julia versions including 1.0.3, the version that can be apt installed on Raspbian Buster # 23 December 2019 * If we exclude Julia for a moment, the setup works fine on Buster as well. * But when it comes to Julia, it is getting trickier and trickier to support ARM v6 based Raspberry Pi boards as official ARM v6 Julia binaries do no longer exist. Whilst Terasaki Satoshi cross-compiled several Julia versions including 1.3.0 using Docker and his binaries work fine, I cannot get IJulia to work with any of them on ARM v6. IJulia builds ok but the resulting kernels die. The same by the way happens with apt-get installed Julia. I searched the web intensively without finding a solution. If you do, kindly get in touch. Thanks & Merry Christmas! # 1 June 2019 * added R-3.6.0 + IRkernel installer * added Julia-1.1.0 + IJulia installer * commented out a couple of optional installs in inst_jns.sh * updated requierments.txt * updated README.md - may still require some tweaks. Will attendd to it again as I find the time # 11 May 2019 * updated requirements * removed line sqlite3-kernel==1.0 from requirements as the kernel is pulled from GitHub * this fixes issue #34 raised by #chalgand # 20 April 2019 * updated requirements as GitHub urllib3 < 1.24.2 to be vulnerable # 6 April 2019 * updated requirements * added a line to inst_labextensions.sh to use ipyleaflet in lab * updated README.md accordingly # 3 April 2019 * updated requirements as GitHub reported the notebook verions < 5.7,9 to be vulnerable # 31 March 2019 * updated requirements # 23 March 2019 * updated requirements # 12 March 2019 * corrected inst_lab_ext.sh as the line that activates the environment. This fixes issue #33 filed by @dwblair. Thanks for reporting this Don! # 9 March 2019 * updated requirements # 6 March 2019 * downgraded tornado to 5.1.1 to fix issue #32 as suggested by @Kevin--R - Thanks Kevin! # 4 March 2019 * updated requirements.txt again * quite a challenge to keep up with the pace of the python community # 3 March 2019 * updated requirements * was notified by GitHub in PyYAML before 4.1, the yaml.load() API could execute arbitrary code. In other words, yaml.safe_load is not used. * updated PyYAML # 30 January 2019 * updated requirements.txt * downgraded vega to version 1.4 to resolve issue #31 * credits go to @jakevdp who made this suggestion # 20 December 2018 * updated requirements # 27 November 2018 * updated requirements * fixed inst_opencv.sh as suggested by @mt08 * corrected README.md accordingly # 10 November 2018 * updated requirements # 27 October 2018 * updated requirements # 20 October 2018 * updated requirements # 15 October 2018 * updated requirements # 6 October 2018 * updated requirements # 4 October 2018 * updated requirements * both ipython and jupyter-console are now compatible with prompt-toolkit 2.0.5 * merged 2 pull requests from @bennuttall - THANKS BEN! # 1 October 2018 * added tensorflow * updated requirements # 23 September 2018 * updated requirements * modified conf_jupyter.sh to fix issue #26 by setting ```c.NotebookApp.allow_remote_access = True``` in the configuration file located at ```~/.jupyter/jupyter_notebook_config.py```. In existing installtions just edit the configuration file manually # 15 September 2018 * updated requirements * simpified requirements using pipdeptree -f --warn silence | grep -P '^[\w0-9\-=.]+' # 14 Septmber 2018 * updated requirements.txt ======= # 13 September 2018 * created new branch dev * shifted bash scripts into `scripts` folder * adjusted `README.md' accordingly >>>>>>> create dev branch # 12 September 2018 * updated requirements * removed service.sh as it is renamed to conf_servivice.sh # 9 September 2018 * installed from scratch on a Raspberry Pi 3 and in the process made some fixes * updated requirements # 28 August 2018 * updated requirements * made minor corrections to README.md # 18 August 2018 * updated requirements # 12 August 2018 * updated requirements * added SQLite3 kernel installation script * correted prep.sh - thanks mt08xx * adopted mt08xx's nice solution to start the server as a service # 7 August 2018 * updated requirements # 31 July 2018 * updated requirements # 20 July 2018 * upgated requirements # 8 July 2018 * updated requirements * added snowballstemmer back in # 1 July 2018 * updated requirements # 12 June 2018 * updated requirements # 3 June 2018 * made minor changes to `README.md` * added dependencies for `python-opencv-headless` to `prep.sh` * updated requirements # 1 June 2018 * fixed typo in `README.md` * closed issue # 23 * updated requirements # 31 May 2018 * removed `inst_node.sh`, modified ```conf_jupyter.sh` and added `inst_lab_ext.sh` as proposad by @Kevin--R to address issue #23 - Thanks Kevin! * modified `README.md` to refelct the changes above # 26 May 2018 * updated requirements * corrected a typo # 21 May 2018 * Thanks to comments received form @Kevin--R issue 22 should now be fixed # 20 May 2018 * ***fixed further issue*** buy modifying ```inst_node.sh``` - see issue #22 * ***fixed issue 22*** by modifying ```conf_jupyter.sh``` in accordance with a hint found [here](https://stackoverflow.com/questions/43659084/source-bashrc-in-a-script-not-working). * if you encountered this issue, please run the modified version of ```conf_jupyter.sh``` # 19 May 2018 * updated requirements # 5 May 2018 * updated requirements * added altair + vega_datasets - see https://altair-viz.github.io/index.html for details # 25 April 2018 * updated requirements # 17 April 2018 * updated requirements * removed `format = 'legacy'` in README.md because it is deprecated in the latest version of `pip` * temporarily removed the altair package from requirements.txt due to incompatibility # 09 April 2018 * closed issue #21 # 07 April 2018 * updated requirements * fixed typo in README.md - thanks for reporting it @m-r-white * ran a fresh install based on the DESKTOP version of Raspbian Stretch to fix issue #21 opened by @gusdrawn and independently confirmed by @m-r-white (Thanks to both!) and updated `README.md` and `conf_jupyter` to clarify what possibly went wrong in their installations. The short answer: `nodejs 5+` is required for `conf_jupyter.sh` to run properly. # 01 April 2018 * updated requirements # 27 March 2018 * updated requirements * in the wake of recent abuse of datascience tools: ***DO NO EVIL!*** # 19 March 2018 * updated ```requiremnets``` * fixed ```inst_julia.sh``` # 15 March 2018 * added note to the end of ```README.md``` on how to stop the server if launched on boot # 14 March 2018 * closed issue #17 * added the solution as an option to ```README.md``` as this might be useful to some # 12 March 2018 * removed necessity to reboot after changing ```swap_size``` by stopping and starting the service * updated ```requirements``` # 11 March 2018 * closed issues #15 and #16 * issue #15 is personal preference - I may pick up on this at a later stage * issue #16 is fixed by installing ```nodejs``` with a separate script. For further info please refer to the issue itself * cut down Julia installation as the JuliaBerry packages lead to segmentation faults * simplified TeX installtion as suggested in the documentation of ```nbconvert``` # 22 February 2018 * updated requirements * manually installed the bokeh jupyter lab extension for testing by running: ```jupyter labextension install jupyterlab_bokeh``` Took some time to build but seems to work fine # 21 Febuary 2017 * updated requirements # 17 February 2017 * updated requirements * it is really amazing how quickly updated packages become available on piwheels... # 14 February 2018 * HAPPY VALENTINE'S DAY * updated requirements # 10 February 2018 * updated requirements * if you installed prior to this update, just run: ```bash source /home/pi/.venv/jns/bin/activate pip list --outdated --format='legacy' pip install -U package1 package2... ``` where ```package1 package2...``` is a list of package names of the packages you want to update # 26 January 2018 * added support for Sphinx for new installations * in case you want to add this manually because you already have a working jns installation just run: ```bash sudo apt install latexmk source ~/.venv/jns/bin/activate pip3 install Sphinx docutils ``` # 24 January 2018 * corrected `inst_jns.sh` and corresponding entry in `README.md` # 22 January 2018 * set size of swap_file to 2048MB # 21 January 2018 * modified `conf_jupyter.sh`in order to facilitate use of `ipywidgets` and `bqplot` in JupyterLab # 20 January 2018 * new version on GitHub # 15 January 2018 ## IMPORTANT NOTIFICATION: I plan to release a new version of jns within this week ***KEY CHANGES*** * Rather than installing the latest version of Python, the new version will use the latest Python 3 version supported in Raspbian - as of this writing Python 3.5.3. * Whilst this seems to be a step backwards, it is a in fact a giant step forward as we benefit from significant installation speedups made possible by the recently released ***piwheels*** project. * The scripts will work across the entire range of Raspberry Pis - perhaps with the exception of the early models with just 256MB of memory - I tested Pi 1, 2, 3 and ZeroW. * The new version provides Python support for gpio, sensehat and picamera without the worries of breaking things on the system level as all Python modules will be pip installed into a virtual environment using a requirements.txt file. * This achieves a more maintainable setup and opens up more possibilities. * Pyhon 3, Julia and Bash kernels will be installed and configured. R, Ruby and Octave kernels are likely to follow as I find the time. * JupyterLab will be installed and ready to use. ================================================ FILE: LICENSE.md ================================================ The MIT License (MIT) Copyright (c) 2015,2016,2017,2018 Eckhard Kleine Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ [![hardware](https://img.shields.io/badge/hardware-Raspberry_Pi-red.svg)](https://www.raspberrypi.org/products/) [![os](https://img.shields.io/badge/OS-Raspbian_Stretch_Lite-red.svg)](https://www.raspberrypi.org/downloads/raspbian/) ![python](https://img.shields.io/badge/python-3.5.3-yellow.svg) ![nodejs](https://img.shields.io/badge/nodejs-v8.11.4-green.svg) ![Julia](https://img.shields.io/badge/julia-v1.1.0-magenta.svg) ![R](https://img.shields.io/badge/R-v3.6.0-blue.svg) [![jupyter](https://img.shields.io/badge/more_info-jupyter-black.svg)](http://jupyter.org) [![piwheels](https://img.shields.io/badge/more_info-piwheels-black.svg)](https://www.piwheels.org) # Jupyter Notebook & Lab Server on Raspberry Pi ## Intro [Project Jupyter](https://jupyter.org) not only revolutionizes data-heavy research across domains - it also boosts personal productivity for problems on a much smaller scale. Due to openness it is an amazing platform for exploring concepts and learning new things. I started setting up a Jupyter Notebook Server on a [Raspberry Pi](https://www.raspberrypi.org) following [this blog post](https://arundurvasula.wordpress.com/2014/04/01/remote-ipython-notebook-with-raspberry-pi/) by Arun Durvasula. Convinced of the potential of the platform I followed the development. My personal exercise soon taught me a great deal about the underlying architcture. Given Jupyter's complexity, speed of growth and scale, it is remarkable that such a system runs fine on a Raspberry Pi. This repository isn't really anything genuine: I owe big thanks to many contributors in the Jupyter, Raspberry Pi, Linux, Python, Julia and greater Open Source communities for providing all the beautiful building blocks - small and large. ### What is new? * Rather than installing the latest version of Python as I did the past, I decided that the new version would use the latest Python 3 version supported in Raspbian - as of this writing Python 3.5.3. * Whilst this seems to be a step backwards, it is a in fact a giant step forward as you benefit from significant installation speedups made possible by the recently released [piwheels](https://www.piwheels.org) project. * The scripts work across the entire range of Raspberry Pis - including the early models with just 256MB of memory. * Python support for GPIO, Sense HAT and PICAMERA is installed without the earlier worries of breaking things on system level. * All Python modules are pip installed into a virtual environment following advice found online: ***You should never use `sudo pip install` -NEVER***. Well I did this in the past and it certainly had me and users confused. We have to learn certain things the hard way to really appreciate the benefits of doing them right. It is worth reading up on this in [this blogpost](http://jakevdp.github.io/blog/2017/12/05/installing-python-packages-from-jupyter/). * You now install Python packages into a virtual environment created with `venv` using a `requirements.txt` file. This really achieves a more maintainable setup, opens up more possibilities and hopefully makes this project more useful for the Raspberry Pi and Jupyter communities. * Python 3, Julia and Bash kernels are installed and configured during installation. * JupyterLab is installed and ready to use. ## What do you need to follow along? * a ***Raspberry Pi model of your choice*** complete with micro-usb power-supply - I recommend a Raspberry Pi 3 but the setup should work across the entire range of Pi models, perhaps with the exception of the very early models that featured only 256MB of memory. I tested on a ZeroW, 1, 2 and 3. * a (micro) SD card with 16GB capacity or more to suit your Pi model with [Raspbian Stretch Lite](https://www.raspberrypi.org/downloads/raspbian/) installed and configured to permit access via ssh as user ***pi***. * an ethernet or wifi connection for the Pi * internet access on the Pi * a computer to carry out the installation connected to the same network as the Pi * ***LESS TIME THAN EVER BEFORE*** due to the recent release of [piwheels](https://www.piwheels.org). Users new to this project might argue that the setup is still time-consuming. Believe me: In the past 6 hours+ were not uncommon and installing the system on a Raspberry Pi 1 was not impossible but required quite some patience and time. Note that some packages listed in `requirements.txt` may not yet be available as Python wheels. Such packages are then built from source and this takes some time... ## Installation ### IMPORTANT NOTE on fresh installations * An increasing number of users seem to install on top of images that have 'nodejs' already installed. * The scripts in this repository were initially designed to work based on ***Raspbian Stretch Lite*** as a starting point with the intention to run the server headless in order to maximise memory available for data analysis. * One such starting point is the desktop version of ***Raspbian Stretch*** which comes with`nodejs` (and `git`) pre-installed. `conf_jupyter.sh` explained later now checks for the existence of `node` and only installs it if not yet present on the system. * ***For the scripts to run properly on the desktop version of Raspbian or any other startingpoint with `node` installed, it is necessary that `node` is version 5 or higher !!!*** * If you start with a fresh Raspbian Stretch Desktop image, you can uninstall `node` using `apt purge nodejs` and then execute the scripts. ### First boot with fresh SD card * ssh into your Raspberry Pi with the the fresh install of Raspbian Stretch Lite as user ***pi***. Then run `sudo raspi-config` and set the memory split to 16MB, expand the file-system and set a new password for the user pi. When done, reboot and log in again via ssh. * If not yet present, install `git`: ```bash sudo apt install -y git ``` * To increase the size of swap_file to 2048MB run: ```bash sudo sed -i -e 's/CONF_SWAPSIZE=100/CONF_SWAPSIZE=2048/' /etc/dphys-swapfile sudo /etc/init.d/dphys-swapfile stop sudo /etc/init.d/dphys-swapfile start ``` * With preparations out of the way clone this repository into the home directory of user ***pi*** ```bash git clone https://github.com/kleinee/jns ``` * Change into the new directory `~/jns/scripts` just created with `git`: ```bash cd ~/jns/scripts ``` Technically you can now run `sudo ./inst_jns.sh` which is the installer script that combines the steps described below. If you follow along I assume that you run all scripts from inside the directory `~/jns/scripts`. You might not want all features on your system. Feel free to edit `inst_jns.sh' to suit your requirements. ## Install required Raspbian packages with apt ```bash sudo ./prep.sh ``` A couple of packages from the Raspbian repository are required during installation and later for a some Python packages to work properly. The script just fetches these packages and installs them. ```bash #!/bin/bash # script name: prep.sh # last modified: 2018/09/09 # sudo: yes script_name=$(basename -- "$0") if ! [ $(id -u) = 0 ]; then echo "usage: sudo ./$script_name" exit 1 fi apt update && apt -y upgrade apt -y install pandoc apt -y install libxml2-dev libxslt-dev apt -y install libblas-dev liblapack-dev apt -y install libatlas-base-dev gfortran apt -y install libtiff5-dev libjpeg62-turbo-dev apt -y install zlib1g-dev libfreetype6-dev liblcms2-dev apt -y install libwebp-dev tcl8.5-dev tk8.5-dev apt -y install libharfbuzz-dev libfribidi-dev apt -y install libhdf5-dev apt -y install libnetcdf-dev apt -y install python3-pip apt -y install python3-venv apt -y install libzmq3-dev apt -y install sqlite3 ``` ## Install required Python 3 packages with pip ```bash ./inst_stack.sh ``` * This creates a virtual Python 3 environment '/home/pi/.venv/jns' and activates it temporarily * It then updates `pip3` to the latest version available from the Python package repository before it processes the `requirements.txt` file line by line. * This is a workaround to prevent `pip` from failing if one or more requirements listed fail to install. ```bash #!/bin/bash # script name: inst_stack.sh # last modified: 2018/01/14 # sudo: no script_name=$(basename -- "$0") env="/home/pi/.venv/jns" if [ $(id -u) = 0 ] then echo "usage: ./$script_name" exit 1 fi if [ ! -d "$venv" ]; then python3 -m venv $env fi # activate virtual environment source $env/bin/activate pip3 install pip==9.0.0 pip3 install setuptools pip3 install -U pip cat requirements.txt | xargs -n 1 pip3 install ``` ## Configure Jupyter ```bash ./conf_jupyter.sh ``` With this script you generate a jupyter notebook configuration directory and in it a file called `jupyter_notebook_config.py` that holds the configuration settings for your notebook / lab server. You also create a folder notebooks in the home directory of user `pi` as the `notebook_dir` for your server. In the configuration file, you apply the following changes: * tell jupyter not to sart a browser upon start - we access the server from a remote machine on the same network * set the IP address to '*' * set the port for the notebook server to listen to 8888 * enable `mathjax` for rendering math in notebooks * set the notebook_dir to `~/notebooks` * use the password hash for the default server password `jns` NOTE: This setup still uses password authentication. If you prefer token-based authentication, you have to change settings in the config file `/home/pi/.jupyter/jupyter_notebook_config.py`. Documentation of possible configuration settings can be found [here](https://jupyter-notebook.readthedocs.io/en/stable/index.html). After the basic configuration the script activates the bash kernel and activates extensions for Jupyter Notebook and JupyterLab. At the JupyterLab end this requires intstallation of `node` followed by installation of the underlying JS infrastructure which is a bit time-consuming but ultimately allows you to use `ipywidgets`, `bqplot` and potentially other extensions. ```bash #!/bin/bash # script name: conf_jupyter.sh # last modified: 2018/09/09 # sudo: no script_name=$(basename -- "$0") env="/home/pi/.venv/jns" if [ $(id -u) = 0 ] then echo "usage: ./$script_name" exit 1 fi # activate virtual environment source $env/bin/activate # generate config and create notebook directory # if notebook directory exists, we keep it (-p) # if configuration file exeists, we overwrite it (-y) jupyter notebook -y --generate-config cd $home mkdir -p notebooks target=~/.jupyter/jupyter_notebook_config.py # set up dictionary of changes for jupyter_config.py declare -A arr app='c.NotebookApp' arr+=(["$app.open_browser"]="$app.open_browser = False") arr+=(["$app.ip"]="$app.ip ='*'") arr+=(["$app.port"]="$app.port = 8888") arr+=(["$app.enable_mathjax"]="$app.enable_mathjax = True") arr+=(["$app.notebook_dir"]="$app.notebook_dir = '/home/pi/notebooks'") arr+=(["$app.password"]="$app.password = 'sha1:5815fb7ca805:f09ed218dfcc908acb3e29c3b697079fea37486a'") # apply changes to jupyter_notebook_config.py for key in ${!arr[@]};do if grep -qF $key ${target}; then # key found -> replace line sed -i "/${key}/c ${arr[${key}]}" $target else # key not found -> append line echo "${arr[${key}]}" >> $target fi done # install bash kernel python3 -m bash_kernel.install # install extensions jupyter serverextension enable --py jupyterlab jupyter nbextension enable --py widgetsnbextension --sys-prefix jupyter nbextension enable --py --sys-prefix bqplot # activate clusters tab in notebook interface /home/pi/.venv/jns/bin/ipcluster nbextension enable --user # install nodejs and node version manager n # if node is not yet installed if which node > /dev/null then echo "node is installed, skipping..." else # install nodejs and node version manager n cd ~/jns # fix for issue #22 # install nodejs and node version manager n # see: https://github.com/mklement0/n-install curl -L https://git.io/n-install | bash -s -- -y lts fi # install jupyter lab extensions bash -i ./inst_lab_ext.sh ``` The script ```inst_lab_ext.sh``` - introduced by @Kevin--R to fix issue#23 has the following content: ```bash #!/bin/bash # script name: inst_lab_ext.sh # last modified: 2019/04/06 # sudo: no script_name=$(basename -- "$0") env="/home/pi/.venv/jns" if [ $(id -u) = 0 ] then echo "usage: ./$script_name" exit 1 fi . /home/pi/.bashrc . $env/bin/activate jupyter lab clean jupyter labextension install @jupyter-widgets/jupyterlab-manager --no-build jupyter labextension install bqplot --no-build jupyter labextension install jupyterlab_bokeh --no-build jupyter labextension install jupyter-leaflet --no-build jupyter lab build ``` ## Start and access your server ### Activate the virtual environment Since you used a virtual environment to install Python modules, you need to activate this environment before you can start your server: ```bash source /home/pi/.venv/jns/bin/activate ``` The prompt will change to indicate successfull activation preceding `pi@hostname:` with the envireonment name - in case pf this setup `(jns)`. With hostname set to `zerow` it looks like this: ```bash (jns) pi@zerow:~ $ ``` ### Before you proceed After installation completes, you will still need to activate the change made to `~\.bashrc` when node was installed before doing anything that requires node. You can be accomplish this by any of the following: - reboot - logout and log back in - call `. ~/.bashrc` from the command line That's the reason for this warning during node installation: ``` IMPORTANT: OPEN A NEW TERMINAL TAB/WINDOW or run `. /home/pi/.bashrc` before using n and Node.js. ``` You can see this by running the following commands after your installation completes: ```bash pi@test-pi:~/jns $ echo $PATH /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/games:/usr/games pi@test-pi:~/jns $ . ~/.bashrc pi@test-pi:~/jns $ echo $PATH /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/games:/usr/games:/home/pi/n/bin pi@test-pi:~/jns $ ``` If you look at your **$PATH** environment variable and see **/home/pi/n/bin** you are ready to use node. Also note that if you uninstall node with `n-uninstall` **/home/pi/n/bin** will remain in your **$PATH** environment variable until you reboot or logout and log back in. ### Start the server To start your server just type `jupyter notebook` or `jupyter lab` ### Access the server To access your server form a webbrowser on a computer running on the same network as your Raspberry Pi, just open a browser and use the Pi's IP address / port 8888 as the url. ```bash xxx.xxx.xxx.xxx:8888 ``` Change `xxx.xxx.xxx.xxx' to the IP address of the Raspberry Pi. ### Login During the configuration the default password for the server was set to `jns`. You can change this by typing: ```bash (jns) pi@zerow:~ $ jupyter notebook password Enter password: **** Verify password: **** ``` ## Install TeX (optional) ```bash sudo ./inst_tex.sh ``` * [TeX](https://en.wikipedia.org/wiki/TeX) (and [Pandoc](http://pandoc.org)) are used under the hood to convert Jupyter notebooks to other formats including PDF. * Whilst not strictly necessary if no PDF export is rquired, I still recommend to run this step. ```bash #!/bin/bash # script name: inst_tex.sh # last modified: 2018/03/11 # sudo: yes script_name=$(basename -- "$0") if ! [ $(id -u) = 0 ]; then echo "usage: sudo ./$script_name" exit 1 fi #------------------------------------------------------ apt install -y texlive-xetex apt install -y latexmk #------------------------------------------------------ ``` ## Install Julia and the IJulia kernel (optional) * [Julia](https://julialang.org) is a relatively new high-level, high-performance dynamic programming language for numerical computing trying to combine the ease of Python with the speed of C. Thanks to the efforts of the Raspberry Pi community `Julia 0.6.0` is available in the Raspbian Stretch Repository. It is really worth a try as the language is a rising star in scientific computing. * [IJulia](https://github.com/JuliaLang/IJulia.jl) is the kernel required for Jupyter Notebook / JupyterLab. Backgroud information on Julia on the Raspberry Pi can be found [here](https://www.raspberrypi.org/blog/julia-language-raspberry-pi/). ### Alternative 1: Julia 1.1.0 (RECOMMENDED) ```bash sudo ./inst_julia-1.1.0.sh ``` * ***NOTE*** tha the installer assumes that *** Julia IS NOT yet installed***. If it is and you want to proceed with installing Julia-1.1.0, I suggest to remove the existing Julia installation before you proceed. * ```Julia 1.1.0``` binaries were cross-compiled by Mr Satoshi Terasaki (for more information follow [this link](https://gist.github.com/terasakisatoshi/3f8a55391b1fc22a5db4a43da8d92c98)) and Mr Satoshi thankfully hosts his binaries [here](https://drive.google.com/file/d/1fj6pNAJgmUD7bsSXqh8ocC1wESx8jkRh/view). * We need to download a large file from Google Drive and need to install the right binary based on the CPU architecture. The download contains binaries for both architectures. #### The Download Helper As per comments in the script this is literally a 1:1 copy of code found on stack overflow - adjustments were only necessary to set the ***FILE_ID*** and the ***DESTINATION*** as required in the context of this repository. The helper is called by the installer script and is not meant to be exceuted manually. ```Python #!/home/pi/.venv/jns/bin/python # # last modified 2019/05/26 # # Python helper script to download Julia 1.1.0 binaries # not meant to be executed manually # https://stackoverflow.com/questions/38511444/python-download-files-from-google-drive-using-url # FILE_ID = '1fj6pNAJgmUD7bsSXqh8ocC1wESx8jkRh' DESTINATION = './julia-1.1.0-arm32bit.zip' import requests def download_file_from_google_drive(id, destination): URL = "https://docs.google.com/uc?export=download" session = requests.Session() response = session.get(URL, params = { 'id' : id }, stream = True) token = get_confirm_token(response) if token: params = { 'id' : id, 'confirm' : token } response = session.get(URL, params = params, stream = True) save_response_content(response, destination) def get_confirm_token(response): for key, value in response.cookies.items(): if key.startswith('download_warning'): return value return None def save_response_content(response, destination): CHUNK_SIZE = 32768 with open(destination, "wb") as f: for chunk in response.iter_content(CHUNK_SIZE): if chunk: # filter out keep-alive new chunks f.write(chunk) if __name__ == "__main__": file_id = FILE_ID destination = DESTINATION download_file_from_google_drive(file_id, destination) ``` #### The Installer Note that the code assumes that julia is not present. * installs necessary dependencies as suggested by Mr Terasaki * uses the downlaod helper to downlaod his binaries * detects the CPU architecture and installs the matching julia binary * creates a soft link in ```/usr/local/bin``` * installs the the IJulia kernel ```bash #!/bin/bash # script name: inst_julia-1.1.0.sh # last modified: 2019/05/26 # sudo: yes SCRIPT_NAME=$(basename -- "$0") JNS_USER='pi' HOME_DIR="/home/$JNS_USER" ENV="$HOME_DIR/.venv/jns" JULIA_HOME=$HOME_DIR/julia/ if ! [ $(id -u) = 0 ]; then echo "usage: sudo ./$SCRIPT_NAME" exit 1 fi # # apt install dependencies # apt install -y build-essential apt install -y libatomic1 apt install -y gfortran apt install -y perl apt install -y wget apt install -y m4 apt install -y cmake apt install -y pkg-config apt install -y libopenblas-base libopenblas-dev apt install -y libatlas3-base libatlas-base-dev apt install -y liblapack-dev apt install -y libmpfr-dev libgmp3-dev apt install -y libgfortran3 # # download and install julia based on architecture # su pi < /home/pi/jupyter_start.sh && chmod a+x /home/pi/jupyter_start.sh #!/bin/bash . /home/pi/.venv/jns/bin/activate jupyter lab #jupyter notebook ONE cat << 'TWO' | sudo tee /etc/systemd/system/jupyter.service [Unit] Description=Jupyter [Service] Type=simple ExecStart=/home/pi/jupyter_start.sh User=pi Group=pi WorkingDirectory=/home/pi/notebooks Restart=always RestartSec=10 [Install] WantedBy=multi-user.target TWO # start jupyter systemctl daemon-reload systemctl start jupyter systemctl enable jupyter ``` * Next time you boot your Pi, the service is stared automatically. * To stop the service for system updates run: ```bash sudo systemctl stop jupyter ``` ## Put it all together This script is just convenience - it executes the individual steps described above in the order necessary. Note that installation of additinal languages and their respective kernels as well as installtion of opnencv is deactivated by default as not all users may need this functionality. I recommend to run ```inst_jns.sh``` as is and install additional functionality using the individual scripts. + inst_sqlite.sh + inst_R-3.6.0.sh + inst_julia-0.6.0.sh + inst_julia-1.1.0.sh ```bash #!/bin/bash # script name: inst_jns.sh # last modified: 2019/05/26 # sudo: yes script_name=$(basename -- "$0") if ! [ $(id -u) = 0 ]; then echo "usage: sudo ./$script_name" exit 1 fi #----------------------------------------------- # MANDATORY #----------------------------------------------- # make necessary preparations ./prep.sh # install Python packages sudo -u pi ./inst_stack.sh # configure server sudo -u pi ./conf_jupyter.sh #----------------------------------------------- # OPTIONAL, RECOMMENDED #----------------------------------------------- # install TeX ./inst_tex.sh # install support for Pi hardware sudo -u pi ./inst_pi_hardware.sh # set up service to start the server on boot ./conf_service.sh #----------------------------------------------- # OPTIONAL, DISABLED BY DEFAULT #----------------------------------------------- # install Julia 0.6.0 and the IJulia kernel NOT RECOMMENDED # ./inst_julia-0.6.0.sh # install Julia 1.1.0 and the IJulia kernel # ./inst_julia-1.1.0.sh # install R 3.6.0 and the IRkernel # ./inst_R-3.6.0.sh # install the SQLite3 kernel # sudo -u pi ./inst_sqlite.sh # install opencv # ./inst_opencv.sh ``` ## Keep your installation up to date ### Raspbian operating system * just run `sudo apt update && sudo apt -y upgrade` ### Python 3 packages * activate the virtual environment with `source /home/pi/.venv/jns/bin/activate` * list outdated packages with `pip3 list --outdated` * Update `package` with `pip3 install -U package` where `package` is the name of package you want to update. ================================================ FILE: scripts/conf_jupyter.sh ================================================ #!/bin/bash # script name: conf_jupyter.sh # last modified: 2018/09/23 # sudo: no script_name=$(basename -- "$0") env="/home/pi/.venv/jns" if [ $(id -u) = 0 ] then echo "usage: ./$script_name" exit 1 fi # activate virtual environment source $env/bin/activate # generate config and create notebook directory # if notebook directory exists, we keep it (-p) # if configuration file exeists, we overwrite it (-y) jupyter notebook -y --generate-config cd $home mkdir -p notebooks target=~/.jupyter/jupyter_notebook_config.py # set up dictionary of changes for jupyter_config.py declare -A arr app='c.NotebookApp' arr+=(["$app.open_browser"]="$app.open_browser = False") arr+=(["$app.ip"]="$app.ip ='*'") arr+=(["$app.port"]="$app.port = 8888") arr+=(["$app.enable_mathjax"]="$app.enable_mathjax = True") arr+=(["$app.notebook_dir"]="$app.notebook_dir = '/home/pi/notebooks'") arr+=(["$app.password"]="$app.password = 'sha1:5815fb7ca805:f09ed218dfcc908acb3e29c3b697079fea37486a'") arr+=(["$app.allow_remote_access"]="$app.allow_remote_access = True") # apply changes to jupyter_notebook_config.py for key in ${!arr[@]};do if grep -qF $key ${target}; then # key found -> replace line sed -i "/${key}/c ${arr[${key}]}" $target else # key not found -> append line echo "${arr[${key}]}" >> $target fi done # install bash kernel python3 -m bash_kernel.install # install extensions jupyter serverextension enable --py jupyterlab jupyter nbextension enable --py widgetsnbextension --sys-prefix jupyter nbextension enable --py --sys-prefix bqplot # activate clusters tab in notebook interface /home/pi/.venv/jns/bin/ipcluster nbextension enable --user # install nodejs and node version manager n # if node is not yet installed if which node > /dev/null then echo "node is installed, skipping..." else # install nodejs and node version manager n cd ~/jns # fix for issue #22 # install nodejs and node version manager n # see: https://github.com/mklement0/n-install curl -L https://git.io/n-install | bash -s -- -y lts fi # install jupyter lab extensions bash -i ./inst_lab_ext.sh ================================================ FILE: scripts/conf_service.sh ================================================ #!/bin/bash # script name: conf_service.sh # last modified: 2018/08/12 # credits: mt08xx # sudo: yes script_name=$(basename -- "$0") if ! [ $(id -u) = 0 ]; then echo "usage: sudo ./$script_name" exit 1 fi # create jupyter.sh in /home/pi and make it executable cat << 'ONE' > /home/pi/jupyter_start.sh && chmod a+x /home/pi/jupyter_start.sh #!/bin/bash . /home/pi/.venv/jns/bin/activate jupyter lab #jupyter notebook ONE cat << 'TWO' | sudo tee /etc/systemd/system/jupyter.service [Unit] Description=Jupyter [Service] Type=simple ExecStart=/home/pi/jupyter_start.sh User=pi Group=pi WorkingDirectory=/home/pi/notebooks Restart=always RestartSec=10 [Install] WantedBy=multi-user.target TWO # start jupyter systemctl daemon-reload systemctl start jupyter systemctl enable jupyter ================================================ FILE: scripts/dnld_julia-1.1.0-arm32bit.py ================================================ #!/home/pi/.venv/jns/bin/python # # last modified 2019/05/26 # # Python helper script to download Julia 1.1.0 binaries # not meant to be executed manually # https://stackoverflow.com/questions/38511444/python-download-files-from-google-drive-using-url # FILE_ID = '1fj6pNAJgmUD7bsSXqh8ocC1wESx8jkRh' DESTINATION = './julia-1.1.0-arm32bit.zip' import requests def download_file_from_google_drive(id, destination): URL = "https://docs.google.com/uc?export=download" session = requests.Session() response = session.get(URL, params = { 'id' : id }, stream = True) token = get_confirm_token(response) if token: params = { 'id' : id, 'confirm' : token } response = session.get(URL, params = params, stream = True) save_response_content(response, destination) def get_confirm_token(response): for key, value in response.cookies.items(): if key.startswith('download_warning'): return value return None def save_response_content(response, destination): CHUNK_SIZE = 32768 with open(destination, "wb") as f: for chunk in response.iter_content(CHUNK_SIZE): if chunk: # filter out keep-alive new chunks f.write(chunk) if __name__ == "__main__": file_id = FILE_ID destination = DESTINATION download_file_from_google_drive(file_id, destination) ================================================ FILE: scripts/inst_R-3.6.0.sh ================================================ #!/bin/bash # script name: inst_R-3.6.0.sh # last modified: 2019/05/19 # sudo: yes SCRIPT_NAME=$(basename -- "$0") JNS_USER='pi' HOME_DIR="/home/$JNS_USER" ENV="$HOME_DIR/.venv/jns" R_VERSION="R-3.6.0" R_DOWNLOAD_URL="http://mirrors.psu.ac.th/pub/cran/src/base/R-3/$R_VERSION.tar.gz" R_EXEC=$(which R) R_HOME="$HOME_DIR/R" if ! [ $(id -u) = 0 ]; then echo "usage: sudo ./$SCRIPT_NAME" exit 1 fi cd $HOME_DIR # # apt install additional packages # apt install -y libreadline-dev apt install -y libbz2-dev # # download R source and compile # if R is not yet present # su pi <