In order to build, install, and run Hyperledger Avalon a number of additional components must be installed and configured. The following instructions will guide you through the installation and build process for Hyperledger Avalon.
You have a choice of Docker-based build or a Standalone-based build. The Docker-based build is recommended.
Follow the instructions below to execute a Docker-based build and execution.
-
Install Docker Engine and Docker Compose, if not already installed. See PREREQUISITES for instructions
-
Build and run the Docker image from the top-level directory of your
avalon
source repository.Intel SGX Simulator mode (for hosts without Intel SGX):
- Run
sudo docker-compose up --build
- For subsequent runs on the same workspace, if you changed a source or configuration file, run the above command again
- For subsequent runs on the same workspace, if you did not make any
changes, startup and build time can be reduced by running:
MAKECLEAN=0 sudo -E docker-compose up
SGX Hardware mode (for hosts with Intel SGX):
- Refer to Intel SGX in Hardware-mode section in PREREQUISITES document to install SGX pre-requisites and to configure IAS keys.
- Run
sudo docker-compose -f docker-compose-sgx.yaml up --build
- For subsequent runs on the same workspace, if you changed a source or configuration file, run the above command again
- For subsequent runs on the same workspace, if you did not make any
changes, startup and build time can be reduced by running:
MAKECLEAN=0 sudo -E docker-compose -f docker-compose-sgx.yaml up
- Run
-
On a successful run, you should see the message
BUILD SUCCESS
followed by a repetitive messageEnclave manager sleeping for 10 secs
-
Open a Docker container shell using following command
sudo docker exec -it tcf bash
-
To execute test cases refer to Testing section below
-
To exit the Avalon program, press
Ctrl-c
Follow the PREREQUISITES document to install and configure components on which Hyperledger Avalon depends.
This section describes how to get started with Avalon quickly using provided scripts to compile and install Avalon. The steps below will set up a Python virtual environment to run Avalon.
-
Make sure environment variables are set as described in the PREREQUISITES document
-
Choose whether you want the stable version (recommended) or the most recent version
-
To use the current stable branch (recommended), run this command:
git clone https://github.com/hyperledger/avalon --branch v0.5-pre-release.1
-
Or, to use the latest branch, run this command:
git clone https://github.com/hyperledger/avalon
-
-
Change to the Avalon source directory
cd avalon
-
Set
TCF_HOME
to the top level directory of youravalon
source repository. You will need these environment variables set in every shell session where you interact with Avalon. Append this line (withpwd
expanded) to your login shell script (~/.bashrc
or similar):export TCF_HOME=`pwd` echo "export TCF_HOME=$TCF_HOME" >> ~/.bashrc
-
If you are using Intel SGX hardware, check that
SGX_MODE=HW
before building the code. If you are not using Intel SGX hardware, check thatSGX_MODE
is not set or set toSGX_MODE=SIM
. By defaultSGX_MODE=SIM
, indicating use the Intel SGX simulator. -
If you are not using Intel SGX hardware, go to the next step. Check that
TCF_ENCLAVE_CODE_SIGN_PEM
is set. Refer to the PREREQUISITES document for more details on these variables.You will also need to obtain an Intel IAS subscription key and SPID from the portal https://api.portal.trustedservices.intel.com/ Replace the SPID and IAS Subscription key values in file
$TCF_HOME/config/tcs_config.toml
with the actual hexadecimal values (the IAS key may be either your Primary key or Secondary key):spid = '<spid obtained from portal>' ias_api_key = '<ias subscription key obtained from portal>'
-
If you are behind a corporate proxy, then in file
$TCF_HOME/config/tcs_config.toml
uncomment and update thehttps_proxy
line:#https_proxy = "http://your-proxy:your-port/"
If you are not behind a corporate proxy (the usual case), then leave this line commented out.
-
Create a Python virtual environment:
cd $TCF_HOME/tools/build python3 -m venv _dev
-
Activate the new Python virtual environment for the current shell session. You will need to do this in each new shell session (in addition to exporting environment variables).
source _dev/bin/activate
If the virtual environment for the current shell session is activated, you will the see this prompt:
(_dev)
-
Install PIP3 packages into your Python virtual environment:
pip3 install --upgrade setuptools json-rpc py-solc py-solc-x web3 colorlog twisted wheel
-
Build and install Avalon components:
make clean make
-
Build the Avalon SDK Python module:
cd $TCF_HOME/sdk make make install
-
Build the shared key/value storage modules:
cd $TCF_HOME/shared_kv_storage/db_store/packages mkdir -p build cd build cmake .. make cd $TCF_HOME/shared_kv_storage make make install
-
Build the Avalon Listener module:
cd $TCF_HOME/listener make make install
Once the code is successfully built, run the test suite to check that the
installation is working correctly.
Follow these steps to run the Demo.py
testcase:
NOTE: Skip step 1 in the case of Docker-based builds, since
docker-compose.yaml
will run the TCS startup script.
- For standalone builds only:
- Open a new terminal, Terminal 1
cd $TCF_HOME/scripts
- Run
source $TCF_HOME/tools/build/_dev/bin/activate
. You should see the(_dev)
prompt - Run
./tcs_startup.sh -s
The-s
option startskv_storage
before other Avalon components. - Wait for the listener to start. You should see the message
TCS Listener started on port 1947
, followed by a repetitive messageEnclave manager sleeping for 10 secs
- To run the Demo test case, open a new terminal, Terminal 2
- In Terminal 2, run
source $TCF_HOME/tools/build/_dev/bin/activate
. You should see the(_dev)
prompt - In Terminal 2, cd to
$TCF_HOME/tests
and type this command to run theDemo.py
test:cd $TCF_HOME/tests python3 Demo.py --input_dir ./json_requests/ \ --connect_uri "http://localhost:1947" work_orders/output.json
- For Docker-based builds:
- Follow the steps above for "Docker-based Build and Execution"
- Terminal 1 is running
docker-compose
and Terminal 2 is running the "tcf" Docker container shell from the previous build steps - In Terminal 2, cd to
$TCF_HOME/tests
and type this command to run theDemo.py
test:cd $TCF_HOME/tests python3 Demo.py --input_dir ./json_requests/ \ --connect_uri "http://avalon-listener:1947" work_orders/output.json
- The response to the Avalon listener and Intel® SGX enclave Manager can be seen at Terminal 1
- The response to the test case request can be seen at Terminal 2
- If you wish to exit the Avalon program, press
Ctrl-c
A GUI is also available to run this demo. See examples/apps/heart_disease_eval
-
If you see the message
ModuleNotFoundError: No module named '...'
, you did not runsource _dev/bin/activate
or you did not successfully build Avalon -
If you see the message
CMake Error: The current CMakeCache.txt . . . is different than the directory . . . where CMakeCache.txt was created.
then the CMakeCache.txt file is out-of-date. Remove the file and rebuild.
-
Verify your environment variables are set correctly and the paths exist
-
If the Demo test code breaks due to some error, please perform the following steps before re-running:
sudo rm $TCF_HOME/config/Kv*
$TCF_HOME/scripts/tcs_startup.sh -t -s
- You can re-run the test now
-
If you get build errors rerunning
make
, trysudo make clean
first -
If you see the message
No package 'openssl' found
, you do not have OpenSSL libraries or the correct version of OpenSSL libraries. See PREREQUISITES for installation instructions -
If you see the message
ImportError: ...: cannot open shared object file: No such file or directory
, then you need to setLD_LIBRARY_PATH
with:source /opt/intel/sgxsdk/environment
. For details, see PREREQUISITES