OpenCAPIF SDK Development Environment Installation
Before proceeding, ensure you have fulfilled the necessary requirements.
Follow the steps below to install the OpenCAPIF SDK for development purposes:
Requisites
Developers must have the following tools installed:
- pyenv
Installation Steps
1. Set Up a Python Environment with pyenv
Follow these steps to create and activate a virtual environment using pyenv:
# Install Python 3.12 using pyenv
pyenv install 3.12
# Create a virtual environment for the SDK
pyenv virtualenv 3.12 pesp_sdk_env
# Activate the virtual environment
source path/to/.pyenv/versions/pesp_sdk_env/bin/activate
OPTIONAL step: sometimes Apple Mac shells raise issues while finding the shell path. If this happens, try this command:
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
OPTIONAL step: For Arm64 architecture sometimes will appear this problem
Last 10 log lines:
__locale_localeconv in _localemodule.o
__locale_localeconv in _localemodule.o
__locale_localeconv in _localemodule.o
__locale_localeconv in _localemodule.o
"_libintl_textdomain", referenced from:
__locale_textdomain in _localemodule.o
ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make: *** [Programs/_freeze_module] Error 1
make: *** Waiting for unfinished jobs....
This article explains how to solve it
2. Clone GitHub repository:
git clone https://labs.etsi.org/rep/ocf/sdk.git
#Then move to the pesp_capif_sdk folder
cd /the/path/to/pesp_capif_sdk
3. Install the Python requirements listed in requirements.txt file:
cd installation
python -m pip install --upgrade pip
pip install -r requirements.txt
Congratulations! The installation of OpenCAPIF SDK has finished.
Testing the SDK
Unit tests
The unit tests check the SDK without a running OpenCAPIF: CAPIF and the AEFs are simulated (test/unit/fake_capif.py), so the tests can check the requests sent by the SDK, the files it writes and the errors it raises. They cover the onboarding, update and offboarding of providers and invokers, the publication of APIs, discovery, security context and tokens, API invocation, event subscriptions, API invocation logs, the API schema translator, the generation of keys and CSRs, and the configuration from files and environment variables. Run them from the root of the repository with:
make unit_tests
It runs python -m pytest test/unit with the Python of the repository venv if it exists, or python3 otherwise (choose another one with make unit_tests PYTHON=/path/to/python). Running it as python -m pytest from the repository root makes the tests use the code of the repository, and not an opencapif_sdk installed in your environment.
To run them without a local Python environment, only with Docker:
make unit_tests_docker
It builds a Docker image with the dependencies of installation/requirements.txt, the SDK code and the tests (test/Dockerfile), and runs the unit tests in a container. The image uses Python 3.13 by default; set PYTHON_IMAGE to use another version, e.g. make unit_tests_docker PYTHON_IMAGE=python:3.9-slim (with Python 3.12 or earlier, the tests that need TLS-PSK are skipped).
The unit tests also run in the staging CI pipeline (staging_unit_tests job) with make unit_tests_docker, so the runner only needs Docker.
The other tests of the test folder are integration tests that need a running OpenCAPIF.
End-to-end tests
To check that the SDK works end to end (for example, after a change), run ci_cd_test/test_sdk.sh against a running OpenCAPIF. If there is no OpenCAPIF available, ci_cd_test/prepare_capif_for_sdk.sh deploys one locally and creates the test user.
bash ci_cd_test/test_sdk.sh
The script builds a Docker image with the SDK from the current SDK working tree, attaches it to the capif-network Docker network, and runs these steps with the testing samples:
- Provider: onboarding and publishing of a test API, exposed by three AEFs, one per security method: OAUTH, PKI and PSK.
- Provider: start of the three AEF servers, which only answer the invokers authenticated with their security method: an access token signed by CAPIF for that AEF (OAUTH), a certificate signed by the CAPIF CA (PKI), or the AEF_PSK that the AEF gets from CAPIF (PSK).
- Invoker: onboarding, discovery of the published API, security context, access token, invocation of the API at each AEF with
invoke_api()(checking that the AEF authenticated the invoker with the expected security method, and that it rejects requests without credentials), and offboarding. - Provider: stop of the AEF servers and offboarding. It always runs, even if a previous step failed, to leave OpenCAPIF clean.
The PSK check requires OpenCAPIF 5.1.0 or later. To check only some security methods, set SDK_TEST_SECURITY_METHODS, e.g. SDK_TEST_SECURITY_METHODS=OAUTH,PKI bash ci_cd_test/test_sdk.sh.
The script exits with code 0 only if every step succeeds. If any step fails, it shows which one, with its error, and exits with code 1, so it can be used to stop a pipeline.
In the staging CI pipeline, the staging_local_install job deploys OpenCAPIF with prepare_capif_for_sdk.sh and then runs this script.