In the following, we briefly introduce you to Docker. For specifics to PI2 , ML/DL, and LSDM, click on the respective link.
Before starting the local development environment, you need to install Docker. If you have no prior experience with Docker, please refer to the introductory material available on the official Docker website.
To use Docker on Windows install the Docker Desktop. We encourage you to use the WSL2 (Windows Subsystem for Linux) as backend. You can find the download link and corresponding installation instructions here.
Docker in the WSL can use up too many resources. We therefore limit the RAM usage with the following commands.
Create the file
C:\Users\<username>\.wslconfig
with the following content
[wsl2]
memory=3GB
You can adapt the memory usage to your system. Furthermore, you can limit the
amount of processors used by adding processors=1.
On Windows you always need to start Docker first manually. Open Docker Desktop and click the little Docker icon in the bottom left corner to start the engine.
To use Docker on Mac install the Docker Desktop. You can find the download link and corresponding installation instructions here.
On Linux you have multiple installation options.
You can install docker using apt (preferred in Debian/Ubuntu). Please follow the official instuctions given here.
Alternatively, Docker provides a useful convenience script to install the engine with the following commands.
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh
For more information see here.
Alternatively, you can install docker using a single command on Ubuntu using Snap. Note: the version provided by snap can be an older one. We recommend using the convenience script instead.
sudo snap install docker
Clone this repository and go into the root directory of the repository by typing the following commands in a terminal:
git clone https://github.com/uma-pi1/pi1-docker
cd pi1-docker
Alternatively, you can click on the "Code" button on the top right of this page and click "Download ZIP". Then you need to decompress the ZIP file into a new folder.
With an installed Docker environment and a started engine you can now run the Docker containers.
Note: The first time you are running the commands below will take some time depending on your notebook and internet connection. So feel free to grab some coffee.
It will only take that long the first time you run this command. All following start-ups should be quick.
This will run all provided containers:
docker compose up -d
You usually want to use the pi1_main container only. Start this using
docker compose up -d pi1-main
Note for Windows users: it might be that you do not have write access in the
shared/ folder. In that case, first run prepare_host.sh. For this, open a
linux shell, turn the script into an executable, then run it.
chmod +x prepare_host.sh
./prepare_host.shThen run docker compose up --build.
If the pi1-docker repository was updated during the term, run
git pull
docker compose up --build -d
in the pi1-docker folder.
Use the Docker Desktop GUI or run the following command in the root folder of the repository to start the main container:
docker compose up -d pi1-main
The container will run until you stop it using the GUI or
docker compose down
All files placed in the folder ./shared located in the root directory of this
repository on your host machine will directly appear in your container in the
folder shared. And vice versa, of course.
Open a browser and enter http://localhost:8889 to open JupyterLab. You have the option to open a terminal or notebooks for multiple different languages.
If you see a prompt asking you for a token or password type pi1.
In our lectures, we are making use of
Jupytext, a tool to
synchronize plain Python files with Jupyter notebooks. In this Docker container,
Jupytext is already installed. This means that you are able to open and edit
plain Python files as a notebook. You will notice that upon saving your edits, a
notebook file (with ipynb file extension) will be created. Changes in either
file (py or ipynb) will be synchronized to the other one.
Note: If Python files are not opened as a notebook directly, right-click the file, click "Open With", then select "Notebook".
You can run programs using the terminal in JupyterLab. But you can also do it non-interactively or interactively from the shell.
-
List Running Containers: If you don't know the exact container name, list the running containers to get the container ID or name.
docker ps
-
Execute a Command: Run your command via the container
sh docker exec -it <container_name> <command>For example, to run a Python script inside
pi1-main:docker exec -it pi1-main python3 shared/myprogram.py
Attach to the container's interactive shell using the docker exec command with
bash.
-
Attach to the Shell: Use the
docker execcommand to attach to the container's shell.docker exec -it <container_name> /bin/bash
-
Execute programs: Once you are inside the container's shell, you can execute programs as you would in a regular terminal.
For example, to compile and run a C program:
gcc -o myprogram myprogram.c ./myprogram
-
Close the shell again: Ctrl+D.
The default user name in JupyterLab and the pi1-main notebook is jovyan. For
more information see
here.
""Jovyan is often a special term used to describe members of the Jupyter community. It is also used as the user ID in the Jupyter Docker stacks or referenced in conversations."
For the lecture Praktische Informatik II (PI2), the Docker environment contains:
- clang
- nasm
- Java
- Python
- JupyterLab with Java and C kernels
For the lectures "Machine Learning (ML)" and "Deep Learning (DL)", the Docker environement contains:
- JupyterLab with Python kernel
- Relevant Python packages including matplotlib, pandas, NumPy, PyTorch, and TensorBoard