Installation & Setup
====================

The QHarbor platform consists of two components:

1. DataQruiser App: our graphical user interface to visualize and interact with your data. You can download and install the application from :doc:`dataqruiser_releases`.
2. the qDrive Package: allow you to interact with your measurement data and synchronizing it with the DataQruiser app from python. Below the installation details.

.. .. contents:: Installation overview
..    :local:
..    :depth: 2

Installing the qDrive package
------------------------------

The minimum Python version is Python 3.7.

It is highly recommended to install the qDrive package in a separate environment to prevent conflicts with other Python packages,
especially if older measurement software is in use.

Python environment setup
~~~~~~~~~~~~~~~~~~~~~~~~

To create a new environment and install the qDrive package, open the Anaconda prompt and run:

.. code-block:: console

   conda create -n qdrive_env python=3.11


Activate the environment:

.. code-block:: console

   conda activate qdrive_env

.. note::
   If you wish to install qDrive in an existing environment, you can test its compatibility with the other packages in that environment by cloning the environment, and installing qDrive in the cloned environment:

   .. code-block:: console

      conda create --name myclone --clone my_measurement_env

   After installation, ensure compatibility by importing your commonly used packages.

   **Spyder users** : If you are installing qDrive in the same environment where spyder is installed, ensure Spyder is up to date (i.e. uses ``PyQt5 >= 5.15.0``) to avoid compatibility issues.


.. For Windows, macOS, and Linux (Python Installer)
.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. You can also create a virtual environment using virtualenv. If virtualenv is not installed, run:

.. .. code-block:: console

..    pip install virtualenv

.. The virtual environment can be created with the following commands:

.. .. code-block:: console

..    cd /path/to/your/preferred/location
..    python -m venv qdrive_env
..    source qdrive_env/bin/activate  # (or .\qdrive_env\Scripts\activate on Windows)

.. Now the creation of the virtual environment is complete. Proceed here to install the qDrive package.

.. .. tip:: 
..    Add the following alias to your ``.bashrc`` to simplify activating the environment:

..    .. code-block:: console

..       alias qdrive_env='source /path/to/your/preferred/location/qdrive_env/bin/activate'

..    Then, run ``qdrive_env`` to activate the environment.

Installation
~~~~~~~~~~~~

Once your environment is active, install the qDrive package by running:

.. code-block:: console

   pip install qdrive



.. After installation, launch the synchronization GUI and log in to your account:

.. .. code-block:: console

..    python -c "import qdrive; qdrive.launch_GUI()"




.. note::
   If you encounter errors during installation in an existing environment, it may be due to package dependencies.
   To resolve these, update the relevant package by running:

   .. code-block:: console

      pip install -U package_that_needs_an_update


.. _sync-agent:

Running the Synchronization Agent
---------------------------------

The qDrive package manages data synchronization via a process that starts automatically when the package is imported in Python
(when you run ``import qdrive``). 

To start the synchronization agent GUI and log in, run the following command in the environment where ``qdrive`` is installed:

.. code-block:: console

   python -c "import qdrive; qdrive.launch_GUI()"


Upon login, a persistent login session is established, so you won’t need to log in again unless you log-out.

To log-out click the log-out button in the GUI, or use the command ``qdrive.logout()`` in Python.

To stop or start the synchronization agent, click the Kill/start sync button in the GUI, or use the command ``qdrive.restart_sync_agent()`` in Python.

.. This will show the synchronization agent GUI:

.. .. image:: _static/GUI_qdrive.png
..   :width: 1000

.. note::
      
   You can also log in directly from a Python kernel/console/jupyter-notebook from the environment where ``qdrive`` is installed running:

   .. code-block:: python

      import qdrive
      qdrive.authenticate_with_console()

   When working on a server, you can also authenticate with an :ref:`API-Token <using-api-tokens-for-authentication>`.

.. _using-api-tokens-for-authentication:

Using API-Tokens for Authentication
-----------------------------------

When working on a server, with no graphical environment, you can log in using an API-Token.

An API-Token can be created in the DataQruiser app:

1. Open the DataQruiser app.
2. Click on the account icon (👤) in the top right corner.
3. Navigate to the "API-Tokens" section.
4. Click the "+" button to generate a new token.
5. Enter a descriptive name for your token (e.g., "Synchronization server token").
6. Copy the generated token immediately - it will only be shown once.

Now it is possible to authenticate on the server using your API-Token:

.. code-block:: python

   from qdrive import login_with_api_token

   login_with_api_token('your_api_token@qharborserver.nl')

   # Verify the authentication was successful
   from qdrive.scopes import get_scopes
   print(f"Successfully authenticated. You have access to {len(get_scopes())} scopes.")

.. tip::
   The API-Token is a secret key that should be kept confidential. We do not recommend storing it in any files. 
   If you suspect your API-Token has been compromised, immediately revoke it in the DataQruiser app.

Updating the qDrive package
---------------------------

If the synchronization GUI is open, close it first.

To update qDrive, activate the environment where it was installed and run the following command to update and restart the synchronization agent:

.. code-block:: console

   pip install qdrive --upgrade
   python -c "import qdrive; qdrive.restart_sync_agent(); qdrive.launch_GUI()"