From c70e2658bec948357b21c5cf187dbe602930a574 Mon Sep 17 00:00:00 2001 From: Miquel Garcia Date: Wed, 6 Aug 2025 19:14:33 +0200 Subject: [PATCH 1/2] Add guide to run tutorials using a Jupyter Docker image --- tutorials/README.md | 108 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 100 insertions(+), 8 deletions(-) diff --git a/tutorials/README.md b/tutorials/README.md index 76307606..8634b69f 100644 --- a/tutorials/README.md +++ b/tutorials/README.md @@ -6,22 +6,22 @@ These tutorials were designed with the goal of building intution and introduce s ### Setup using conda -1. Check that you have [conda](https://docs.conda.io/en/latest/) installed. -To do so, run +1. Check that you have [conda](https://docs.conda.io/en/latest/) installed. +To do so, run ```sh conda list ``` -2. Run +2. Run ```sh ./create_environment ``` -to generate the environment and install the dependencies. +to generate the environment and install the dependencies. 1. `cd` into the [python](../python) directory. ### Setup using virtualenv -1. Check that [virtualenv](https://github.com/pyenv/pyenv) is installed, if not then run +1. Check that [virtualenv](https://github.com/pyenv/pyenv) is installed, if not then run ```sh pip install virtualenv ``` @@ -42,10 +42,102 @@ pip install -r requirements.txt ## Starting the notebooks 1. Make sure the `albatross` virtual environment is activated. -2. `cd` into to the [tutorials](../tutorials) directory. -3. Run +2. `cd` into to the [tutorials](../tutorials) directory. +3. Run ```sh jupyter notebook ``` -to start up the IPython notebooks in your browser. +to start up the IPython notebooks in your browser. + +## Launching the tutorials using Docker + +Docker provides an isolated environment with all necessary dependencies pre-installed, making it the easiest way to get started with the Albatross tutorials without worrying about local Python environment conflicts. + +### Prerequisites + +1. Install [Docker](https://docs.docker.com/get-docker/) on your system +2. Ensure Docker is running by checking: + + ```sh + docker --version + ``` + +### Step-by-step Docker setup + +1. **Navigate to the albatross root directory** + + ```sh + cd /path/to/albatross + ``` + +2. **Pull the Jupyter Data Science notebook image** + + ```sh + docker pull jupyter/datascience-notebook:latest + ``` + + This image contains Jupyter Lab with popular data science libraries (numpy, pandas, matplotlib, scipy, etc.) pre-installed. + +3. **Launch the Docker container** + + ```sh + docker run -ti -p 8888:8888 -v `pwd`:/home/jovyan jupyter/datascience-notebook:latest + ``` + + **Command breakdown:** + - `-ti`: Run in interactive mode with a TTY + - `-p 8888:8888`: Map port 8888 from container to host + - `-v \`pwd\`/albatross:/home/jovyan`: Mount the albatross directory into the container + - The container will start and display a URL with a token + +4. **Access Jupyter Lab** + + Copy the URL from the terminal output (it will look like `http://127.0.0.1:8888/lab?token=...`) and paste it into your browser, or simply go to [http://127.0.0.1:8888/lab](http://127.0.0.1:8888/lab) and enter the token when prompted. + +5. **Install Albatross-specific requirements** + + Once Jupyter Lab is open, click on the "Terminal" tile in the launcher to open a terminal, then run: + + ```bash + pip install -r python/requirements.txt + ``` + + This installs additional packages required for the tutorials: + - `emcee`: MCMC sampling library + - `gpflow`: Gaussian Process library + - `pyproj`: Cartographic projections + - `seaborn`: Statistical visualization + - And other dependencies + +6. **Start working with tutorials** + + Navigate to the `tutorials/` folder in the file browser and open any of the available notebooks: + - `tutorial_1_one_dimension.ipynb` - Introduction to 1D Gaussian Processes + - `tutorial_2_maximum_likelihood_estimation.ipynb` - Parameter estimation + - `tutorial_3_one_dimension_sparse.ipynb` - Sparse GPs for scalability + - `tutorial_4_kalman_fliter_equivalent.ipynb` - Time series applications + - `tutorial_5_evaluating_uncertainty.ipynb` - Uncertainty quantification + +### Troubleshooting + +- **Port 8888 already in use**: If you get a port binding error, either stop the existing service using port 8888 or use a different port: + + ```sh + docker run -ti -p 8889:8888 -v `pwd`/albatross:/home/jovyan jupyter/datascience-notebook:latest + ``` + + Then access via [http://127.0.0.1:8889/lab](http://127.0.0.1:8889/lab) + +- **Permission issues**: On Linux/macOS, you might need to add your user to the docker group or run with `sudo` + +- **Volume mounting issues**: Ensure you're running the command from the albatross root directory + +### Stopping the container + +To stop the container, press `Ctrl+C` in the terminal where Docker is running, or run: + +```sh +docker ps # Find the container ID +docker stop +``` From f783d12799dcb278d173c80eda01a61206a7027e Mon Sep 17 00:00:00 2001 From: Miquel Garcia Date: Thu, 7 Aug 2025 19:36:26 +0200 Subject: [PATCH 2/2] Address clarifications for Docker-based execution of tutorials Hopefully clarifies questions posted by @jbangelo and @IsakTjernberg (thanks!) --- tutorials/README.md | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/tutorials/README.md b/tutorials/README.md index 8634b69f..9dcf85f9 100644 --- a/tutorials/README.md +++ b/tutorials/README.md @@ -65,13 +65,7 @@ Docker provides an isolated environment with all necessary dependencies pre-inst ### Step-by-step Docker setup -1. **Navigate to the albatross root directory** - - ```sh - cd /path/to/albatross - ``` - -2. **Pull the Jupyter Data Science notebook image** +1. **Pull the Jupyter Data Science notebook image** ```sh docker pull jupyter/datascience-notebook:latest @@ -79,23 +73,24 @@ Docker provides an isolated environment with all necessary dependencies pre-inst This image contains Jupyter Lab with popular data science libraries (numpy, pandas, matplotlib, scipy, etc.) pre-installed. -3. **Launch the Docker container** +2. **Launch the Docker container** ```sh - docker run -ti -p 8888:8888 -v `pwd`:/home/jovyan jupyter/datascience-notebook:latest + docker run --rm -ti -p 8888:8888 -v /path/to/albatross:/home/jovyan jupyter/datascience-notebook:latest ``` **Command breakdown:** + - `--rm`: Remove the residuals of the container after stopping it. - `-ti`: Run in interactive mode with a TTY - `-p 8888:8888`: Map port 8888 from container to host - - `-v \`pwd\`/albatross:/home/jovyan`: Mount the albatross directory into the container + - `-v /path/to/albatross:/home/jovyan`: Mount the albatross directory into the container's `work` directory. Note: `jovyan` is the main user folder, and its contents will be shown in the Jupyter lab file browser when the service is launched. - The container will start and display a URL with a token -4. **Access Jupyter Lab** +3. **Access Jupyter Lab** Copy the URL from the terminal output (it will look like `http://127.0.0.1:8888/lab?token=...`) and paste it into your browser, or simply go to [http://127.0.0.1:8888/lab](http://127.0.0.1:8888/lab) and enter the token when prompted. -5. **Install Albatross-specific requirements** +4. **Install Albatross-specific requirements** Once Jupyter Lab is open, click on the "Terminal" tile in the launcher to open a terminal, then run: @@ -110,7 +105,7 @@ Docker provides an isolated environment with all necessary dependencies pre-inst - `seaborn`: Statistical visualization - And other dependencies -6. **Start working with tutorials** +5. **Start working with tutorials** Navigate to the `tutorials/` folder in the file browser and open any of the available notebooks: - `tutorial_1_one_dimension.ipynb` - Introduction to 1D Gaussian Processes @@ -124,7 +119,7 @@ Docker provides an isolated environment with all necessary dependencies pre-inst - **Port 8888 already in use**: If you get a port binding error, either stop the existing service using port 8888 or use a different port: ```sh - docker run -ti -p 8889:8888 -v `pwd`/albatross:/home/jovyan jupyter/datascience-notebook:latest + docker run --rm -ti -p 8889:8888 -v `pwd`:/home/jovyan jupyter/datascience-notebook:latest ``` Then access via [http://127.0.0.1:8889/lab](http://127.0.0.1:8889/lab)