Jupyter Notebooks for the GNSS interferometric reflectometry python package.
- Option I: Use Notebooks with Docker Container
- Step 1: [Install Docker](#Install Docker)
- Step 2: Build Docker Image and Run Container
- Option 1: Use Dockerhub (RECOMMENDED)
- Option 2: [Use git repository with bash script](#Docker Git Bash)
- Option 3: [Use git repository and run manual docker commands](#Docker Git Commands)
- Option II: Use Notebooks with local Python build
Jupyter and Docker Shutdown Process
(most recent update: April 18 2022)
[Update to Most Recent Docker Image](#Update Docker)
See [here](#Docker Git info) for additional helpful commands for containers.
Pick your system and follow instructions on the Docker website.
- Mac - https://docs.docker.com/docker-for-mac/install/
- Windows - https://docs.docker.com/docker-for-windows/install/
- Ubuntu - https://docs.docker.com/install/linux/docker-ce/ubuntu/
Once installed, type docker run hello-world in terminal to check if installed correctly.
More information on getting started, testing your installation, and developing.
Useful tool to use is Docker Desktop
Navigate to the directory where you would like to have output data stored. Note that the code will create a directory called Files where the final data will be stored for you locally. NOTE: If you would like to make your own notebook and keep the changes if you need to remove/update the docker - you can place the notebook in the Files folder.
Then run:
docker run -it -v $(pwd)/Files:/home/jovyan/gnssrefl_jupyter/Files -p 8888:8888 --name='gnssrefl_jupyter' -e GRANT_SUDO=yes --user root --restart=unless-stopped unavdocker/gnssrefl_jupyter:latest
Description of the commands used:
-it: interactive process (shell)-v: external volume. All changes will be reflected on your host computer.-p: publish on port--name: name of docker container-e: granting sudo permissions--user: setting the userreference dockerhub image: This will build the dockerhub image if it doesn't already exist locally.
This will build the docker image and run the container. Once everything has finished building in the terminal, you can copy and paste the last url provided at the end into a browser and run the jupyter notebooks from there.
The url will look something like http://127.0.0.1:8888/?token= with a randomly generated token at the end.
DONE - Below are other options for installation.
For instructions on how to install git on any OS: https://github.com/git-guides/install-git Use the HTTPS link in this repository to clone the repository to your local machine. You may do this in a terminal using git or use a git client (Fork, etc...) You will want to do this in a location on your local computer that you wish to store the repository.
To clone a repository onto your local machine using the HTTPS link, click on the drop down that says 'clone' in the
repository and copy the link that says 'Clone with HTTPS'. Using your terminal, navigate to where you would like to clone
the repository and then run the command git clone [https url]
To get the latest version of master or your own branch, use the git pull command from inside the now-local repository.
This repository includes a shell script that will set up the image and container for you. Then run:
./build_docker.sh
(you may need to give this file executable permission: chmod +x build_docker.sh)
This will build the docker image and run the container. Once everything has finished building in the terminal, you can copy and paste one of the urls provided at th end into a browser and run the jupyter notebooks from there.
The url will look something like http://127.0.0.1:8888/?token= with a randomly generated token at the end.
DONE - Below are other options for installation.
To set up the docker image and container use the following instructions:
Step 1. Clone the Git Repository to your local machine (see above)
Navigate to the directory where the Dockerfile from this repository is stored and run...
docker build --rm -t gnssrefl_jupyter .
Description of the commands used:
--rm: remove temporary images built-t: tag/name the docker image 'gnssrefl_jupyter'.: to build it in current directory
Prior to running the docker, make sure you do not have other jupyter notebooks running on 8888 or else it will not work properly. To open the jupyter notebook directly in the run command...
docker run -it -v $(pwd)/Files:/home/jovyan/gnssrefl_jupyter/Files -p 8888:8888 --name='gnssrefl_jupyter' -e GRANT_SUDO=yes --user root --restart=unless-stopped gnssrefl_jupyter
Description of the commands used:
-it: interactive process (shell)-v: external volume. All changes will be reflected on your host computer.-p: publish on port--name: name of docker container-e: granting sudo permissions--user: setting the userreference docker image
This will build the docker image and run the container. Once everything has finished building in the terminal, you can copy and paste one of the urls provided at th end into a browser and run the jupyter notebooks from there.
The url will look something like http://127.0.0.1:8888/?token= with a randomly generated token at the end.
DONE.
To Shut down the Jupyter notebook from the terminal just use ctrl+c
To shut down the docker container run docker stop [container name]
If you need to see the container(s) you have running you can use docker ps
To update your Image from our DockerHub. Run docker pull unavdocker/gnssrefl_jupyter
Then you will need to launch an updated container.
If your container is running - stop the container (see above).
Then run docker rm [container name]
finally you can re-run the container:
docker run -it -v $(pwd)/Files:/home/jovyan/gnssrefl_jupyter/Files -p 8888:8888 --name='gnssrefl_jupyter' -e GRANT_SUDO=yes --user root --restart=unless-stopped unavdocker/gnssrefl_jupyter:latest
The following are additional docker commands that are optional:
If you want to add your own external volume add another -v command to the docker run command. You can add as many external volumes as you wish. All changes will be reflected on your host computer.
-v ~/[your_host_directory]:/home/jovyan/gnssrefl_jupyter/[personal_directory_name]
If instead you wish to not run the container in the current terminal, then run the container in detached mode. To do this, add a -d to the docker run command...
docker run -it -d -p 8888:8888 --name='gnssrefl_jupyter' -e GRANT_SUDO=yes --user root -v $(pwd)/Files:/home/jovyan/gnssrefl_jupyter/Files --restart=unless-stopped gnssrefl_jupyter
If your container is running and you need to enter the container (such as detached mode), then use the docker exec command to enter the container in a bash shell.
docker exec -it gnssrefl_jupyter /bin/bash
From here you can obtain the token for the Jupyter Notebook by running the command jupyter notebook list to get the link and token to run the notebook in your browser.
If you need to change your docker run command, exit out of jupyter notebook (Control-C), stop, and remove the container before running a new one.
docker stop gnssrefl_jupyter
docker rm gnssrefl_jupyter
If you need to rebuild the image, follow the previous steps to remove the container and then remove the image before trying to rebuild.
docker image rm gnssrefl_jupyter
If you do not wish to use the docker container, then you can run Jupyter notebook using your local Python 3 environment.
NOTE this setup requires system dependencies: gcc and gfortran.
To install:
- if you are using a LINUX then simply run
apt-get install -y gccandapt-get install -y gfortranin your terminal. - if you are using a MacOS then you will need to install xcode. First, in your terminal, check if you have xcode by
xcode-select -p. If it is installed, it should return a path. If it is not installed then runxcode-select --install. This should install gcc.You can check if you have gcc bygcc --version. Check if you have gfortran bygfortran --version. If you do not have gfortran, then follow instructions to install for your system here for MacOS and here for Linux.
If you are still experiencing trouble then it is recommended you try the docker version of these notebooks. See above.
For instructions on how to install git on any OS: https://github.com/git-guides/install-git
Use the HTTPS link in this repository to clone the repository to your local machine. You may do this in a terminal using git or use a git client (Fork, etc...) You will want to do this in a location on your local computer that you wish to store the repository.
To clone a repository onto your local machine using the HTTPS link, click on the drop down that says 'clone' in the
repository and copy the link that says 'Clone with HTTPS'. Using your terminal, navigate to where you would like to clone
the repository and then run the command git clone [https url]
To get the latest version of master or your own branch, use the git pull command from inside the now-local repository.
To install all the required python packages, use pip to install the requirements.txt file. Navigate to the gnssrefl_jupyter directory (where you cloned this repository) that contains the requirements.txt file and run:
pip install -r requirements.txt
*note that depending on your environmnet you may need to use pip3 instead of pip.
run the command jupyter notebook and it should open a local jupyter instance in a browser.
jupyter notebook
The notebook directory is where we store the notebooks for the gnssir use cases.
The bin directory contains all of the executable and importable scripts.
Contains any data or figures needed to generate content for the gnssir notebooks.