ARA Jupyter Notebooks

ARA Jupyter Notebook provides an environment for experimenters to write their experiments in Python, which can then be shared with the community to enable reproducibility and collaborative development. ARA Jupyter Notebooks function similarly to a standard Python JupyterHub, allowing users to execute the ARA experiment workflow through Python code snippets. In other words, ARA users can reserve resources, launch containers, and execute commands within the containers using Python.

To work with Jupyter Notebook, ARA provides a Python library called araclient, which includes functions for various stages of the ARA experiment workflow. When using Jupyter Notebook, the currently active project is used for creating leases and launching containers.

Note

To work with ARA Jupyter Notebooks, we recommend having basic familiarity with the Python programming language and JupyterHub environments. For an introduction to JupyterHub, you may refer to the following resources: (1) Jupyter Notebook in 10 minutes and (2) Jupyter Notebook Tutorial: Introduction, Setup, and Walkthrough.

To access the Jupyter Notebook environment, clink on the Project -> Jupyter Notebook menu from the ARA Portal dashboard, as highlighted by the red rectangle in the figure below.

The menu redirects you to the Jupyter Notebook environment, where you can click on the Python 3 (ipykernel) option (highlighted in the red rectangle in the figure below) to create a new notebook for writing your Python program.

The Jupyter Notebook environment appears as shown below:

../_images/Jupyter_Notebook_Environment.png

Using ARA Jupyter Notebook

On this page, we demonstrate how to use ARA Jupyter Notebooks to create a lease, launch a container on the lease, run a command inside the container, delete the container, and finally delete the lease.

Import the araclient library.
```
import araclient
```
Create a lease on an ARA resource. To create a lease, use the function create_lease(args) where args is a dictionary containing lease attributes such as lease name, start date, end date, resource site, resource type, device type, device ID, center frequency, and bandwidth. An example of creating a lease on a sandbox node (e.g., Sandbox-Host-001) is as follows:
```
demo_lease_info = {
'lease_name': 'Demo_Lease_1',
'start_date': '',
'end_date': '',
'site': 'Sandbox',
'resource_type': 'AraRAN',
'device_type': 'Host',
'device_id': '001',
'center_frequency': '',
'bandwidth': ''
}

demo_lease_ob = araclient.create_lease(demo_lease_info)
```
The create_lease() function returns a lease object containing information about the lease. You can view the lease details by printing the lease object as shown below:
```
print(demo_lease_ob)
```
The details of lease will be displayed as follows:
```
Lease ID: 1f25a8e7-8b3f-4976-8ced-9d15848f141d
Lease Name: Demo_Lease_1
Lease Duration: 2025-04-29T04:39:00.000000 -- 2025-04-29T09:39:00.000000
Lease Status: PENDING
```
The Lease Status will initially be in PENDING state and may take a few seconds to become ACTIVE. You can check the current state of a lease using the get_lease_status() function as shown below:
```
print(demo_lease_ob.get_lease_status())
```
You can create multiple leases using the APIs mentioned above. To list all your leases, use the following function:
```
leases = araclient.list_lease()
print(leases)
```
The function returns a list of lease objects that you have created. The output looks as follows:
```
[<araclient.Lease object at 0x7f5f31f8b6a0>]
```
Once the lease is created and ACTIVE, we can create container on the created lease using the next step.

Once you the lease is created, in the ARA Portal, you can see the lease is created and active from the Project -> Reservations -> Leases menu.
For creating container on the reserved resource, ARA provides a create_container() function with arguments being the name of the container, container image, command, and network. The function is called on the lease object on which you want to launch the container. An example is as follows:
```
demo_container_ob = demo_lease_ob.create_container('demo_container', 'arawirelesshub/ara-ubuntu:22.04', 'bash', 'ARA_Shared_Net')
print(demo_container_ob)
```
The function creates a container and returns an object pointing to the container.
```
Container ID: 0e93aaec-bc55-41a4-b903-b607878b46dd
Container Name: demo_container
Container Image: arawirelesshub/ara-ubuntu:22.04
Container Command: ['bash']
Container Status: Creating
Container Host: None
Container Created Time: 2025-04-29 05:00:19.573388
Container Project ID: fda38a8656bf435b86d2de0d7870ec41
Container Environment: {}
Container IP Adress: ['10.0.4.149']
Container Floating IP: 192.168.1.1
```
Similar to the lease, the container will be in Creating state at the beginning. You can use the function get_container_status() to get the recent state of the container.
```
print(demo_container_ob.get_container_status())
```
Further, you can list all containers using the following function.
```
containers = araclient.list_container()
print(containers)
```
The function generates a list the container objects as follows.
```
[<araclient.Container object at 0x7f5f30d6f400>]
```
Once the container is created, you can see the containers in the Project -> Container -> Containers menu in the ARA dashboard.
Once the container is created, we can run commands within the container from the Jupyter Notebook using the function execute(cmd) with the argument cmd being the command in string format. For example, the ls command for listing the files inside the root directory can be executed within the container as follows.
```
output = demo_container_ob.execute('ls /')
print(output)
```
The execute() function run the provided command in the container corresponding to the container object, from where the function is called, and returns the output back as a string. The above command returns the list of files in the root directory as follows.
```
Command successfully executed.
Output: bin
boot
dev
etc
home
lib
lib32
lib64
libx32
media
mnt
opt
proc
root
run
sbin
srv
sys
tmp
usr
var
```

We can run commands required for our experiments through the execute() function.

Once the commands are execute, i.e., the experiment is complete, we can delete the container using the delete() function on the respective container object.
```
demo_container_ob.delete()
```
Once the container is deleted, the function throws the following output.
```
'Container was successfully deleted.'
```
After deleting the container, the lease can be deleted using the delete() function on the lease object as follows.
```
demo_lease_ob.delete()
```
On successful deletion of the lease, the function returns the following message.
```
'Lease was successfully deleted.'
```

Exceptions

For handling exceptions, araclient library defines the following.

Common Exception

This exception is raised when the users authentication token is either invalid or missing from the database. To resolve this, the user must re-login to the portal. Once logged in, the user can access the Jupyter Notebook by selecting the Jupyter menu, which redirects the user to the Jupyter and refresh the authentication token.
Lease Exception

This exception will be raised when there is an issue while listing, creating, and deleting leases.
Container Exception

This exception will be triggered when there is issue while listing, creating, executing commands, and deleting container.