iExec tools

Appearance

🛠️ Build and deploy your first iApp ​

Reading time 🕒 10 mins

Time to build!

Let's build an iApp that can process protected data in a secure environment.

An iApp runs in a Trusted Execution Environment (TEE), it can process data in a secure environment.

This guide will help you set up, test, deploy and run your iApp using the iapp-cli tool. Follow the instructions carefully for a smooth development experience.

📋 Prerequisites ​

Before getting started, ensure you have the following:

📦 Node.js v20+
Download →
🐳 Docker
Download →
🐳 Docker Hub Account
Sign Up →

Don't worry! All secrets used in this tutorial stay on your machine and aren’t shared with anyone. You’ll only need them to run the iApp run command.

💾 Installation (win / mac / linux) ​

First, you need to install the iapp package. Open your terminal and run:

sh
npm i -g @iexec/iapp

You can check if the installation was successful by running:

sh
#checking the version
iapp --version

#checking the available commands
iapp --help

🛠️ Initialize Framework ​

To initialize the working directory for developing your iApp, use the iapp init command. This command sets up the necessary project structure and files.

sh
mkdir iexec-test
cd iexec-test
iapp init

You will be prompted with the following message:

txt
  ___    _    ____  ____
 |_ _|  / \  |  _ \|  _ \
  | |  / _ \ | |_) | |_) |
  | | / ___ \|  __/|  __/
 |___/_/   \_\_|   |_|

✔ What's your project name? (A folder with this name will be created) … hello-world
✔ Which language do you want to use? › JavaScript
? What kind of project do you want to init? › - Use arrow-keys. Return to submit.
❯   Hello World - iapp quick start
    advanced
1Pick a name for your project
txt
? What's your project name? (A folder with this name will be created) ...
2Select a programming language for your project
txt
? Which language do you want to use? › - Use arrow-keys. Return to submit.
❯   JavaScript
    Python
3Select the type of project you want to init
txt
? What kind of project do you want to init? › - Use arrow-keys. Return to submit.
❯   Hello World - iapp quick start
    advanced

We recommend selecting "Hello World" to quickly discover how iApp works! use advanced only if you are familiar with iExec.

txt
✔ [Chosen language] app setup complete.
✔ Generated ethereum wallet (0xD4A28d.........................)

  • An iApp project is setup with the selected language

  • An ethereum wallet has been created (we use it to sign the iApp creation onchain)

  • A new folder has been created, it contains a very simple application, with the main code being located in src/app.js or src/app.py

🧪 Test Your iApp ​

To test your iApp, run iapp test command

sh
iapp test

It uses your local docker to build and execute the app.

- If you have Error: Docker daemon is not accessible Make sure Docker is installed and running.


- If you have Error: Failed to locate iApp project root error: Ensure you are in your project folder before proceeding.

You can see the output of the computation by saying yes to the question:

txt
? Would you like to see the result? (View ./output/) (Y/n)

🧩 Using Arguments ​

You can pass arguments to your iApp using the --args option. This allows you to provide necessary inputs during runtime (you can use your name for example).

sh
iapp test --args your-name

🔒 Using Protected Data ​

You can pass a protectedData that you are authorized to process to your iApp using the --protectedData option.

Since nothing is actually deployed during testing, we use Protected Data mocks to test the app. Using --protectedData default will provide your app with the default protectedData mock.

sh
iapp test --protectedData default

You can check how args and protectedData are processed in src/app.js or src/app.py

🚀 Deploy Your iApp ​

Deploy your iApp on the iExec protocol.

1Go to Docker Hub Security Settings
2Click "Personal access tokens" → "Generate new token"
3Name it "Test iExec iApp CLI" (expiration date is optional)
4Select "Read & Write" permissions
5Save your token securely and your username

Once you have your token, you can deploy your iApp using the following command:

sh
# you need your username and the access token (it can take a few minutes to deploy)
iapp deploy

📝 Make sure to save your iApp address after deployment - you'll need it later!

You can find your iApp address in the iexec-app.json file in your project folder.


⚠️ If you encounter issues during deployment, make sure Docker's BuildKit feature is enabled and supports AMD64 architecture:

sh
docker buildx inspect --bootstrap | grep -i platforms

The output should include linux/amd64 in the list of supported platforms. If not, update to the latest Docker Desktop version which includes these requirements.


⚠️ If you set the wrong Docker username, you can change it by editing the iapp.config.json file

🏃 Run Your iApp ​

Now you can run your application:

sh
iapp run <my-iapp-address>

To sum up the process, we take the iApp and wrap it in the iExec framework, allowing it to run securely in a Trusted Execution Environment (TEE) for confidential computing. If you want to explore further, you can check the protocol documentation here.

🎉 Congratulations! You've successfully deployed and run your first iApp on iExec. This is a significant milestone - your application is now ready to securely process confidential data in a trusted environment.

🎯 Key takeaways ​

🔒
iApps: Special applications that run in TEEs to process protected data
🛠️
iApp CLI: Command-line tool for building, testing, and deploying iApps
🔐
Protected Data: Can be integrated and processed securely in your iApp
⛓️
Deployment: Apps are deployed on iExec protocol to run in trusted environments

Next up: Alice will learn how to authorize the iApp and Bob to access and use her protected data! 🚀