ORCA Backend

ORCA Backend is a REST API server written using Django framework to access orca_nw_lib functionalities. It is a backend service that can be used by applications to interact with SONiC Network and devices.

ORCA Backend

Quick Start in 2 simple steps

ORCA Backend can be started easily by just running 2 docker containers, as follows :

Step-1 - Run Neo4j docker container

One of the dependencies for ORCA backend orca_nw_lib uses neo4j to store the network topology. To install neo4j easiest is to run Neo4j Docker image in container with the following command :

docker run --name orca_neo4j -p7474:7474 -p7687:7687 -d --env NEO4J_AUTH=neo4j/password neo4j:latest

To check that neo4j has successfully started, open https://:7474 with credentials neo4j/password to browse the database.

Step-2 - Run orca_backend docker container

Use following command to run orca_backend

docker run --name orca_backend -p 8000:8000 -e neo4j_url="<server_ip>" -d stordis/orca_backend:latest

NOTE: Replace "<server_ip>" with neo4j server ip.

Container runs on 0.0.0.0:8000 by default. To verify that container has successfully started, try to access http://:8000/admin/ and log in with default user/password- admin/admin which is by default created.

Thats it, If thats enough, rest of the steps below can be skipped and directly proceed with quick start of orca_ui, which again is as simple as running a docker container and there discover your topology. Else, refer below for more details about build and installation of ORCA backend.

NOTE: Several settings have default values if not overriden by environment variables. For more details refer Configuration section below.

Running orca_backend from source

Step-1 - Install ORCA Backend dependencies

ORCA backend uses poetry for installing all required dependencies. Poetry can be installed using the following command :

      pip install poetry

To install all dependencies of ORCA backend use the following command :

      git clone https://github.com/STORDIS/orca_backend.git
      cd orca_backend
      poetry install
      poetry shell

Troubleshoot: if "poetry install" stuck for long, perform cleanup as follows: poetry env remove --all \ poetry cache clear --all . rm -rf $(poetry config cache-dir)/artifacts If issue not resolved, check poetry output in verbose mode as follows :\ poetry -vvv install \ In the output if install process is stuck at "[keyring.backend] Loading macOS" try setting :\ export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring

Step-2(optional) - Configuration

Device and DB access configurations of orca_backend is configured in ORCA Network Library Config File. All the config parameters defined in this file can simply be overridden by environment variables with the same name as defined in the config file. Example -

    export discover_networks="10.10.229.50"
    export device_username=admin
    export device_password=YourPaSsWoRd

Similarly, when starting orca_backend container, use it like:

  docker run -d --name orca_backend \
    -p 8000:8000 \
    -e discover_networks="10.10.229.50" \
    -e device_username="admin" \
    -e device_password="YourPaSsWoRd" \
    -e neo4j_url="<server_ip>" \
    stordis/orca_backend:latest

NOTE: Replace "<server_ip>" with neo4j server ip.

ORCA Network Library Config File is actually the part of one of the dependencies of orca_backend, and the file is installed under site_packages/orca_nw_lib/ directory of python environment being used.

Step-3 - Make Migrations

Needed for log_manager do following :

      python manage.py makemigrations log_manager
      python manage.py migrate

Step-4 - Create Django User

Create Django user as follows :

      cd orca_backend
      python manage.py createsuperuser

The user created here can be used to login to server via orca_ui, or making rest calls using postman etc.

Step-5 - Finally, Run ORCA Backend

orca_backend runs like normal django server as follows:

      python manage.py runserver

To verify that django server has successfully started, try accessing (replace localhost with your server address) - http://localhost:8000/ , Here all the Rest endpoint should be listed. Or to perform admin tasks access- http://localhost:8000/admin/.

Install ORCA UI

Build and install orca_backend docker image from source

Docker image of orca_backend can be created and container cane started as follows:

Create docker image

First create the docker image as follows:

    cd orca_backend
    docker build -t orca_backend .

If docker image is to be transferred to other machine to run there, first save the image, transfer to desired machine and load there as follows:

    docker save -o orca_backend.tar.gz orca_backend:latest
    scp orca_backend.tar.gz <user_name>@host:<path to copy the image>
    ssh <user_name>@host
    cd <path to copy the image>
    docker load -i orca_backend.tar.gz

Docker container can be started as follows:

  docker run--name orca_backend -p 8000:8000 -e neo4j_url="<server_ip>" -d orca_backend

Note - Above command will also create a default django super user with username/password - admin/admin consider changing password afterwards at http://localhost:8000/admin/ (replace localhost with orca_backend server address)

APIs and ORCA UI

Users can always use orca_ui which already implements the orca_backend APIs and straight forward when it comes to use ORCA as a whole client server application, User can still use orca_backend REST APIs with out using orca_ui to develop custom apps for example. For a quick start, APIs can be directly used from browser with django rest framework's web interface or from Postman like tools. URLs are available under network/urls.py. Before using APIs a user authentication is required as well. Following is the procedure to use orca_backend APIs using simple curl -

Steps to Use APIs

Create superuser in Django orca_backend using the command below:
```
    cd orca_backend
    python manage.py migrate
    python manage.py createsuperuser
```
user_name and password is sufficient to start with.

After creating the superuser, use the following login API to generate a token for the user created above:

    curl --location 'http://localhost:8000/auth/login' \
    --header 'Content-Type: application/json' \
    --data-raw '{
            "username": "<username>",
            "password": "<password>"
    }'

Example Response:

{
    "token": "f2cb8adc5c0fadc0b38b9505c93378515f96dc98"
}

Use the generated token above in subsequent API requests by including it in the request header with the key named "Authorization":

curl --location 'http://localhost:8000/interfaces?mgt_ip=10.10.130.210' \
--header 'Authorization: Token f2cb8adc5c0fadc0b38b9505c93378515f96dc98'

To execute tests

    export discover_networks="<Device(s) or Network(s) IP.>"
    python manage.py test network.test.interface_test

STORDIS / orca_backend

readme