diff --git a/README.md b/README.md index 4270052..cb3e3de 100644 --- a/README.md +++ b/README.md @@ -2,53 +2,66 @@ This repository contains Jupyter Notebooks that can be used as training materials for understanding how the PDBe REST API works, and provides a number of examples of answering specific questions about PDB entries using the API. -## Getting Started -Either use Binder to use the notebook: +## Getting started with Docker (recommended) -[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/PDBeurope/pdbe-api-training/master) +This option launches the summer school notebooks in a Docker container. This is the recommended way to run the notebooks as it ensures that all dependencies are correctly installed and that the notebooks will run as expected. -Or +Make sure your [Docker](https://docs.docker.com/engine/install/) is running on your machine before executing the following commands: -You will need to have Jupyter installed on your machine. For Linux/OSX machines, simply type: +### Clone the repository +```console +git clone https://github.com/PDBeurope/pdbe-api-training . +cd /path/to/your/pdbe-api-training/ +``` +### Build the Docker container (you only need to do this once) +```console +docker build -t pdbe-api-training . ``` -pip3 install --upgrade pip -pip3 install jupyter + +### Run the Docker container +```console +docker run -p 8888:8888 -v /path/to/your/pdbe-api-training/pdbe_tutorial_2024/:/pdbe_api_tutorial/pdbe_tutorial_2024 pdbe-api-training ``` -For Windows machines (optionally also for Linux/OSX) you can install Jupyter with conda-forge: -https://conda-forge.org/ +Now open your browser and go to `http://localhost:8888/` and you should see the Jupyter Notebook interface. The `-v` flag ensures changes you make to the notebooks will be saved in the `pdbe_tutorial_2024` directory in the repository cloned to your local machine. -### Prerequisites +## Getting started with Binder -If installing using Anaconda, there is no additional prerequisites. If installing using pip3, you will need to have Python3 on your machine, and of course pip3 +Notebooks can also be run on cloud via Binder. Click on the badge below to launch the notebooks in Binder: -### Installing +[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/PDBeurope/pdbe-api-training/master) -From command line on Unix machine these would be the steps setting up everyone: +## Getting started with Python and Jupyter + +You will need to have Python3.10, pip3 and Jupyter installed on your machine. + +### Upgrade pip3 +```console +pip3 install --upgrade pip ``` + +For Windows machines (optionally also for Linux/OSX) you can install Jupyter with conda-forge: +https://conda-forge.org/ + +### Clone the repository + +```console mkdir pdbe_jupyter cd pdbe_jupyter git clone https://github.com/PDBeurope/pdbe-api-training . -jupyter notebook ``` -Jupyter Notebook will open a window in your browser, and you can select the specific notebooks you would like to view. - - -## Install and run with Docker - -Make sure your Docker client is running and then run: - -```shell -cd /path/to/your/pdbe-api-training/ -docker build -t pdbe-api-training . -docker run -p 8888:8888 -v /path/to/your/pdbe-api-training/pdbe_tutorial_2024/:/pdbe_api_tutorial/pdbe_tutorial_2024 pdbe-api-training +### Install the dependencies and start Jupyter +```console +cd pdbe-api-training +pip3 install -r requirements.txt +jupyter ./pdbe_tutorial_2024 ``` -Now open your browser and go to `http://localhost:8888/` and you should see the Jupyter Notebook interface. The `-v` flag ensures changes you make to the notebooks will be saved in the `pdbe_tutorial_2024` directory in the repository cloned to your local machine. +Jupyter Notebook will open a window in your browser, and you can select the specific notebooks you would like to view. ## Authors