Workshop Setup Guide

This guide helps instructors set up doQumentation for live workshops and classes with up to 50 participants. Each participant gets their own Jupyter kernel for running Qiskit code directly in the browser.

How it works​

For workshops, we deploy multiple Code Engine instances (each running a Jupyter server) and distribute participants across them. Each participant's browser is assigned to one instance and sticks to it for the session. If an instance goes down, affected users automatically reconnect to another one.

Prerequisites​

• IBM Cloud account with Code Engine access (free tier available)
• GitHub repo access to trigger the deploy workflow
• A Jupyter token (32+ characters) shared across all instances

Cost estimates​

Instances scale to zero when idle — no charges outside the workshop.

Before the workshop (day before)​

1. Deploy instances​

Go to Actions > "Code Engine Image" > Run workflow and set:

• instance_count: number of instances (see cost table above)
• cpu: vCPUs per instance (4 recommended for workshops)
• memory: memory per instance (8G recommended)

Wait for the workflow to complete (~5 min). The output includes a workshop URL.

2. Set the Jupyter token​

If this is your first deployment, set the JUPYTER_TOKEN environment variable on each instance:

ibmcloud ce project select --name ce-doqumentation-01
for i in 01 02 03; do
  ibmcloud ce app update --name "ce-doqumentation-${i}" \
    --env JUPYTER_TOKEN="your-secure-token-here" \
    --env CORS_ORIGIN="https://doqumentation.org"
done

3. Generate the workshop URL​

The deploy workflow outputs a base64-encoded config. Replace SET_YOUR_TOKEN_HERE with your actual token:

# Example: 3 instances
CONFIG='{"pool":["https://ce-doqumentation-01.xxx.eu-de.codeengine.appdomain.cloud","https://ce-doqumentation-02.xxx.eu-de.codeengine.appdomain.cloud","https://ce-doqumentation-03.xxx.eu-de.codeengine.appdomain.cloud"],"token":"your-secure-token-here"}'
echo -n "$CONFIG" | base64

The workshop URL is: https://doqumentation.org/jupyter-settings#workshop=<BASE64>

4. Run a quick stress test​

pip install aiohttp websockets
python scripts/workshop-stress-test.py \
  --pool https://ce-01...,https://ce-02...,https://ce-03... \
  --token your-secure-token-here \
  --users 10 --cells-per-user 2 --simple

5. Warm up instances​

Visit each CE URL once in your browser, or run the stress test with --users 1. This ensures instances aren't cold-starting when participants arrive.

Share with participants​

Share the workshop URL via:

• QR code on a slide
• Paste in chat (Zoom, Slack, etc.)
• Email before the workshop

Participants click the link — everything is auto-configured. No IBM Cloud account needed for participants.

During the workshop​

Monitor instances​

Open Settings > Code Engine — the workshop panel shows instance status:

Click Refresh to update kernel counts.

Scale up if needed​

If instances are struggling (high memory, slow execution):

1. Re-run the deploy workflow with a higher instance_count
2. Copy the new instance URL(s) from the IBM Cloud console
3. Click Update Pool in the workshop panel to add them
4. New participants are automatically distributed to the new instances
5. Existing participants keep their current instance (no disruption)

If an instance goes down​

Affected participants see a brief reconnection — their browser automatically connects to another instance. The code cells are still visible in the page, but kernel state (variables) is lost. Participants can re-run their cells.

After the workshop​

No cleanup needed — instances scale to zero after ~10 minutes of idle time.

To delete instances entirely:

ibmcloud ce project select --name ce-doqumentation-01
ibmcloud ce app delete --name ce-doqumentation-02 --force
ibmcloud ce app delete --name ce-doqumentation-03 --force

Verify spending:

bash scripts/ibmcloud-spending-limit.sh

Troubleshooting​

Quick reference​

# Deploy 3 instances for a 50-person workshop
GitHub Actions > Code Engine Image > Run workflow
  instance_count=3, cpu=4, memory=8G

# Generate workshop URL
echo -n '{"pool":["URL1","URL2","URL3"],"token":"TOKEN"}' | base64

# Share: https://doqumentation.org/jupyter-settings#workshop=BASE64

# Monitor: Settings > Code Engine > Instance Status > Refresh

# Scale up: Add instances via workflow, then Update Pool in settings

# After: Instances auto-scale to zero. No action needed.