Asoba Ona Documentation

Run notebooks on an edge host

Use JupyterLab to write notebooks interactively and the managed notebook runner to execute a profile and track its progress. Both use the edge notebook workspace. Either answer to the installer prompt leaves jobs stopped.

1. Prepare the workspace

Complete Deploy and keep the extracted bundle. The default workspace is /var/ona/notebooks. If you set ONA_NOTEBOOK_ROOT during installation, use that same directory here. Sign in on the edge host as the operator who owns the workspace. Managed jobs require Docker access and a working NVIDIA container runtime. Host Python needs PyYAML to read job status and verify cleanup. Provision dependencies from an offline package source if the host is disconnected.

2. Set up JupyterLab

On the edge host, install JupyterLab in a dedicated Python environment or use an existing installation. From the extracted bundle, follow the one-time setup in scripts/local/notebooks/README.md to configure the loopback listener and install the systemd unit for your account. Expect the local /lab endpoint to redirect to login. If startup fails, inspect the unit status and confirm the configured Jupyter executable and workspace are accessible to that account.

On your workstation, open a Bash terminal and forward the JupyterLab port. Enter the SSH port configured for your device.

read -r -p "Edge SSH username: " EDGE_USER
read -r -p "Edge host address: " EDGE_HOST
read -r -p "Edge SSH port: " EDGE_PORT
ssh -N -p "$EDGE_PORT" -L 8888:127.0.0.1:8888 "${EDGE_USER}@${EDGE_HOST}"

Leave this terminal open and visit http://127.0.0.1:8888/lab on your workstation. Retrieve the token from ~/.jupyter/ona_notebook.token in a separate SSH session as the notebook operator. If a kernel is killed for exceeding the unit memory limit and JupyterLab remains available, reconnect to Lab and start a fresh kernel.

3. Configure and run a profile

In Bash on the edge host, change to the extracted bundle directory. Save a notebook under the workspace and run the following to copy the example profile. Enter the same version used to install the bundle.

read -r -p "Installed edge release tag: " ONA_EDGE_TAG
export ONA_EDGE_TAG
export ONA_NOTEBOOK_ROOT="${ONA_NOTEBOOK_ROOT:-/var/ona/notebooks}"
cp -n scripts/local/notebooks/profile.example.yaml "$ONA_NOTEBOOK_ROOT/profiles/my_study.yaml"

Expect a profile at profiles/my_study.yaml under the workspace. If it already exists, review it before reuse. Edit its notebook, working directory, output, and status paths relative to the workspace. Keep execution.fresh_kernel: true.

From the same bundle directory and shell, start the profile. This command occupies the terminal until the job exits.

bash scripts/local/notebooks/run_notebook.sh run my_study

Expect a successful job to exit with status zero. To monitor while it runs, open a second SSH session, change to the bundle directory, and set the same workspace and tag in that session.

4. Check status and cleanup

On the edge host, run the status command from the extracted bundle directory. Expect a state and completed-cell count. A failed cell can include its source and traceback.

bash scripts/local/notebooks/run_notebook.sh --status my_study

After the job exits, run cleanup verification from the same directory.

bash scripts/local/notebooks/run_notebook.sh --verify my_study

Expect PASS when the job state is terminal, Compose reports no running notebook job, and the workspace GPU lock is available. A failed job can pass cleanup. If cleanup fails, inspect the job state and running containers before rerunning. If Python reports a missing yaml module, install PyYAML for the host interpreter and retry.