Configuring the environment
Before you can start running experiments on QPUs, you need to configure your environment. In QruiseOS, the procedure to achieve that is extremely simple - you only need to create an API token in the QruiseOS dashboard and create a single, two-line file on your computer - the rest is taken care of by the Qruise software. This page will guide you through the process step-by-step, and at the end you should be ready to start playing with your QPUs!
Creating an API token¶
The first step is to create an API token. Start by navigating to the QruiseOS dashboard in your web browser. If you are not signed in, you will be automatically redirected to the login page.
First time user?
If you don't know the address of the QruiseOS dashboard, ask your system administrator. They should also have prepared a user account for you.
After logging in, click on the "User" menu item in the bottom-left corner:
In the page that opens, locate the API keys section. When you log in for the first time, there will be no keys and it will display a "No API keys created" message:
To create a new key, click on "Create new key". This will open an API key creation page:
In the top of the page you can see the roles matrix for the API key. The leftmost column of the matrix contains the names of QPUs that you have access to. In our example, those are "onboarding-chip" and "my-new-qpu". To the right of the QPU name you will find checkboxes specifying which roles will be assigned to the key, as specified by the topmost row. As you can see, there are three different roles: Reader, Writer, and Admin. You can select only those roles which were assigned to you by your administrator - the rest will be grayed out. In our example, the user has Reader and Writer roles for the "onboarding-chip" QPU, but only a Reader role for "my-new-qpu".
Missing roles or QPUs?
In order to follow along with the remainder of the Getting Started and the User Guides sections (including the example notebooks), the two QPUs – onboarding-chip and my-new-qpu – must first be created following the instructions in Creating a new QPU. Create your API token only after you can see these two QPUs in your dashboard. If either or both of the QPUs are missing or you cannot select a role that you need, contact your system administrator to first create these QPUs and assign you the necessary roles.
You can now select all the roles you wish your API key to have, as well as its name and a description, and click the "Create key" button:
When you click the "Create key" button, the newly created API key will be shown at the bottom of the page:
Copy the API key and save it to your disk - we will need it in the next step.
API keys and security
For security reasons, the API key will only be shown to you when you create it. When you reload the page or close the web browser, it will not be possible to recover it.
Creating an identity file¶
With the API token created, the final step is to create a default identity file. Identity files are small text files used by the Qruise software to identify the user. They are located in the ~/.config/qruise/credentials directory and have an .id extension. To create a default identity file, open the ~/.config/qruise/credentials/default.id file on the machine you want to use QruiseOS on (e.g. using the hosted JupyterHub service in QruiseOS) and paste the previously created key in the following template:
No such file or directory error
It is likely that the directory where you are supposed to store the identity file does not yet exist on your system, in which case you might get a No such file or directory error when trying to open or save the ~/.config/qruise/credentials/default.id file. To fix this, you can first create the required directory with mkdir -p ~/.config/qruise/credentials/ and then use vim or nano to create the identity file with nano ~/.config/qruise/credentials/default.id.
Before you save it, replace the API_TOKEN and QRUISEOS_BACKEND_URL placeholders with real values. For instance, if the QruiseOS server address is https://api.example.com/, then for the token created in the previous section the identity file would look the following:
key: qruise_os_cf10895db9524dea81e98e48b0e95405_51323532e545f024d1c2a3fd11bfbb16a2fa833e3f063c2f5c3af0a936ea8db8
url: https://api.example.com/
QruiseOS server address
If you don't know your QruiseOS server address, ask your team leader or administrator. In the hosted JupyterHub environment within QruiseOS you can use http://qruise-backend:8000/.
In order to check that your API token has been correctly set in the identity file, you can try out the example notebooks in ~/qruise/examples/ on your QruiseOS hosted JupyterHub instance and follow along the User guides section in this documentation.