Skip to main content
This project is in beta. Found a bug? Open a GitHub issue. Question or idea? Ask in Discussions — we'd love your feedback!

⚙️ doQumentation Settings

Configure the Jupyter server used for executing Python code in tutorials.

Current: Not detected

Server Backend

Choose which backend to use for code execution:

Execution Mode

Choose what happens when you click Run on tutorial pages. This applies to embedded code execution on this site only — opening a notebook in JupyterLab uses the standard Qiskit runtime.

Changes take effect on the next kernel session. If code is running, click Back then Run to apply.

IBM Quantum Account

Setup instructions & security notes
Security note: Credentials are stored in plain text in this browser's localStorage, for this language site only (on another language site, enter them again). They are never put in a cookie, so they are not sent to the web host. They are not encrypted and can be read by browser extensions or anyone with access to this device. Use the expiry setting below to limit exposure, and delete credentials when you're done. For shared or public computers, prefer the manual save_account() method described below instead.

Enter your IBM Quantum credentials once here. They will be auto-injected via save_account() when the kernel starts, so you don't need to enter them in every notebook. This applies to embedded code execution on this site only — opening a notebook in JupyterLab requires calling save_account() manually.

  1. Register at quantum.cloud.ibm.com/registration (free, no credit card required)
  2. Create an instance — go to Instances, click "Create instance +", select the Open (free) plan, and follow the wizard
  3. Copy CRN — back on the home page, find your instance under "Instances" and click the copy icon next to "CRN"
  4. Create API key — on the home page, find "API key" and click "Create +"

Need more help? See IBM's authentication guide for screenshots and detailed steps.

Alternative: Run save_account() manually in a notebook cell

If you prefer not to store credentials in this browser, paste this into any code cell and run it. Credentials are saved in the Binder kernel's temporary storage and lost when the session ends.

from qiskit_ibm_runtime import QiskitRuntimeService
QiskitRuntimeService.save_account(
    token="YOUR_API_TOKEN",
    instance="YOUR_CRN",
    overwrite=True
)

Display Preferences

Code Font Size

14px
from qiskit import QuantumCircuit

Pre-computed Outputs

Each notebook page shows pre-computed outputs (images, tables, text) from IBM's original runs. When you click Run to execute code live, both the original outputs and your new live results are shown. Turn this toggle off to hide the original outputs during live execution, keeping only your results visible.

Python Warnings

By default, Python warnings (deprecation notices, runtime hints) are suppressed for cleaner notebook output. Disable this to see all warnings — useful for debugging or learning about API changes.

Manage Your Data

All data stays in your browser. On doqumentation.org your progress, bookmarks and settings are kept in localStorage and in small cookies that share them across the language sites; those cookies travel to the static web host with each page request, never to a doQumentation server. Your IBM Quantum credentials are never put in a cookie: they stay in localStorage on the language site where you entered them. Clearing your browser data or using a different browser/device starts fresh.

Progress

Visited pages show a ✓ in the sidebar. Notebook pages show a </>: grey until visited, blue once visited, green once you ran code on them.

No progress tracked yet. Visit tutorials and guides to start tracking.

Bookmarks

No bookmarks yet. Use the bookmark button on any page to save it here.

Display & UI

Sessions & Credentials

Reset Everything

Remove all saved data including progress, bookmarks, display preferences, and credentials.

Advanced Settings

IBM Cloud Code Engine

IBM Cloud Code Engine provides a fast, serverless Jupyter kernel powered by your own IBM Cloud account. Startup takes seconds instead of minutes. Free tier covers ~14 hours/month.

Setup Instructions
  1. Create an IBM Cloud account at cloud.ibm.com (free tier available)
  2. Go to the IBM Cloud Code Engine console and create a new project in your preferred region
  3. Create a new application with image ghcr.io/janlahmann/doqumentation-codeengine:latest, listening port 8080
    Sizing: 1 vCPU / 2 GB for single user, 8 vCPU / 16 GB for workshops (up to 80 users)
  4. Set environment variables: JUPYTER_TOKEN to a secure token (min 32 characters) and CORS_ORIGIN to your domain (e.g. https://doqumentation.org)

For workshop sizing details, see the workshop setup documentation.

Binder Packages

When running on GitHub Pages, code executes via MyBinder. The Binder environment includes core Qiskit packages pre-installed:

qiskit[visualization], qiskit-aer,
qiskit-ibm-runtime, pylatexenc,
qiskit-ibm-catalog, qiskit-addon-utils, pyscf

Some notebooks require additional packages. You can install them on demand by running this in a code cell:

!pip install -q <package>

Or install all optional packages at once:

!pip install -q scipy scikit-learn qiskit-ibm-transpiler \
  qiskit-experiments plotly sympy qiskit-serverless \
  qiskit-addon-sqd qiskit-addon-mpf \
  qiskit-addon-aqc-tensor[aer,quimb-jax] \
  qiskit-addon-obp qiskit-addon-cutting ffsim \
  gem-suite python-sat

Setup Help

RasQberry Setup

RasQberry runs the doQumentation container (see Docker Setup below). Open the site from the Pi's address, port 8080, and code runs on the Pi with no further setup.

Offline workshop guide: run a class from one Raspberry Pi

Local Jupyter Setup

Start a Jupyter server that accepts this site only, with a token you choose, then enter its URL and token under Custom Server above:

jupyter server --ServerApp.token='choose-a-long-token' \
  --ServerApp.allow_origin='https://doqumentation.org' \
  --ServerApp.disable_check_xsrf=True

Docker Setup

The Docker container generates a random Jupyter token at startup. Code execution through the website (port 8080) works automatically — no token needed. The token is only required for direct JupyterLab access on port 8888.

To retrieve the token from container logs:

podman logs doq | grep "Jupyter token"

To set a fixed token:

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

Remote Server

For remote servers, ensure CORS is configured to allow connections from this site. Add the following to your jupyter_server_config.py:

c.ServerApp.allow_origin = 'https://doqumentation.org'
c.ServerApp.allow_credentials = True