Build Gramine app
In this tutorial, you will learn how to build and run a Confidential Computing application with the Gramine TEE framework.
Prerequisites:
For demo purposes, we omitted some development best practices in these examples.
Make sure to check your field's best practices before going to production.
Create a directory tree for your application in
~/iexec-projects/.cd ~/iexec-projects
mkdir tee-hello-world-app && cd tee-hello-world-app
iexec init --skip-wallet
mkdir src
touch Dockerfile
Make sure your
chain.json content is as follows:{
"default": "bellecour",
"chains": {
"bellecour": {}
}
}
When your sources are copied, your are ready to dockerize your application:
Javascript
Python
Dockerfile
FROM iexechub/iexec-gramine-base:0.10.0
RUN apt-get update \
&& apt-get install -y curl \
&& curl -fsSL https://deb.nodesource.com/setup_14.x | bash - \
&& apt-get install -y nodejs \
&& rm -rf /var/lib/apt/lists/*
ARG SOURCE_DIR=src
ARG GRAMINE_DIR=gramine
# Get the code of app to /workplace/app
COPY $SOURCE_DIR/app.js /workplace/app
# Set the main function for node app, no need for binnary app
RUN sed -i "s#MAIN_FUNC=#MAIN_FUNC=/workplace/app/app.js#" /apploader.sh
WORKDIR /workplace/app
# Install required node dependencies (needs to be ran after WORKDIR has been specified)
RUN npm install [email protected]
# Copy the manifest to use from within the base image
# or create your own
RUN cp /common-manifests/nodejs.entrypoint.manifest /entrypoint.manifest
# Finalize app (finalize manifest and sign app)
RUN /finalize-app.sh
Dockerfile
FROM iexechub/iexec-gramine-base:0.10.0
### Install python and required dependencies
RUN apt-get update \
&& apt-get install -y python3 \
&& rm -rf /var/lib/apt/lists/*
ARG SOURCE_DIR=src
ARG GRAMINE_DIR=gramine
# get the code of app to /workplace/app
COPY $SOURCE_DIR/app.py /workplace/app
# set the main function for python and node app, no need for binnary app
RUN sed -i "s#MAIN_FUNC=#MAIN_FUNC=/workplace/app/app.py#" /apploader.sh
WORKDIR /workplace/app
# Install required dependencies
RUN pip3 install pyfiglet
# Copy the manifest to use from within the base image
# or create your own
RUN cp /common-manifests/python.entrypoint.manifest /entrypoint.manifest
# Finalize app (finalize manifest and sign app)
RUN /finalize-app.sh
Build the docker image.
docker build . --tag <docker-hub-user>/tee-gramine-hello-world:1.0.0
Push your image on DockerHub:
docker push <docker-hub-user>/tee-gramine-hello-world:1.0.0
Congratulations, you just built your Gramine TEE application.
At this stage, your application is ready to be tested on iExec. The process is similar to testing any type of application on the platform, with these minor exceptions:
Gramine TEE applications require some additional information to be filled in during deployment.
# prepare the Gramine TEE application template
iexec app init --tee-framework gramine
Edit
iexec.json and fill in the standard keys and the mrenclave object:{
...
"app": {
"owner": "<your-wallet-address>", // starts with 0x
"name": "tee-gramine-hello-world",
"type": "DOCKER",
"multiaddr": "docker.io/<docker-hub-user>/tee-gramine-hello-world:1.0.0", // update it with your own DockerHub username
"checksum": "<checksum>", // starts with 0x, update it with your own image digest
"mrenclave": {
"framework": "GRAMINE",
"version": "v0",
"fingerprint": "<mrenclave>" // no 0x prefix, see how to retrieve it below
}
},
...
}
Run your Gramine TEE image with
sps=unset to get the enclave fingerprint (mrenclave):docker run --rm -e sps=unset <docker-hub-user>/tee-gramine-hello-world:1.0.0
The run is expected to fail but you should look for a
mr_enclave field in your logs: mr_enclave: dcec6d7f76520cb996d6e9dac105b9c3d75c7bb4a4d8f3669f6101cbca6aff4f
Hint: The
mr_enclave is also available in your logs when building your app.Deploy the app with the standard command:
iexec app deploy --chain bellecour
Specify the tag
--tag tee,gramine in iexec app run command to run a tee app.# initialize the storage
iexec storage init --chain bellecour --tee-framework gramine
You are now ready to run the app
iexec app run --tag tee,gramine --workerpool debug-v8-bellecour.main.pools.iexec.eth --watch --chain bellecour
You noticed we used
debug-v8-bellecour.main.pools.iexec.eth instead of an ethereum address, this is an ENS name. The ENS (Ethereum Name Service) protocol enables associating decentralized naming to ethereum addresses.If your task does not complete and the error is related to Gramine, you might see following output:
[error] get keys failed, return -[<ERROR_CODE>]
Error code | Error message | Description | Action |
|---|---|---|---|
111 | Unreachable SPS | The SPS is not reachable or offline. | |
9984 | Invalid SPS Certificate | The SSL certificate of the SPS is not signed by a Certificate Authority you trust. | You might be using a <version> of the Gramine base (iexechub/iexec-gramine-base:<version>) which is too old. Verify the <version> to use in the documentation or please contact iExec Help Center. |
30952 | Unexpected MRENCLAVE | The measurement of the enclave does not match your on-chain configuration of your deployed dapp "fingerprint": "<mrenclave>". |
You have built and run your Gramine application, you can now go further with:
Last modified 1mo ago