Add guide to run tutorials using a Jupyter Docker image

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,97 @@ 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. **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.
+
+2. **Launch the Docker container**
+
+   ```sh
+   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 /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
+
+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.
+
+4. **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
+
+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
+   - `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 --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)
+
+- **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 <container_id>
+```