Offline workshop on a Raspberry Pi

This guide is for teachers. One Raspberry Pi 5 with 8 GB of memory can run the whole of doQumentation for a classroom: the tutorials, the search, and the Qiskit code that participants run from their own phones and laptops. On the day you need no internet and no cloud account.

You type a few commands into the Pi's terminal. Each one is shown in full, so you can copy and paste it. You do not need to be a programmer.

Running a workshop in the cloud instead (IBM Code Engine, more than about 20 people)? See the Workshop Setup Guide.

What you need​

• A Raspberry Pi 5 with 8 GB of memory, its power supply, and a microSD card or SSD with at least 8 GB free (the image takes about 4 GB).
• Raspberry Pi OS (64-bit), the current version. If you use a RasQberry Pi, the image is already there; see rasqberry.org for its Workshop & Qiskit Server menu entry. The rest of this page still applies.
• A screen and keyboard for the Pi, or a laptop that connects to it.
• For more than about 10 participants: a small travel Wi-Fi router (see The network).

Participants need only a web browser. Nothing is installed on their devices.

Before the day (at home, with internet)​

Do this a few days ahead, so there is time to fix a problem.

1. Install Podman​

Open a terminal on the Pi and run:

sudo apt update
sudo apt install -y podman qrencode

podman runs the doQumentation image; qrencode makes the QR code for participants.

Already use Docker? That works too: write docker wherever this page says podman. The commands are otherwise the same.

2. Download the image​

podman pull ghcr.io/janlahmann/doqumentation:jupyter

This downloads about 1.3 GB and needs about 3.9 GB on the Pi's disk. It contains the website, a Jupyter server and Qiskit with its simulators. Download it again before each workshop to get the latest version.

3. Start it​

podman run -d --name doq --restart unless-stopped \
  -e JUPYTER_TOKEN=choose-a-teacher-password \
  -p 8080:80 -p 127.0.0.1:8888:8888 \
  ghcr.io/janlahmann/doqumentation:jupyter

What each part does:

The defaults are already right for a classroom; you don't need to set these, but you can, each with another -e:

To change a switch, remove the container (podman rm -f doq) and run the podman run command again with the new -e value.

4. Test it​

Wait about 30 seconds, then open http://localhost:8080 in the Pi's browser. Open the Hello world tutorial and click Run on the first code cell. The first run takes a few seconds; you should see a small circuit drawing.

Then test from a second device, as described in How participants open the site.

5. After a reboot​

Podman does not start the container again by itself after the Pi is switched off and on. After each start of the Pi, run:

podman start doq

(With Docker, --restart unless-stopped also covers reboots, so this step is not needed.)

The network​

Participants' devices must be on the same network as the Pi. There are two ways.

Recommended: your own network. The Pi provides it, so nothing at the venue can get in the way. Either

• turn the Pi into a Wi-Fi hotspot. Good for a small group, about 10 devices. Run once:

  sudo nmcli device wifi hotspot ifname wlan0 ssid Quantum password quantum2026
  sudo nmcli connection modify Hotspot connection.autoconnect yes
  

  Participants join the Wi-Fi Quantum with the password quantum2026 (choose your own). The Pi's address on this network is 10.42.0.1, so the site is at http://10.42.0.1:8080. While the Pi is a hotspot, its Wi-Fi cannot also be connected to the internet; a network cable still can.

• or bring a small travel router and connect the Pi to it with a network cable. This carries more devices than the Pi's own Wi-Fi. The router needs no internet connection. Find the Pi's address as shown below.

Possible: the venue's network. This works if participants and the Pi are on the same Wi-Fi and the network lets devices reach each other. Guest and school networks often block exactly that ("client isolation"); then participants see nothing at all. Test it on site with one phone before people arrive. The address must start with 10., 172.16. to 172.31. or 192.168.; on other addresses the Run buttons do not appear. If either fails, switch to your own network.

How participants open the site​

Find the Pi's address:

hostname -I

The first number is the address, for example 192.168.1.23. The site is at http://<that address>:8080, for example http://192.168.1.23:8080.

Make a QR code that participants can scan with their phone camera. To show it in the terminal:

qrencode -t ansiutf8 http://10.42.0.1:8080

Or save it as a picture for a slide or a printed handout:

qrencode -s 12 -o workshop-qr.png http://10.42.0.1:8080

(Use your own address instead of 10.42.0.1.) Write the address under the QR code as well, for laptops without a camera. Prefer the number address to a name like raspberrypi.local: names ending in .local do not work on some Android phones and managed Windows laptops.

What works without internet, and what doesn't​

Check the pages you plan to use at home, with the Pi's network only and the internet unplugged.

How many participants?​

Plan for up to 15 participants on a Pi 5 with 8 GB. 20 is the upper limit, and only if everyone keeps to one page at a time.

How we measured it: we ran the image under Podman on a machine with the same 4 processor cores (arm64) and 8 GB as a Pi 5. We opened Python sessions the way the site does and ran the Hello world tutorial in each: a circuit drawing, an ideal and a noisy simulation, two histograms. Memory as shown by podman stats:

Each session that has run code takes about 0.3 GB. Raspberry Pi OS itself needs about 1 GB, so 20 sessions fill a Pi 5 with 8 GB almost completely; 15 leave room for surprises.

Memory is the limit. Every page on which a participant has clicked Run keeps its own Python session, and the session stays open as long as that page is open, even after the participant has moved on to another page in the same tab. Twenty participants who each ran code on two pages use 40 sessions, about 12 GB, which is more than the Pi has. So:

• Ask participants to work on one page at a time and close tabs they no longer need.
• At a break, or if it gets slow, restart (see the next section).

The processor sets the speed. The Pi 5 has 4 cores, and participants who run code at the same moment share them. In our test, Hello world from top to bottom took about 10 seconds for one person alone and about 30 seconds each when 10 people started it at the same second. A Pi 5 is slower than the machine we measured on, so expect longer waits there. The first Run on a page takes longest, because it loads Qiskit. Larger simulations take longer and slow everyone down; stagger the heavier exercises instead of starting the whole room on them at once.

During the workshop: if it gets slow​

See how many Python sessions are open:

curl -s http://localhost:8080/api/kernels | grep -o '"id"' | wc -l

See how much memory and processor time the container uses:

podman stats --no-stream doq

If memory is close to the limit, or pages respond slowly, restart. This closes every participant's Python session, takes about 20 seconds, and keeps the website and your settings:

podman restart doq

Tell participants first: after the restart they click Run again, starting from the first cell of their page, because their variables are gone. The open pages reconnect by themselves.

In JupyterLab (on the Pi only: open http://localhost:8888 and enter your teacher password) you can also see the open sessions under Running Terminals and Kernels and close single ones.

Between groups​

Restart between two groups, so the next group starts with a clean Pi and none of the previous group's files:

podman restart doq

Troubleshooting​

A note on trust​

All participants share one Python environment on the Pi. Anyone on the network can run any Python code there, including code that reads or deletes other participants' files or stops their sessions. That is fine for a class; do not keep personal data or passwords in the container, and restart between groups.

After the workshop​

Stop it:

podman stop doq

Remove it completely, including the downloaded image, to free about 4 GB:

podman rm -f doq
podman rmi ghcr.io/janlahmann/doqumentation:jupyter

Turn the hotspot off again, if you used it:

sudo nmcli connection down Hotspot
sudo nmcli connection modify Hotspot connection.autoconnect no

Checklist​

Print this part.

Days before (with internet)

• Pi 5, 8 GB, Raspberry Pi OS 64-bit, at least 8 GB free on disk
• podman pull ghcr.io/janlahmann/doqumentation:jupyter (about 1.3 GB)
• Container started with the podman run command above
• Hello world runs on the Pi (http://localhost:8080)
• The pages you plan to use work with the internet unplugged
• Hotspot set up, or travel router and network cable packed
• QR code and written address on a slide or handout

On the day, before people arrive

• Pi on, podman start doq, wait 30 seconds
• One phone on the workshop Wi-Fi: open the address, click Run on a cell
• Tell participants: one page at a time, close tabs you are done with

During and after

• If slow: podman stats --no-stream doq, then podman restart doq at a break
• Between groups: podman restart doq
• At the end: podman stop doq