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
ORCA Backend can be started easily by just running 2 docker containers, as follows :
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://<server_ip>:7474 with credentials neo4j/password to browse the database.
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://<server_ip>: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.
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
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.
Needed for log_manager do following :
python manage.py makemigrations log_manager
python manage.py migrate
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.
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/.
Docker image of orca_backend can be created and container cane started as follows:
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)
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 -
-
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'
export discover_networks="<Device(s) or Network(s) IP.>"
python manage.py test network.test.interface_test