AlgoViz

If you want to update AlgoViz, read this.

Local Installation

Instead of the Docker image, you can also install Jupyter Lab and AlgoViz locally. The instructions can be found here:

AlgoViz is an extension for Jupyter Notebook that is used in courses of the working group Didactics of Computer Science. It enables the programming of interactive graphics and provides a range of visualizations and tools that can be used in Python, C++ and Typescript or JavaScript.

We provide the image uosddi/algoviz via Docker Hub. It includes:

A Jupyter Lab installation
The Python kernel
A modified version of the kernel tslab for TypeScript/JavaScript
The extension AlgoViz

The image requires...

a port on the host system
a directory on the host that will be mounted into the container as volume /opt/repos.

What is a Docker Image?

Docker is a system for virtualization, i.e. it allows you to simulate another computer on a computer, the so-called host.

This is called guest. A Docker images is basically the hard drive of a guest computer. It is run with Docker and then provides services via the network interface.

Using a Docker image has the following advantages:

The infrastructure is platform independent.
Technical maintenance is much easier.
You can simply delete the software by deleting the image.
Updating is easy.

The main disadvantage is that an image can be relatively large. This is because it contains a complete operating system.

Hints for Safari Users

In our experience, the Safari browser does not correctly implement all features of Scalable Vector Graphics. Therefore, problems may occur when using Safari.

Therefore, we recommend using a different browser.

The Installation

Step 0: Preparing your working directory

Create a working directory in which you want to store all materials. We recommend an empty directory that has the name of the event, e.g. CS101 for Computer Science 101.

Hint!

Do not use spaces, umlauts or special characters in directory or file names. Limit yourself to Latin letters and numbers.

Step 1: Installing Docker

The first step is to install Docker on your own computer. This is also called host because it is the host for the virtual machine simulated by Docker. We will use Docker Desktop, a graphical interface for managing images.

Download the version of Docker Desktop that is suitable for the host system (your computer) from https://www.docker.com and install it. Under Windows and MacOS, installation shouldn't be a problem. Under Linux, it depends on the distribution you use.

Step 2: The image

After installing Docker Desktop, open a Terminal (Linux/MacOS) or the Command Prompt (Windows) and enter the following command:

docker pull uosddi/algoviz:latest

The image will then be downloaded, but this may take a while as it is about 2 GB in size. Continue with the next step when the download is finished.

Step 3: Starting the image for the first time

Start Docker Desktop. You should find it in the usual application menus.

After starting (may take a while), select the Images entry in the menu on the left. The window should then look something like this:

If you move the mouse over the entry uosddi/algoviz, a button with the inscription RUN appears on the right. Press it. This opens the following dialog:

Click on Optional Settings. The dialog then looks something like this. However, no values have been entered yet.

Enter the values shown in the Local Host and Container Path fields (i.e. 8888 and /opt/repos).

You can assign the Container Name as you wish. It would be useful to use the event abbreviation.

Click on the three dots in the Host Path input field.

A dialog opens in which you can select your working directory from Step 0.

Tip

Do not use spaces, umlauts or special characters for directory or file names. Limit yourself to Latin letters and numbers (A-Z, a-z, 0-9) and the underscore _. Experience shows that spaces and special characters cause problems sooner or later.

When you have selected a directory, click Run. This starts a virtual machine that runs the image. This is called a Docker container.

If the start was successful, Docker switches to the Containers tab. A menu with a series of entries opens under the three vertical dots. Open with browser opens a web browser and displays a login page. The password is empty. So just press ENTER.

A few more hints

Where are the notebooks stored?

When you first started the program, you specified a directory on your computer, the Host Path. The materials and your notebooks are stored in this directory. You can access the files even if the container is not running. They are completely normal files.

Which browser can I use?

The OPEN IN BROWSER button starts your standard browser. In our experience, not all browsers are equally suitable. The best option is Chrome and its derivatives, e.g. Chromium or Edge. Mozilla Firefox should not cause any problems either. Safari, on the other hand, can cause problems. We therefore recommend that you either set one of the suitable browsers as your standard browser or start the browser yourself and "surf" the following URL:

http://localhost:8888 (bookmarks are quite useful).

The later starts

If you want to start the container again later, go DIRECTLY to the container view in Docker Desktop and start the container. DO NOT START THE IMAGE AGAIN! This would create another container! Once the container has started, open the browser using OPEN IN BROWSER. Alternatively, you can open a browser after starting and go to the URL https://localhost:8888

The Material

The materials for events are stored in various repositories. In the AlgoViz menu you will find the entry Add repository. Call it up and enter the following information in the dialog that opens:

The name of a new directory to be created for the repository.
The URL of the repository
The branch for the event

You can choose the name freely. We strongly recommend that you avoid special characters and spaces. Only use lowercase and uppercase letters, numbers and the underscore "_".

The URL and the branch will be communicated to you during the respective event.

After you have added the repository, a button for the repo (short for repository) will appear in your workspace. If you click on it, your material will be automatically updated.

Computer Science 101

Recommended name: cs101
URL: https://gitdid.informatik.uni-osnabrueck.de/vorlesungen/cs101/public_en.git
Branch: main

Einführung in die Algorithmik

Empfohlener Name: algo
URL: https://gitdid.informatik.uni-osnabrueck.de/vorlesungen/algo/public.git
Branch: ss2024

Updates

Von Zeit zu Zeit wird AlgoViz aktualisiert. In diesen Fällen sollten Sie ihr Docker Image bzw. die lokale Installation ebenfalls aktualisieren.

Update of the Docker Image

The update of the Docker Image woks as the first start.

Pullen the current image uosddi/algoviz:latest.
Delete your old Container.
Create a new Container with the same parameters as the old one.

The old Image still exists with the Tag <none>. Delete ist.

Update of the local installation

Run the following command in your conda environment:

pip install algoviz --upgrade

That's it.