Template repository for JavaScript and C++ CCF applications.
Quickstart
The quickest way to build and run this sample CCF app is to checkout this repository locally in its development container by clicking:
All dependencies will be automatically installed (takes ~2 mins on first checkout).
Alternatively, if your organisation supports it, you can checkout this repository in a Github codespace:
JavaScript
CCF apps can be written in JavaScript/TypeScript. This is the quickest way to develop new apps as this does not require any compilation step and the app can be updated on the fly, via a governance proposal.
The JavaScript sample bundle is located in the js/
directory.
Run JS app
$ npm --prefix ./js install
$ npm --prefix ./js run build
$ /opt/ccf/bin/sandbox.sh --js-app-bundle ./js/dist/
[12:00:00.000] Virtual mode enabled
[12:00:00.000] Starting 1 CCF node...
[12:00:00.000] Started CCF network with the following nodes:
[12:00:00.000] Node [0] = https://127.0.0.1:8000
[12:00:00.000] You can now issue business transactions to the libjs_generic application
[12:00:00.000] Loaded JS application: ./js/dist/
[12:00:00.000] Keys and certificates have been copied to the common folder: /workspaces/ccf-app-template/workspace/sandbox_common
[12:00:00.000] See https://microsoft.github.io/CCF/main/use_apps/issue_commands.html for more information
[12:00:00.000] Press Ctrl+C to shutdown the network
In another terminal:
$ curl -X POST https://127.0.0.1:8000/app/log?id=1 --cacert ./workspace/sandbox_common/service_cert.pem -H "Content-Type: application/json" --data '{"msg": "hello world"}'
$ curl https://127.0.0.1:8000/app/log?id=1 --cacert ./workspace/sandbox_common/service_cert.pem
hello world
Docker
It is possible to build a runtime image of the JavaScript application via docker:
$ docker build -t ccf-app-template:js-enclave -f docker/ccf_app_js.enclave .
$ docker run --device /dev/sgx_enclave:/dev/sgx_enclave --device /dev/sgx_provision:/dev/sgx_provision -v /dev/sgx:/dev/sgx ccf-app-template:js-enclave
...
2022-01-01T12:00:00.000000Z -0.000 0 [info ] ../src/node/node_state.h:1790 | Network TLS connections now accepted
# Now the CCF service is started and member governance is needed to allow trusted users to interact with the deployed application
Or, for the non-SGX (a.k.a. virtual) variant:
$ docker build -t ccf-app-template:js-virtual -f docker/ccf_app_js.virtual .
$ docker run ccf-app-template:virtual
Network governance
The CCF network is started with one node and one member, you need to execute the following governance steps to initialize the network
- Activate the network existing member to start a network governance
- Build the application and create a deployment proposal
- Deploy the application proposal, using governance calls
- Create and submit an add users proposal
- Open the network for users (using proposal)
Bare VM
The application can be tested using cchost
on Linux environment.
To start a test CCF network on a Linux environment, it requires CCF to be intalled or you can create a CCF-enabled VM using Creating a Virtual Machine in Azure to run CCF
# Start the CCF network using the cchost in
# Enclave mode
/opt/ccf/bin/cchost --config ./config/cchost_config_enclave_js.json
# Or Virtual mode
/opt/ccf/bin/cchost --config ./config/cchost_config_virtual_js.json
...
# Now the CCF network is started and further initialization needed before the interaction with the service
The CCF network is started with one node and one member, please follow the same governance steps as Docker to initialize the network and check CCF node config file documentation
Managed CCF
The application can be tested using Azure Managed CCF (Pre-release phase)
, you can create Azure Managed CCF serivce on your subscription, that will give you a ready CCF network
- First, create the network's initial member certificate, please check Certificates generation
- Create a new Azure Managed CCF serivce (the initial member certificate required as input)
- Build the application and create a deployment proposal
- Deploy the application proposal, using governance calls
- Create and submit an add users proposal
C++
CCF apps can also be written in C++. This offers better performance than JavaScript apps but requires a compilation step and a restart of the CCF node for deployment.
The C++ sample app is located in the cpp/
directory.
Also check out the code tour to get an overview of the C++ app.
Build C++ app
In the checkout of this repository:
$ cd cpp/
$ mkdir build && cd build
$ CC="/opt/oe_lvi/clang-10" CXX="/opt/oe_lvi/clang++-10" cmake -GNinja ..
$ ninja
$ ls
libccf_app.enclave.so.signed # SGX-enabled application
libccf_app.virtual.so # Virtual application (i.e. insecure!)
See docs for complete instructions on how to build a CCF app.
Run C++ app
$ /opt/ccf/bin/sandbox.sh -p ./libccf_app.virtual.so
Setting up Python environment...
Python environment successfully setup
[12:00:00.000] Virtual mode enabled
[12:00:00.000] Starting 1 CCF node...
[12:00:00.000] Started CCF network with the following nodes:
[12:00:00.000] Node [0] = https://127.0.0.1:8000
[12:00:00.000] You can now issue business transactions to the ./libccf_app.virtual.so application
[12:00:00.000] Keys and certificates have been copied to the common folder: .../ccf-app-template/build/workspace/sandbox_common
[12:00:00.000] See https://microsoft.github.io/CCF/main/use_apps/issue_commands.html for more information
[12:00:00.000] Press Ctrl+C to shutdown the network
Or, for an SGX-enabled application (unavailable in development container): $ /opt/ccf/bin/sandbox.sh -p ./libccf_app.enclave.so.signed -e release
Docker
It is possible to build a runtime image of the C++ application via docker:
$ docker build -t ccf-app-template:cpp-enclave -f docker/ccf_app_cpp.enclave .
$ docker run --device /dev/sgx_enclave:/dev/sgx_enclave --device /dev/sgx_provision:/dev/sgx_provision -v /dev/sgx:/dev/sgx ccf-app-template:cpp-enclave
...
2022-01-01T12:00:00.000000Z -0.000 0 [info ] ../src/node/node_state.h:1790 | Network TLS connections now accepted
# It is then possible to interact with the service
Or, for the non-SGX (a.k.a. virtual) variant:
$ docker build -t ccf-app-template:cpp-virtual -f docker/ccf_app_cpp.virtual .
$ docker run ccf-app-template:virtual
Dependencies
If this repository is checked out on a bare VM (e.g. for SGX deployments), the dependencies required to build and run the C++ app can be installed as follows:
$ wget https://github.com/microsoft/CCF/releases/download/ccf-2.0.0/ccf_2.0.7_amd64.deb
$ sudo dpkg -i ccf_2.0.7_amd64.deb # Install CCF under /opt/ccf
$ cat /opt/ccf/share/VERSION_LONG
ccf-2.0.7
$ /opt/ccf/getting_started/setup_vm/run.sh /opt/ccf/getting_started/setup_vm/app-dev.yml # Install dependencies
See the CCF official docs for more info and Modern JavaScript application development.
Code Tour
In VSCode, a code tour of the C++ app can be started with: Ctrl + P, > CodeTour: Start Tour