Installation Guide
==================

This guide provides instructions for installing satorbis-kit from AWS CodeArtifact.

Prerequisites
-------------

Before installing satorbis-kit, ensure you have:

* Python 3.8 or higher
* pip package manager
* AWS CLI installed and configured
* Access to the AWS CodeArtifact repository

Installation Steps
------------------

1. Export AWS Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~

First, ensure your AWS credentials are properly configured. You can export them as environment variables:

.. code-block:: bash

   export AWS_ACCESS_KEY_ID=<your-access-key-id>
   export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
   export AWS_SESSION_TOKEN=<your-session-token>  # Optional, if using temporary credentials can get from the console

Alternatively, configure AWS CLI:

.. code-block:: bash

   aws configure

2. Get Authorization Token
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Retrieve the authorization token from AWS CodeArtifact:

.. code-block:: bash

   aws codeartifact get-authorization-token \
     --domain satorbis \
     --domain-owner 590183684378 \
     --region ap-south-1 \
     --query authorizationToken \
     --output text

.. note::
   - Domain: ``satorbis``
   - Domain Owner: ``590183684378``
   - Region: ``ap-south-1``
   - Repository: ``p-platform-services-satorbis``

3. Install the Package
~~~~~~~~~~~~~~~~~~~~~~

Install satorbis-kit using pip with the CodeArtifact repository:

.. code-block:: bash

   pip install satorbis-kit \
     --extra-index-url https://aws:<AUTH_TOKEN>@satorbis-590183684378.d.codeartifact.ap-south-1.amazonaws.com/pypi/p-platform-services-satorbis/simple/

.. important::
   Replace ``<AUTH_TOKEN>`` with the authorization token from step 2.

   Complete example with token:

   .. code-block:: bash

      AUTH_TOKEN=$(aws codeartifact get-authorization-token \
        --domain satorbis \
        --domain-owner 590183684378 \
        --region ap-south-1 \
        --query authorizationToken \
        --output text)

      pip install satorbis-kit \
        --extra-index-url https://aws:${AUTH_TOKEN}@satorbis-590183684378.d.codeartifact.ap-south-1.amazonaws.com/pypi/p-platform-services-satorbis/simple/

Automated Installation Script
------------------------------

For convenience, you can create a script to automate the installation process:

.. code-block:: bash

   #!/bin/bash

   # Configuration
   DOMAIN="satorbis"
   ACCOUNT_ID="590183684378"
   REGION="ap-south-1"
   REPO="p-platform-services-satorbis"
   PACKAGE="satorbis-kit"

   # Get authorization token
   AUTH_TOKEN=$(aws codeartifact get-authorization-token \
     --domain $DOMAIN \
     --domain-owner $ACCOUNT_ID \
     --region $REGION \
     --query authorizationToken \
     --output text)

   # Install the package
   pip install $PACKAGE \
     --extra-index-url https://aws:${AUTH_TOKEN}@${DOMAIN}-${ACCOUNT_ID}.d.codeartifact.${REGION}.amazonaws.com/pypi/${REPO}/simple/

Save this as ``install_satorbis_kit.sh``, make it executable with ``chmod +x install_satorbis_kit.sh``, and run it.

Using pip Configuration File
-----------------------------

For easier management, you can configure pip to always use the CodeArtifact repository by creating or editing ``~/.pip/pip.conf`` (Linux/macOS) or ``%APPDATA%\pip\pip.ini`` (Windows):

.. code-block:: ini

   [global]
   extra-index-url = https://aws:<AUTH_TOKEN>@satorbis-590183684378.d.codeartifact.ap-south-1.amazonaws.com/pypi/p-platform-services-satorbis/simple/

.. warning::
   The authorization token expires after 12 hours by default. You'll need to regenerate and update the token periodically.

Virtual Environment (Recommended)
----------------------------------

It's recommended to install satorbis-kit in a virtual environment:

.. code-block:: bash

   # Create virtual environment
   python -m venv venv

   # Activate virtual environment
   # On Linux/macOS:
   source venv/bin/activate

   # On Windows:
   # venv\Scripts\activate

   # Get authorization token and install satorbis-kit
   AUTH_TOKEN=$(aws codeartifact get-authorization-token \
     --domain satorbis \
     --domain-owner 590183684378 \
     --region ap-south-1 \
     --query authorizationToken \
     --output text)

   pip install satorbis-kit \
     --extra-index-url https://aws:${AUTH_TOKEN}@satorbis-590183684378.d.codeartifact.ap-south-1.amazonaws.com/pypi/p-platform-services-satorbis/simple/

Verifying Installation
-----------------------

After installation, verify that satorbis-kit is installed correctly:

.. code-block:: python

   import satorbis_kit
   print(satorbis_kit.__version__)

Troubleshooting
---------------

Common Issues
~~~~~~~~~~~~~

**Authentication Failed**
   * Ensure your AWS credentials are valid and have the necessary permissions
   * Check that your authorization token hasn't expired
   * Verify that you have access to the CodeArtifact repository

**Package Not Found**
   * Confirm the repository URL is correct
   * Verify the package exists in the CodeArtifact repository
   * Check your network connectivity to AWS

**Permission Denied**
   * Ensure your AWS IAM user/role has the following permissions:
      * ``codeartifact:GetAuthorizationToken``
      * ``codeartifact:ReadFromRepository``
      * ``sts:GetServiceBearerToken``

For more help, please contact your system administrator or refer to the `AWS CodeArtifact documentation <https://docs.aws.amazon.com/codeartifact/>`_.