.. _installing: Installing and configuring crandas ===================================== Crandas is a way to interact with the Roseman Labs engine. In order to use crandas, you must have access to an instance of Roseman Labs. The necessary configuration files must be downloaded from the Roseman Labs platform_. Installation ------------- To install crandas, simply run .. code:: bash pip install crandas --index-url=https://pypi.rosemancloud.com Note that crandas is not hosted on `pypi.org `_, so it is necessary to add the server url. The version of crandas must always match the engine version, if you already installed an older version of crandas, you might need to update to the current one: .. code:: bash pip install --upgrade crandas --index-url=https://pypi.rosemancloud.com .. admonition:: Using Jupyter :class: jupyter If you want to use crandas in a Jupyter notebook, you can install the additional packages by adding ``[notebook]``. .. code:: bash pip install crandas[notebook] --index-url=https://pypi.rosemancloud.com We recommend using a virtual environment (``venv``) to run crandas. For more information about virtual environments, see `here `__. .. dropdown:: Working on Windows Windows does not have python installed by default. In that case, you must first install `Python 3.9 or higher `_. Don't forget to tick the box that says **Add python.exe to PATH** to ensure you can run python from any directory. .. admonition:: Using Jupyter :class: jupyter When using Jupyter notebooks in Visual Studio Code, make sure to have the latest versions of packages, as earlier versions of VS Code did not correctly display the progress bar. More information about which package versions are needed can be found `here `__. - ``pip install --force-reinstall -v "ipywidgets >= 7.7.2"`` - ``pip install --force-reinstall -v "jupyterlab_widgets >= 1.1.1"`` Install a specific version of crandas ###################################### To install a specific version of crandas instead run: .. code:: bash pip install --force-reinstall -v crandas== --index-url=https://pypi.rosemancloud.com You can replace ```` with the version of crandas you wish to install, e.g. ``v1.15.3``. Installing the python package is not enough to start using crandas, you also need to configure the settings to connect to the Roseman Labs engine. Configuring crandas -------------------- After installing crandas, you must configure the system to connect to the Roseman Labs engine. This step requires access to the Roseman Labs platform in order to download the necessary configuration file. First of all, you must check that you have the *analyst* role in the platform, this is necessary to perform any analysis. .. tip:: A `video version `_ of these instructions can be found on the Roseman Labs YouTube channel. Crandas can run in either in design mode or in authorized mode. More information about these modes and how they relate to each other can be found on the `help center `_. Downloading the connection file ################################# Follow `these instructions `__ to download the connection file from the platform. The file :code:`.vdlconn` will be downloaded and must be placed in a specific place, depending on your operating system. .. tabs:: .. group-tab:: Linux 1. Using the terminal, create a new :code:`crandas` folder inside the :code:`.config` folder (:code:`mkdir -p ~/.config/crandas`). 2. Move the file :code:`.vdlconn` to the :code:`crandas` folder you just created (:code:`mv ~/Downloads/.vdlconn ~/.config/crandas`) .. group-tab:: Windows 1. Open your home folder: a. Press WIN+R, the Windows Run window should open b. Enter :code:`%HOMEDRIVE%%HOMEPATH%` and press enter. c. A new Windows Explorer window should open that shows your Home folder. 2. In this home folder create a new folder called :code:`.config` (unless it already exists). Note that you might need to do ``CTRL+H`` to see hidden files (as folders starting with a ``.`` are hidden by default) 3. Go inside your :code:`.config` folder and create a new folder named :code:`crandas` 4. Move the file :code:`.vdlconn` to the :code:`crandas` folder you just created. .. dropdown:: Contents of the connection file The connection file contains the URL and certificate for one of the servers, and public keys for the 3 servers to encrypt the uploads and downloads. - **Server public keys**: We have a public key for each of the 3 servers. These keys are used to encrypt input data that is sent towards each server. The crandas client connects to one of the servers and sends the encrypted input data. The connected server, that can only decrypt 1 of the 3 encrypted streams, then forwards the encrypted data to the other two servers. - **Certificate:** When the crandas client connects to the engine, the certificate authenticates the engine server for the client. This ensures that the client is connecting to the correct server. Downloading the analyst key ############################# The analyst key is a cryptographic key that will allow its holder to execute authorized computations. When an analysis is uploaded to the platform by the analyst, it is signed with their analyst key. When executing in authorized mode, this key will be needed to ensure that the analyst that uploaded the analysis is the one who actually executes it (verified with the public key). This key should **remain private**. Follow `these instructions `__ to download the private key from the *authorized* platform. The key must be moved to the same folder as the connection file (``~/.config/crandas``) and renamed to ``analyst.sk``. Alternatively, when using crandas you will need to specify the path to your key when using :func:`connect() <.base.connect>`. .. warning:: This key can only be downloaded **once**. If lost, it will not be possible to execute any analysis, even those that have been previously approved. If that occurs, contact your system administrator. Do not share it with anyone. Using crandas -------------- After installing and configuring crandas, it is just a matter of opening python and importing the package. .. code:: python import crandas as cd # Connect to the engine. The connection file specifies whether to # connect in design or authorized mode cd.connect("") If you do not use the default name ``analyst.sk`` and location for the analyst key as described above (for example, when you have multiple keys from multiple environments), you can specifically choose which analyst key to use as follows: .. code:: python cd.connect("", analyst_key="PATH_TO_ANALYST_KEY") After this, crandas will be ready for us to use it to make secure computations. .. _platform: https://support.rosemanlabs.com/how-to-download-the-connection-file